PHP-Nuke Addons & Modules System ================================ Since PHP-Nuke 5.0 you can add new modules, addons or plugins simply copying the addons files into a directory. With this feature, PHP-Nuke gains modularity and you, the webmaster, the choice to install and/or unistall the modules you want with an easy step. This document has two main parts, one for webmasters/users and other for Addons developers. Please read it carefully and remember that this system, as the whole PHP-Nuke comes without any warranty and all you do from here is under your own responsability and risk. Always remember to backup your database and all your files before doing anything. ==================================== 1.- Information for Webmasters/Users ==================================== We start on the "modules" directory where you can add or delete all the modules, addons or plugins you want. The directories names under /modules/ dir have a rule to work properly: a) All spaces are filled with "_", so if you have a module called for example Web Links, your directory name need to be Web_Links Modules links will be automaticaly added to the Main Menu block at the end of your entries. The selected list method, instead of the use of LI html tag, is: · Module Name
This is because we want to provide HTML 4.0 Transitional compatibility, if you want to change this, just edit mainfile.php file on the function mainblock(), but try to stay under the HTML standards and eliminate any
  • tag from all your blocks, why? because on the new standard you need to use before and after the listed items, if you do this the box will not looks good on the site. If you want to maintain or test a new Addons but don't want to show a link to your users, just login as admin and click on your addon in the Modules block. When you copy a new addon to the /modules/ directory, it will be added automaticaly into your database with "Inactive" status. Inactive Modules can be viewed and accesed only by Administrators. If you have Inactive the Modules block but you want to offer a module service, just Active the module/addon (not the block) from administration page and provide a link like: http://www.yoursite.com/modules.php?mop=modload&name=Addon_Name&file=index where &name=Addon_Name is the directory name under modules directory and &file=index is the name of the main .php file (without the extension) of your module. The rest of the URL is required. To simplify this process, you can just provide a link with "name" variable, like: http://www.yoursite.com/modules.php?name=Addon_Name you can do this "only" if your file name is "index.php" and no functions inside need to be called. When install a new addon please be sure that the blank spaces on the directory's name are replaced with "_", for Example: Web_Links. The directory name is case sensitive, this mean that isn't the same web_links than Web_Links. The "_" character is replaced automaticaly by a blank space when the addon link appears in the Modules block. So "Web_Links" module directory name will be changed to "Web Links". Also, please read the addon instructions that will be included by the addon author for installation purpouses. ===================================== 2.- Information for Addons Developers ===================================== Making a new addon with this system is pretty easy. Developer just need to know a few rules: a) On each addon file please remember to add the following code as the first lines: if (!eregi("modules.php", $_SERVER['PHP_SELF'])) { die ("You can't access this file directly..."); } This is to avoid direct access to the addons files, so users need to click on your link, with this we assure to include the theme layout for each page. b) The best way is to follow the translation system by defines. To do this just create a "language" directory inside your addon main directory, and on each module file include this code: require_once("mainfile.php"); $module_name = basename(dirname(__FILE__)); get_lang($module_name); This will include (if exist) the language file according to the user's cookie. You can take a look at any included module to see an example for this feature. c) When declare a switch() do not use the variable $mop to do it. Use another variable name like $op, for example. d) On the Addon directory name do not use blank spaces, instead use the character "_". For example if you want to create an addon called "The Web Ring", the directory name will be "The_Web_Ring". e) Any link on the addons files need to have the following syntax: http://www.yoursite.com/modules.php?mop=modload&name=The_Web_Ring&file=index where "modules.php?mop=modload" is required as is, "&name=The_Web_Ring" is the directory name of the addon and "&file=index" declares the file name to access, without the .php extension. The extension will be added automaticaly. Easy, no? Ok, if you need to link to a specified function to any file of your addon, to the above URL just add: &switchname=name So, if you declared a switch like: switch($func) { case "func-one": funct-one(); break; } you will call it: http://www.yoursite.com/modules.php?mop=modload&name=The_Web_Ring&file=index&func=func-one if your function need to receive variables values, your switch will look like: switch($func) { case "func-one": funct-one($xid, $xname); break; } your link need to be: http://www.yoursite.com/modules.php?name=The_Web_Ring&file=index&func=func-one&xid=$xid&xname=$xname If you need to use forms in your addon, use this method:
    ...
    but remember to not use reserved variables names like "name" and/or "file" and use a switch variable different of "$mop". Hope that these rules are clear. Another important note is that you need to know that modules system have reserved variables, they are: $name: Used to declare the addon name $file: Used to declare the filename in use $mop: Used for the modules.php switch $index: Used to add or remove the right blocks $modload: The call $mod_active: Used to check modules' status As an additional and interesting note, you can make that your addon show left and right blocks by using the $index variable. At the begining of your file just declare the varibale: $index = 1; If the value is "1" your addon will show the right blocks, if the value is "0" will only show the left blocks, of course with the default or user selected theme layout. Remember that you can also use your own language translation file, called for example lang-english.php so we can create language compatibility with the rest of the site using language system. Well, this was not a very big documentation but a basic one to let you start using and/or making your addons/modules/plugins. Hope that you enjoy this new feature of PHP-Nuke. =================================== 2.- Using the SQL Abstraction Layer =================================== The SQL abstraction layer is a method to make the SQL queries so any user of any database server can use PHP-Nuke. From version 6.5 and up, PHP-Nuke users the same abstraction layer of phpBB for compatibility reasons. It's very easy and highly tested. Normaly you make a query on MySQL like this: $sql = "SELECT uid, uname FROM nuke_users"; $result = mysql_query($sql); list($uid, $uname) = mysql_fetch_row($result); With the SQL abstraction layer on PHP-Nuke you should declare $db as a global variable and then: $sql = "SELECT uid, uname FROM nuke_users"; $result = $db->sql_query($sql); $row = $db->sql_fetchrow($result); This will return the array $row[] with the results. If you want to work with more friendly names you should do this: $uid = $row[uid]; $uname = $row[uname]; But is much faster for you and the system to use just the array values directly, ie: echo "Hello $row[uname], Welcome to my site!"; Note that there isn't any "sql_fetch_array", the sql_fetch_row automaticaly will create the array with the results of your query. It's clear? Yeah. The old method using the file sql_layer.php and the variable $dbi is now deprecated. It works for compatibility reasons, but I strongly suggest to any developer making new modules or modifying a module to start using the new method. ============================================================================ NOTE: To stay under HTML 4.01 Transitional standard is very important that you substitute all "&" characters in the URLs with "&" tag. So, for example, the URL: need to be written: without this, your pages will not validate as HTML 4.01 compatible. ============================================================================= COPYRIGHT WARNING!!! Since PHP-Nuke is licensed under the GNU/GPL License, whatever module, addon, plugin, theme, block, etc. that needs any PHP-Nuke part of code to properly run need to be released under a GPL compatible license. Doesn't matter what license you choose to use, that work is automaticaly licensed under the terms of the GNU/GPL license. Please read the GPL License carefully, it's in the included COPYING file ============================================================================= Have fun now!