Changes between Version 5 and Version 6 of DolphinTutorialMyFirstModule

Timestamp:

Jan 29, 2010, 6:01:20 AM (15 years ago)

Author:

AlexT

Comment:

--

DolphinTutorialMyFirstModule

@@ -263 +263 @@
 
 
+The simplest Dolphin module is completed. Now you can use this to start developing you first Dolphin module, or use it as a framework for your own different modules. Almost every extension can be started from such a structure. Make sure that you take a look at the bloggie/install/config.php file. This file must be heavily changed for your own module, and this file has comments on each line to help you in changing it.
+
+
+== 3. Adding admin panel. ==
+ 
+We want to improve our mod and add a format for the date and allow disabling user time. We definitely need some admin settings for this purpose.
+
+Our admin panel will have the following parts:
+
+    * admin page creation
+    * adding settings to module install and uninstall
+    * print setting form on newly created admin pages
+    * a link in the admin modules section to the module setting page
+
+== 3.1. Admin page creation. ==
+
+Add the following code to the '''bloggie/classes/MeBlggModule.php''' file as a class method:
+
+{{{
+    function actionAdministration () {
+
+        if (!$GLOBALS['logged']['admin']) {
+            $this->_oTemplate->displayAccessDenied ();
+            return;
+        }
+
+        $this->_oTemplate->pageStart();
+
+        echo DesignBoxAdmin (_t('_me_blgg'), 'It works!');
+        
+        $this->_oTemplate->pageCodeAdmin (_t('_me_blgg'));
+    }
+}}}
+
+The '''pageCodeAdmin''' function is similar to the  '''pageCode''' function, but it displays the admin page instead of the user page. Also, this function accepts only one parameter - page title.
+
+Also the difference in the code is that we check if admin only can access this page. The '''$GLOBALS['logged']['admin']''' variable is set to true if admin is logged in. Additionally, you can check if regular members are logged in by using the '''$GLOBALS['logged']['member']''' variable. If none of these values are true, then a guest is accessing your page. The '''displayAccessDenied''' function displays a page with an "access denied" message - in this case, we don't need to care much about that, and we can just return from the function or even exit. The '''$GLOBALS['logged']''' does not always exist, and is initialized in the '''check_logged''' function. In our case this function is called in the '''bloggie/request.php''' file.
+
+Another new function here is '''DesignBoxAdmin'''. It wraps our content in a nice box. The box title is the first parameter and box content is the second one. There is an optional 3rd parameter where you can define the box menu. Also, there is an analog of this function in the user side called '''DesignBoxContent'''. You can examine existing Dolphin code for a lot of examples.
+
+To test the page, you need to login to the admin panel and open the '''http://www.your-site.com/your-path/m/bloggie/administration''' URL.
+
+There is no artificial code, and hopefully you have made everything properly and the admin page is displayed with the  "It works!" phrase. If there is a problem, then review all the steps once again and try to find where there is a mistake.
+
+
+== 3.2. Adding module settings. ==
+
+At this stage we need to modify the '''install.sql''' and '''uninstall.sql''' files for the first time. We need to change the installation config file and indicate that these files must be processed. To do this we need to change the following section in the '''bloggie/install/config.php''' file:
+
+
+{{{
+    'install' => array(
+        'update_languages' => 1,
+    ),
+    'uninstall' => array (
+        'update_languages' => 1,
+    ),
+}}}
+
+to the following:
+
+{{{
+    'install' => array(
+        'update_languages' => 1,
+        'execute_sql' => 1,
+    ),
+    'uninstall' => array (
+        'update_languages' => 1,
+        'execute_sql' => 1,
+    ),
+}}}
+
+It will execute '''install.sql''' and '''uninstall.sql''' files automatically upon modules install/uninstall.
+
+Then, place the following code into '''install.sql''':
+
+
+{{{
+SET @iMaxOrder = (SELECT `menu_order` + 1 FROM `sys_options_cats` ORDER BY `menu_order` DESC LIMIT 1);
+INSERT INTO `sys_options_cats` (`name`, `menu_order`) VALUES ('My Bloggie', @iMaxOrder);
+SET @iCategId = (SELECT LAST_INSERT_ID());
+INSERT INTO `sys_options` (`Name`, `VALUE`, `kateg`, `desc`, `Type`, `check`, `err_text`, `order_in_kateg`, `AvailableValues`) VALUES
+('me_blgg_date_format', 'Y-m-d H:i', @iCategId, 'Format for server date/time', 'digit', '', '', '1', ''),
+('me_blgg_enable_js_date', 'on', @iCategId, 'Show user time', 'checkbox', '', '', '2', '');
+}}}
+
+and the following into '''uninstall.sql''':
+
+{{{
+-- settings
+SET @iCategId = (SELECT `ID` FROM `sys_options_cats` WHERE `name` = 'My Bloggie' LIMIT 1);
+DELETE FROM `sys_options` WHERE `kateg` = @iCategId;
+DELETE FROM `sys_options_cats` WHERE `ID` = @iCategId;
+}}}
+
+The most important thing is that all setting options are in the '''sys_options''' database table. It is better to assign every setting option some category which is stored in the '''sys_options_cats''' database table, because it makes it easier to delete created categories in uninstall and display them. Also, it is good practice to make a prefix for all of your setting names to avoid conflicts with other mods.
+
+Now, we need to use newly created settings, so we change the '''actionHome''' function in the following way:
+
+{{{
+    function actionHome () {
+        $this->_oTemplate->pageStart();
+
+        $sDateFormat = getParam ('me_blgg_date_format');
+        $isShowUserTime = getParam('me_blgg_enable_js_date') ? true : false;
+        $aVars = array (
+            'server_time' => date($sDateFormat),
+            'bx_if:show_user_time' => array(
+                'condition' => $isShowUserTime,
+                'content' => array(),
+            ),
+        );
+        echo $this->_oTemplate->parseHtmlByName('main', $aVars);
+        $this->_oTemplate->pageCode(_t('_me_blgg'), true);
+    }
+}}}
+
+and we change the template as shown below:
+
+{{{
+<div style="text-align:center;">
+    <bx_text:_me_blgg_server_time /> __server_time__
+    <bx_if:show_user_time>
+        <br />
+        <bx_text:_me_blgg_user_time />
+        <script type="text/javascript">
+            document.write(new Date());
+        </script>
+    </bx_if:show_user_time>
+</div>
+}}}
+
+Lets describe a few new things:
+
+    * the '''getParam''' function is used to get a setting option with a specified name. Please note that in the case of a checkbox, it will return '''on''' as the true value or an empty string as a false value.
+    * '''bx_if''' template construction allows adding conditional processing to the template. The condition is in the '''condition''' field, and any variables which you need to use inside bx_if clauses in the template should be placed in the content subarray. In our case, there is no such variable and this array is empty.
+
+Almost everything is done, and it is time to test it now. Reinstall the module, since we have changed the installation config and installation files, and refresh the  '''http://www.your-site.com/your-path/m/bloggie/home''' page. If everything is done right, the result should be as follows:
+
+{{{
+Server time: 2010-01-22 17:45
+User time: Fri Jan 22 2010 17:45:41 GMT+1100
+}}}
+
+Now, everything works except the fact that we cannot change any settings options we just created. So, we now proceed to creating a setting options form.
+
+
+== 3.3. Changing the settings form. ==
+