Changes between Version 6 and Version 7 of DolphinTutorialMyFirstModule

Timestamp:

Jan 29, 2010, 6:16:24 AM (14 years ago)

Author:

AlexT

Comment:

--

DolphinTutorialMyFirstModule

@@ -412 +412 @@
 == 3.3. Changing the settings form. ==
 
+Change the '''actionAdministration''' function the following way:
+
+{{{
+    function actionAdministration () {
+
+        if (!$GLOBALS['logged']['admin']) { // check access to the page
+            $this->_oTemplate->displayAccessDenied ();
+            return;
+        }
+
+        $this->_oTemplate->pageStart(); // all the code below will be wrapped by the admin design
+
+        $iId = $this->_oDb->getSettingsCategory(); // get our setting category id
+        if(empty($iId)) { // if category is not found display page not found
+            echo MsgBox(_t('_sys_request_page_not_found_cpt'));
+            $this->_oTemplate->pageCodeAdmin (_t('_me_blgg'));
+            return;
+        }
+
+        bx_import('BxDolAdminSettings'); // import class
+
+        $mixedResult = '';
+        if(isset($_POST['save']) && isset($_POST['cat'])) { // save settings
+            $oSettings = new BxDolAdminSettings($iId);
+            $mixedResult = $oSettings->saveChanges($_POST);
+        }
+
+        $oSettings = new BxDolAdminSettings($iId); // get display form code
+        $sResult = $oSettings->getForm();
+                   
+        if($mixedResult !== true && !empty($mixedResult)) // attach any resulted messages at the form beginning
+            $sResult = $mixedResult . $sResult;
+
+        echo DesignBoxAdmin (_t('_me_blgg'), $sResult); // dsiplay box
+        
+        $this->_oTemplate->pageCodeAdmin (_t('_me_blgg')); // output is completed, admin page will be displaed here
+    }   
+}}}
+
+then add the following class method to the '''modules/me/bloggie/classes/MeBlggDb.php''' file:
+
+{{{
+    function getSettingsCategory() {
+        return $this->getOne("SELECT `ID` FROM `sys_options_cats` WHERE `name` = 'My Bloggie' LIMIT 1");
+    }
+}}}
+
+Clarification:
+
+    * the '''getSettingsCategory''' method is placed into '''MeBlggDb''' since all database queries must be in this file.
+    * the '''getOne''' method returns the value of '''ID''' field in the '''SELECT''' SQL query. There are other handy functions to get the data from database. Refer to '''inc/classes/BxDolDb.php''' for complete list.
+    * '''_oDb''' is automatically defined in the '''MeBlggDb''' class
+    * the '''MsgBox''' function wraps text in a nice message box
+    * the '''bx_import''' function automatically imports a class by its name, and it can load classes with '''BxDol''', '''BxBase''', '''BxTempl''' prefixes if they are correctly named and located. Also, it can load module classes if the module config is passed as the second parameter.
+    * the '''BxDolAdminSettings''' class is used to display and save settings. Just use it as shown above. Make a note that the '''saveSettings''' function returns a result message which we append at the beginning of the result string.
+
+
+== 3.4. Adding a link to a newly created page to the admin modules sub-menu. ==
+
+Replace the content of '''install.sql''' with the following code:
+
+
+{{{
+-- settings
+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_permalinks', 'on', 26, 'Enable friendly permalinks in Bloggie', 'checkbox', '', '', '0', ''),
+('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', '');
+
+-- permalinks
+INSERT INTO `sys_permalinks` VALUES (NULL, 'modules/?r=bloggie/', 'm/bloggie/', 'me_blgg_permalinks');
+
+-- admin menu
+SET @iMax = (SELECT MAX(`order`) FROM `sys_menu_admin` WHERE `parent_id` = '2');
+INSERT IGNORE INTO `sys_menu_admin` (`parent_id`, `name`, `title`, `url`, `description`, `icon`, `order`) VALUES
+(2, 'me_blgg', '_me_blgg', '{siteUrl}modules/?r=bloggie/administration/', 'My Bloggie by Me', 'modules/me/bloggie/|icon.png', @iMax+1);
+}}}
+
+and '''uninstall.sql''' with the following:
+
+{{{
+-- 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;
+DELETE FROM `sys_options` WHERE `Name` = 'me_blgg_permalinks';
+
+-- permalinks
+DELETE FROM `sys_permalinks` WHERE `standard` = 'modules/?r=bloggie/';
+
+-- admin menu
+DELETE FROM `sys_menu_admin` WHERE `name` = 'me_blgg';
+}}}
+
+Also, we need to change this section in the '''modules/me/bloggie/install/config.php''' file, since we have modified the '''sys_permalinks''' database table:
+
+{{{
+    'install' => array(
+        'update_languages' => 1,
+        'execute_sql' => 1,
+        'recompile_permalinks' => 1,
+    ),
+    'uninstall' => array (
+        'update_languages' => 1,
+        'execute_sql' => 1,
+        'recompile_permalinks' => 1,
+    ),
+}}}
+
+the '''recompile_permalinks''' instruction was added above.
+
+We need to specify permalinks, because they are needed for correct link representation in case of an enabled '''mod_rewrite''' module in Apache and when this module is disabled. To correctly enable the permalinks mechanism we need to specify several things:
+
+    * add a setting option which enables or disables permalinks in the module. In our case we have added the '''me_blgg_permalinks''' setting option. Please note that we have added this option to a special category (category id is equal to "'''26'''").
+    * add the record to the '''sys_permalinks''' database table where we specify the newly created setting option and two URLs:
+          * '''modules/?r=bloggie/'''  - when permalinks are disabled
+          * '''m/bloggie/''' - when permalinks are enabled
+    * add '''recompile_permalinks''' in the '''modules/me/bloggie/install/config.php''' file. It tells the installer to recompile cache with permalinks when we install or uninstall the module.
+
+The link to admin Modules submenu is added at the end. We have specified:
+
+    * "'''2'''" indicates that it will be added to the '''Modules''' admin menu
+    * '''me_blgg''' is an internal name. It is similar to a normal database prefix 
+    * '''_me_blgg''' is the language key which is used to display the module title
+    * '''URL''' is specifiled without permalinks enabled, and it is transformed to mod_rewrite URL automatically, if permalinks are enabled. Also, we used '''siteUrl''' in the URL,  but it will be replaced with the full site URL with the slash at the end.
+    * '''My Bloggie by Me''' is the module description.
+    * '''modules/me/bloggie/|icon.png''' is a menu icon. This icon must be placed into the '''modules/me/bloggie/templates/base/images/icons/''' folder and named '''icon.png'''. The size should be 16x16 pixels.
+    * '''@iMax+1''' is order. Order is calculated in the previous string, and in this case, it will be added to the end of the list - which is preferable behavior.
+
+
+Full module re-installation is needed because we have modified the '''config.php''' and '''install.sql''' files.
+
+The module is completed and you can download resulted module here(TODO:bloggie2.zip) to compare with your own, or to find mistakes if something went wrong.
+
+== 4. Blog functionality. ==
+ 
+I have prepared new package to not waste the time for things already explained. Please uninstall your current '''Bloggie''' module and delete it from the '''modules/me''' directory, and then download a new one from here(TODO:bloggie3.zip) and install it. I have just removed unnecessary things and added settings and language keys related to Blog functionality.
+
+Our Bloggie will consist of several pages:
+
+    * the latest blog posts page (our module homepage)
+    * Blog post view
+    * Adding a blog post page
+    * Editing the Blog post page
+
+The main thing in this section is how to deal with forms, and includes several helpful hints.\
+
+== 4.1. Creating the database structure. ==
+
+We will have only one database table with blog posts:
+
+{{{
+CREATE TABLE `me_blgg_posts` (
+    `id` INT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY ,
+    `title` VARCHAR( 255 ) NOT NULL ,
+    `text` TEXT NOT NULL ,
+    `author_id` INT UNSIGNED NOT NULL ,
+    `added` INT UNSIGNED NOT NULL ,
+    INDEX ( `author_id` )
+);
+}}}
+
+add the above lines to the beginning of the '''install.sql''' file. Also, we need to add a "drop" database to the beginning of the '''uninstall.sql''' file:
+
+{{{
+DROP TABLE `me_blgg_posts`;
+}}}
+
+Since you are aware of the basic SQL synatax, I will not go into a description of each symbol. In the general, our '''Bloggie''' will have '''title''' and '''text''', and other hidden fields are necessary too:
+
+    * '''id''' - a unique identifier of each blog post. It is also the table primary key
+    * '''author_id''' - author's profile id
+    * '''added''' - blog post creation date/time
+
+I have indexed the '''author_id''' field because we may have a page with all user's posts in the future.
+
+== 4.2. Creating the add post page. ==
+
+Add the following method to the '''MeBlggModule''' class:
+
+{{{
+    function actionAdd () {
+
+        if (!$GLOBALS['logged']['member'] && !$GLOBALS['logged']['admin']) { // check access to the page
+            $this->_oTemplate->displayAccessDenied ();
+            return;
+        }
+
+        $this->_oTemplate->pageStart(); // all the code below will be wrapped by the user design
+
+        bx_import ('BxTemplFormView'); // import forms class
+
+        $oForm = new BxTemplFormView ($this->aForm); // create foprms class
+
+        $oForm->initChecker(); // init form checker
+
+        if ($oForm->isSubmittedAndValid ()) { // if form is submitted and not form errors were found, save form data
+
+            $aValsAdd = array ( // add additional fields
+                'added' => time(),
+                'author_id' => $_COOKIE['memberID'],
+            );                        
+            $iEntryId = $oForm->insert ($aValsAdd); // insert data to database
+
+            if ($iEntryId) { // if post was successfully added
+                $sRedirectUrl = BX_DOL_URL_ROOT . $this->_oConfig->getBaseUri() . 'view/' . $iEntryId;
+                header ('Location:' . $sRedirectUrl); // redirect to created post view page
+                exit;
+            } else {
+                MsgBox(_t('_Error Occured')); // if error occured display erroro message
+            }                
+
+        } else {
+
+            echo $oForm->getCode (); // display form, if the form is not submiyyed or data is invalid
+
+        }
+
+        $this->_oTemplate->pageCode(_t('_me_blgg_page_title_add'), true); // output is completed, display all output above data wrapped by user design
+    }
+}}}
+
+then modify the '''MeBlggModule''' class constructor the following way:
+
+{{{
+    function MeBlggModule(&$aModule) {        
+        parent::BxDolModule($aModule);
+
+        $this->aForm = array(
+
+            'form_attrs' => array(
+                'name'     => 'form_bloggie',
+                'action'   => '',
+                'method'   => 'post',
+            ),      
+
+            'params' => array (
+                'db' => array(
+                    'table' => 'me_blgg_posts',
+                    'key' => 'id',
+                    'submit_name' => 'submit_form',
+                ),
+            ),
+                  
+            'inputs' => array(
+
+                'title' => array(
+                    'type' => 'text',
+                    'name' => 'title',
+                    'caption' => _t('_me_blgg_form_caption_title'),
+                    'required' => true,
+                    'checker' => array (
+                        'func' => 'length',
+                        'params' => array(3,255),
+                        'error' => _t ('_me_blgg_form_err_title'),
+                    ),
+                    'db' => array (
+                        'pass' => 'Xss',
+                    ),
+                ),            
+                
+                'text' => array(
+                    'type' => 'textarea',
+                    'name' => 'text',
+                    'caption' => _t('_me_blgg_form_caption_text'),
+                    'required' => true,
+                    'html' => 2,
+                    'checker' => array (
+                        'func' => 'length',
+                        'params' => array(20,64000),
+                        'error' => _t ('_me_blgg_form_err_text'),
+                    ),                    
+                    'db' => array (
+                        'pass' => 'XssHtml',
+                    ),                    
+                ),
+
+                'submit' => array (
+                    'type' => 'submit',
+                    'name' => 'submit_form',
+                    'value' => _t('_Submit'),
+                    'colspan' => true,
+                ),            
+
+            ),            
+        );
+    }
+}}}
+
+The array we have placed into the constructor is our form description. The reason we have placed it in the description instead of the function is that we will reuse this array in the future when we create our edit post page.
+
+
+The form description array can be described the following way:
+
+ * form_attrs are regular HTML attributes which will be added to the <form> tag.
+ * params are special function parameters. This can have several parameters, but most important is the db sub-array which describes the table to save form data to.
+
+    * table is the database table name to save data to
+    * key is the database primary key field (it is used to update data)
+    * submit_name is the name of the submit html form element and is used to determine automatically when the form is submitted.
+
+ * the inputs array describes every form element, and each element consists of the following fields:
+
+    * type is input type, like text, textarea, etc
+    * name is input the type name it also must match database field name
+    * caption is the indicated form element name
+    * required displays a red asterisk near the caption. Please note that it displays a red asterisk only. No real checking for mandatory fields is made if this field is true. For real checking see below.
+    * checker describes the checker function for the field. This is a place where real checking takes place.
+          * func is the checking function, like length, preg, avail, etc.
+          * params are checking function params. Params varies depending on the exact function.
+          * error is the message to display near the field if checking failed.
+    * db describes the database field to save input data to. The most important is the following parameter:
+          * pass is the function to pass data through, it validates data properly - to not allow an inappropriate value in a particular field. The value of this field may be Xss, XssHtml, Int, Float, Date, etc.
+
+This doesn't describe all the possible values of this array. For a complete list please refer to the '''inc/classes/BxDolForm.php''' file.
+