Blame | Last modification | View Log | RSS feed
This is Travelsized CMS version 0.3.0Contents:1. Introduction2. Coding Style3. Module Coding.-=:=-._.-=:=-._.-=:=-._.-=:=-._.-=:=-._.-=:=-._.-=:=-._.-=:=-._.-=:=-._.-=:=-.1. IntroductionThis file contains instructions, guidelines and other useful information forthose who wish to try hacking at Travelsized CMS..-=:=-._.-=:=-._.-=:=-._.-=:=-._.-=:=-._.-=:=-._.-=:=-._.-=:=-._.-=:=-._.-=:=-.2. Coding Style* Indentation happens using tabs, and with your text editor's tab width set to 8characters.* Assignments and arithmetics are written as follows:$variable = $x + $y;* Function calls are mare with no space after the function name:function($argument1, $argument2);* Documentation in phpDocumentor style API documentation (www.phpdoc.org) isheavily encouraged.* Non-logical blocks (such as a sequence of code) can be commented as such:// A comment {code;more code;// A comment }---------------------------------------2.1 Block styleBlocks are written as follows (using an if block as the example):/* Comments go on the previous line using either of the commenting styles */if( condition == value ){code;}else // else lines on the same line as the preceding if block's{code;}.-=:=-._.-=:=-._.-=:=-._.-=:=-._.-=:=-._.-=:=-._.-=:=-._.-=:=-._.-=:=-._.-=:=-.3. Module CodingCoding modules for Travelsized CMS is a fairly straight-forward business, andit has been designed to be so simple for ease of expansion.---------------------------------------3.1 Expanding your module beyond the first fileYou may wish to put more code into a module than fits in one file. This canbe done by creating a subfolder under the modules folder and putting thosefiles in there. A good idea would be to structure this folder as follows:/setup - the Travelsized CMS system folder/modules - the Travelsized CMS modules foldermodulename.php - your module's main file/modulename - same name as your module main file, bar the extension/data - put your module's data in here/code - put extra module code in herei18n.??.inc - internationalisation files - see bellow...................InternationalisationThe Travelsized CMS internationalisation function (i18n) supports the modulesystem, and to i18n-ify your module, create files in the modulename folder(above) containing something similar to the following (Danish i18n):filename: setup/modules/modulename/i18n.dk.inccode begins----------------------------------<?PHP// i18n for the modulename module$i18nstrings["Replace the text with this, plus the contained argument, which is ##0##!"] = "Replace the text with this, plus the contained argument, which is ##0##!";?>code ends--------------------------------------------------------------------------3.3 Module file structureThe following is a heavily commented example of a module, which does nothingat all really...filename: setup/modules/modulename.phpcode begins----------------------------------<?PHP/*** Example Module for Travelsized CMS* @author Dan Jensen <admin@leinir.dk>* @date 2006-02-21* @version 0.1* @copyright Lesser GNU Public License - www.gnu.org/copyleft*/// The following registers$modules_names[] = "Module Name";$mopules_versions[] = "0.1";$modules_descriptions[] = "A description of what the module does";// Register the module's module setup function into the module setup function registry$modules_setup[] = "modulesetup_modulename";// Register the module's parser functions into the module parsing function registry$modules[] = "parse_modulename";$modules[] = "parse_modulename_more";// Usergroup defaults {/* Set the default user permissions for this module.Notice especially the naming convention here, as it is requiredby the permissions system to manage modules properly */$usergroups_global_default["modules_modulename_view"] = true;$usergroups_global_default["modules_modulename_edit"] = false;// Usergroup defaults }// Give the user some help, show them what they can do with this module {$page_help["\replace(txt1)"] = "Will replace with a text, containing txt1";$page_help["\replacemore(txt1)"] = "Will replace with a text, containing txt1, through a function";// Give the user some help, show them what they can do with this module }/*** modulename_replacer replaces a text with a longer text, containing that same text** @param $replacewith Replace this text with a longer text** @return string The replacement text*/function modulename_replacer( $replacewith ){return i18n("Replace the text with this, plus the contained argument, which is ##0##!", array($replacewith));}// All parse functions take one required argument $page_data, containing unparsed page data, and returns the parsed $page_datafunction parse_modulename( $page_data ){global $setup_folder;while(true){$begpos = strpos( $page_data, "\\replace(" ); //where does the first itemif ($begpos === false) break; //all items have been parsed, no need to check more$endpos = strpos( $page_data, ")", $begpos + 8 ); //feed end$text = substr($page_data, $begpos + 9, ( $endpos - $begpos ) - 9);if( isAllowed( "modules_modulename_view" ) )$replacewith = i18n( "Replace the text with this, plus the contained argument, which is ##0##!", array( $text ) );else$replacewith = i18n( "You are not authorised to view this!" );$page_data = str_replace( "\\readrss($text)", $replacewith, $page_data );}return $page_data;}// All parse functions take one required argument $page_data, containing unparsed page data, and returns the parsed $page_datafunction parse_modulename_more( $page_data ){global $setup_folder;while( true ){$begpos = strpos( $page_data, "\\replacemore(" ); //where does the first itemif ( $begpos === false ) break; //all items have been parsed, no need to check more$endpos = strpos( $page_data, ")", $begpos + 12 ); //feed end$text = substr( $page_data, $begpos + 13, ( $endpos - $begpos ) - 13 );if( isAllowed( "modules_modulename_view" ) )$replacewith = modulename_replacer( $text );else$replacewith = i18n( "You are not authorised to view this!" );$page_data = str_replace("\\readrss($text)", $replacewith, $page_data);}return $page_data;}// The module setup function takes no arguments, and returns the HTML code for what will be put into the module setup box on the websitefunction modulesetup_modulename(){if( isAllowed( "modules_modulename_edit" ) )return "<div>" . i18n( "This text is what will show up in the module setup, when the user goes to configure it." ) . "</div>";elsereturn "<div>" . i18n( "You are not authorised to view this!" ) . "</div>";}?>code ends--------------------------------------------------------------------------3.4 BreadcrumbsThe setup mode breadcrumbs trail is created from the $_REQUEST variables inthe following order:$_REQUEST["module"] (a substring, removing the modulesetup_ part)$_REQUEST["module_section"]$_REQUEST["module_subsection"]$_REQUEST["module_action"]All of these are put through i18n(), so if a translation exists, this isshown in stead of the contents of the variable itself (you can i18n english aswell, that way you can translate a short, lowercase and technical sounding"modulename" to a proper English text like "Module Name")---------------------------------------3.5 Particularly interesting functionsThe following is an in no way exhaustive list of functions that might beinteresting to you when writing a module....................i18n($translateme, $array)Returns a translated string of the string $translateme, in InternationalEnglish (aka British English), replacing texts in the format ##number## withthe contents of the element in that position in the array $array.examples:i18n("Translate me") with the language set to dk might return "Oversæt mig"i18n("Translate me") with the language set to fr might return "Translate me"(The above will happen if there is no translation available)i18n("Text ##0## replacement", array("stuff")) with the language set to dkmight return "Tekst stuff erstatning"...................siteURL($removepagename)Returns the website's URL, and if $removepagename is true, the index.php nameis removed from the URLexamples:siteURL() might return http://www.sitename.com/subsite/index.phpsiteURL(true) might return http://www.sitename.com/subsite/...................thisPageURL($header = false, $absoluteurl = true)Returns the full URL to the current page, in html format normally, if $headeris true in header format (with & in stead of &), and if $absoluteurl istrue including the protocol, port (if applicable) and full domain name.examples:thisPageURL() might return ./index.php?page_id=13&language=en&user_id=usernamethisPageURL(true) might return ./index.php?page_id=6&language=enthisPageURL(false, true) might return http://www.sitename.com/subsite/index.php?page_id=101&language=en...................getUserInfo($login, $which_info)saveUserInfo($login, $which_info, $info)getUserInfo will return the user information $info about $which_info savedusing saveUserInfo about the user $login.examples:getUserInfo("username", "name") might return "Full Name"getUserInfo("username", "email") might return "email@sitename.com"saveUserInfo("username", "email", "newaddress@newsite.com") returns true when saved and false when failed