== Dolphin 7 Tutorial: My First Module ==


== 1. Getting Started. ==
 
In this tutorial we will create a simple Dolphin module. In the beginning, this module will show a text page only. Then, we will add an admin section for the module. At the end we will create some basic functionality, like a blog system.

In this tutorial we will create a simple Dolphin module. In the beginning, this module will show a text page only. Then, we will add an admin section for the module. At the end we will create some basic functionality, like a blog system.

This tutorial covers things like a simple module structure, creating user pages and admin pages, creating config values for your module, forms and adding admin menu items.

The main purpose of this tutorial is to help you get started with the new Dolphin 7 modules structure and basic functionality.

To proceed with this tutorial you need:

    * already installed Dolphin 7, you can get the latest Dolphin version [http://www.boonex.com/dolphin/download/ here] and detailed installation instructions are [http://www.boonex.com/trac/dolphin/wiki/DetailedInstall70 here].
    * basic PHP knowlege, object oriented programming knowledge is more than welcome. You can learn about PHP [http://www.php.net/ here].
    * basic MySQL queries knowledge, you can learn about MySQL server and MySQL queries syntax [http://www.mysql.com/ here].


The things you will not get in this tutorial:

    * will not teach you PHP, MySQL, Javascript, HTML, CSS
    * will not teach you how to edit and upload files to the server
    * will not teach you about every Dolphin feature. There are many Dolphin features which are more complex, and mentioning them here may detract you from the main purpose of this tutorial. For a complete list of Dolphin programming features and references to the documentation in the code, check [http://www.boonex.com/trac/dolphin/wiki/DolModDev here].
    * will not tech you how to create new templates. A templates creation guide is [http://www.boonex.com/trac/dolphin/wiki/DolDesign here].
    * will not teach you how to translate Dolphin to other languages. A translation manual is [http://www.boonex.com/trac/dolphin/wiki/DolLang here].
    * will not teach security aspects of writing the code. You are responsible if you are hacked through your own module.


Learning Dolphin gives you many advantages:

    * you will be able to make modifications to your site
    * if you are writing a modification, especially as a Dolphin module, it will allow you to transfer your modification more easily between Dolphin version upgrades.
    * you can make money by selling your modifications in [http://www.boonex.com/unity/extensions/home Unity Market] or offering your service for others in the same [http://www.boonex.com/unity/extensions/home Unity Market]. 
    * it will help you to get certified - because there are strict requirements if you want to certify your mod.


Let's start with the simplest thing in the beginning.


==  2. Simplest module. ==

There is a prepared zip package with the simplest Dolphin 7 module here(TODO:bloggie.zip). Download it, unpack and upload to the '''modules/me/''' folder. Most probably there is no me folder in the modules directory, so just create it by yourself. '''Me''' is a vendor name. For the real module, you need to rename it to the real vendor name, but for now '''me''' is fine for everybody. It will be the '''bloggie''' folder in the  '''modules/me/''' directory. Bloggie is the module name. It is good practice to name the folder where module's files are located with the name of the module, it is just more clear. In the end it will be some type of blog module with the name Bloggie.

Lets describe each file in the module. This is almost the minimal set of files for the module:

'''bloggie/classes''' [[BR]]
directory with all module classes

'''bloggie/classes/MeBlggConfig.php''' [[BR]]
Module config class. In most cases you don't need to modify it - it inherits system class which has all the necessary functionality to get configuration values.

'''bloggie/classes/MeBlggDb.php''' [[BR]]
Module database class. It is strongly recommended that you write all SQL queries in this class only, then you can call ready functions from the code.

'''bloggie/classes/MeBlggModule.php''' [[BR]]
Module controller class - where the main work happens.

'''bloggie/classes/MeBlggTemplate.php''' [[BR]]
Module template class. You don't need to change this class. All the necessary functionality is inherited from the base class.

'''bloggie/install''' [[BR]]
Module installation directory, where all installation files are located, like SQL files and language files.

'''bloggie/install/config.php''' [[BR]]
Module installation config file. We will take a closer look at this later.

'''bloggie/install/info''' [[BR]]
Installation information messages folder. If you need to display information messages upon module install/uninstall, you will need to place files here - also special instructions are needed to point to in the install config file to display these messages properly.

'''bloggie/install/installer.php''' [[BR]]
Module installer class. You can add some custom installation scripts and override default behavior.

'''bloggie/install/langs''' [[BR]]
Module languages must be located in this dir. The language file name must be a php file with the name of two letters of the language code.

'''bloggie/install/langs/en.php''' [[BR]]
Default English language file.

'''bloggie/install/sql''' [[BR]]
SQL script for module install and uninstall are here.

'''bloggie/install/sql/install.sql''' [[BR]]
Module installation SQL file.

'''bloggie/install/sql/uninstall.sql''' [[BR]]
Module un-installation SQL file.

'''bloggie/request.php''' [[BR]]
File which routes all requests to the '''MeBlggModule''' class. You don't need to change it in most cases.

'''bloggie/templates''' [[BR]]
Module templates directory. You need to place *.html, *.css and image files here, according to the structure below.

'''bloggie/templates/base''' [[BR]]
Base template folder. You don't need to create a separate folder for each template (but you can do that). Just place all files into the base folder, and regardless of the current chosen template, all template files will be taken from here. Also, all HTML template files are located in this folder.

'''bloggie/templates/base/css''' [[BR]]
CSS files must be located here.

'''bloggie/templates/base/images''' [[BR]]
Images files must be located here.

'''bloggie/templates/base/images/icons''' [[BR]]
Image icons must be located here.

'''bloggie/templates/base/main.html''' [[BR]]
Our custom template file.


The location of each file is important, because there are some functions to plug-in to each file automatically. If the file is not located properly, it will not be possible to plug it in easily.

The foregoing just gives you the basic view of the module's structure, and now you know where to find files to modify templates, or where all module's SQL queries are located.

Now you need to install the module via the admin panel. Go to Dolphin admin panel -> Tools -> Modules. Scroll down to the '''Not Installed Modules''' block. It will show the '''Bloggie version 1.0.0 by Me''' module here if you uploaded all the files properly. Select it and click install. The module will be installed and you will see the '''Installation of: Bloggie Done''' message in the top block of this page. To test the module open the following page:

{{{
http://www.your-site.com/your-path/m/bloggie/home
}}}

or if Apache mod rewrite is not enabled, or you don't have the .htaccess file in the Dolphin root folder for some strange reason, you can try to open the following url:

{{{
http://www.your-site.com/your-path/modules/?r=bloggie/home
}}}

The only thing this module does is to display the following message: "For a community to be whole and healthy, it must be based on people's love and concern for each other". Not so much, but it is an example of a working result, shows that you don't have any bugs and your site cannot be hacked through this page.

Now we will make some easy modifications to this page.
But, before proceeding to any modifications, let's disable all template caches in the Dolphin admin panel -> Settings -> Advanced Settings -> Template. It will make life easier by saving some time for you - you don't need to clear the cache manually after each change.

== 2.1. Change Text ==

This phrase on the page is located in the language file, so all we need is to change the translation. The easiest way is to go to the Dolphin admin panel -> Settings -> Language settings and change the phrase here, but in this case the phrase will not be remembered by our module and this modification would be lost upon module reinstall. To change it in the module forever, we need to edit the '''bloggie/install/langs/en.php''' file.

File content looks like this (I omitted php tags and copyright info):

{{{
$sLangCategory = 'My Bloggie';

$aLangContent = array(
    '_me_blgg' => 'My Bloggie',
    '_me_blgg_text' => 'For a community to be whole and healthy, it must be based on people\'s love and concern for each other.',
);
}}}

The language file is regular php file with one array, where array indexes are language keys and values are translations. Now we need to change the translation only. Take care when editing translations, some characters must be escaped properly as it is a regular php file and regular php string. Also, if you are translating the language file to another language, you need to be sure that you are using UTF-8 encoding during editing of this file. Change it in the following way:

{{{

$sLangCategory = 'My Bloggie';

$aLangContent = array(
    '_me_blgg' => 'My Bloggie',
    '_me_blgg_text' => 'Hello World!',
);
}}}

If you are brave enough you may enter you own text.

After this change, you will not see the new message on the desired page until you reinstall the module, or you can select the module in the list of installed modules in the Dolphin admin panel -> Tools -> Modules and click Recompile language(s). Now the text is changed on your page, of course, after a page refresh.

But what is this good for ? A simple text page can be created using an easier method ... you maybe already know that you can create such pages in the Dolphin page builder.
Ok, lets add some dynamics to make a difference from static pages!

== 2.2. Adding dynamic content. ==

For some users, it maybe useful to see the difference between server time and user time, so this change will show both server and user time.

It is easier to begin with the things we already know. First we need to add new language keys:

{{{
$sLangCategory = 'My Bloggie';

$aLangContent = array(
    '_me_blgg' => 'My Bloggie',
    '_me_blgg_server_time' => 'Server time:',
    '_me_blgg_user_time' => 'User time:',
);
}}}

I assume that you didn't forget to recompile language files for the module after this change!

Then, we will modify the template file '''bloggie/templates/base/main.html''' from the old one:

{{{
<div style="text-align:center;">
    <bx_text:_me_blgg_text />
</div>
}}}

to a new one:

{{{
<div style="text-align:center;">
    <bx_text:_me_blgg_server_time /> __server_time__
    <br />
    <bx_text:_me_blgg_user_time />
    <script type="text/javascript">
        document.write(new Date());
    </script>
</div>
}}}

Some things need clarifying:

    * '''bx_text''' is a special instruction. It outputs a translation for the key using the currently selected language.  
    * '''__server_time__''' is a template variable which is not defined yet.
    * For the user time, we use javascript, because javascript is executed in a browser, on the user side, so the time is user time here.

Now, try to refresh the page to see what was changed, If everything is done right, you will see something like this:

{{{
Server time: __server_time__
User time: Fri Jan 22 2010 13:46:07 GMT+1100
}}}

It almost works perfectly. The only thing is the server time display. All the underscores are displayed, because we have not defined a server variable yet. To define this we need to change the following code in the '''bloggie/classes/MeBlggModule.php''' file:

{{{
    function actionHome () {
        $this->_oTemplate->pageStart();
        $aVars = array ();
        echo $this->_oTemplate->parseHtmlByName('main', $aVars);
        $this->_oTemplate->pageCode(_t('_me_blgg'), true);
    }
}}}

to this one:

{{{
    function actionHome () {
        $this->_oTemplate->pageStart();
        $aVars = array (
            'server_time' => date('r'),
        );
        echo $this->_oTemplate->parseHtmlByName('main', $aVars);
        $this->_oTemplate->pageCode(_t('_me_blgg'), true);
    }
}}}

Before describing all these lines, refresh the page to see the result - Voila!

{{{
Server time: Fri, 22 Jan 2010 13:56:54 +1100
User time: Fri Jan 22 2010 13:56:55 GMT+1100
}}}

The time is almost the same because I'm on a local server and probably you are,too. But in the case of a remote server in another timezone you will see a difference.

    * '''_oTemplate''' is an automatically defined template class, In our case it is the instance of the '''MeBlggTemplate''' class
    * '''pageStart''' tells you that output will be below
    * '''pageCode''' tells you that output is completed, and the page will be displayed
          * the first parameter is page name, and we take it from the language file using _t function
          * the second parameter tells the script to wrap the output in a box
    * '''parseHtmlByName''' function outputs the '''main.html''' file by making all the substitutions. It accepts the array '''$aVars''' of server variables - in this case we declared the '''server_time''' template variable, which is used in the template as '''__server_time__'''.

Some other things which are good to know at this stage:

Take note of the function name - '''actionHome'''. Every function which begins with the  '''action''' word is accessible from the browser, so be careful and make sure that you don't begin another function with the '''action''' keyword. Make other note too: the URL of the page is '''http://www.your-site.com/your-path/m/bloggie/home'''. The '''Home''' keyword in the function name is directly dependent on the URL. The trick is that the URL is transformed to the function name. For example - '''http://www.your-site.com/your-path/m/bloggie/test_page''' will be transformed to the '''actionTestPage''' function. Also, you maybe already noticed that '''http://www.your-site.com/your-path/m/bloggie/''' URL is working too. This is because '''actionHome''' is special function which is called when no one is pointed to the URL. Also, these '''action''' functions can accept parameters, but this will be described later.