This is a
"work in progress" it is not complete. The information presented here may not be accurate given the rate at which R3-born is developing.
Hopefully this will prove to be enough of a guide to help developers get started with developing their own R3-born blocks and modules.
Modules and Blocks
Module and Blocks are managed in (more or less) the same way by the module engine. So their development requirements are quite similar, any differences or any special considerations will be noted.
Naming a module or block
You name a module/block anything you want, for example 'my_module'. The module would then be installed in '/modules/my_module/'.
Module and Block Files
There are several files that a module/block should or could have, they would be organised something like the example below.
/modules/my_module/
/modules/my_module/my_module.php
/modules/my_module/mvConstants.php
/modules/my_module/mvHeaders.php
/modules/my_module/mvVersion.php
/modules/my_module/admin/admin_my_config.php
/modules/my_module/install/mvInstall.php
/modules/my_module/install/mvUninstall.php
/modules/my_module/install/mvUpdate.php
/modules/my_module/install/schemas/mssql_install.sql
/modules/my_module/install/schemas/mssql_uninstall.sql
/modules/my_module/install/schemas/mysql_install.sql
/modules/my_module/install/schemas/mysql_uninstall.sql
/modules/my_module/install/schemas/postgres_install.sql
/modules/my_module/install/schemas/postgres_uninstall.sql
/modules/my_module/languages/lang_english/lang_main.php
/modules/my_module/languages/lang_english/lang_admin.php
/modules/my_module/templates/admin/my_module_config_body.tpl
/modules/my_module/templates/subAndreas/my_module_body.tpl
/modules/my_module/templates/subAndreas/subAndreas.css
/modules/my_module/templates/subAndreas/subAndreas.cfg
Default file (Required)
The default page for a module can either be the same name as the module itself, so if the module is called 'my_module' then the default file could be 'my_module.php' or it can also just be 'index.php'.
However, for Block only 'index.php' can be used.
mvVersion.php (Required)
This file is only used by the Module Management ACP. It provides the module engine with details about the module version, where to check for new versions, copyright/credits, description, etc.
It is also used to tell the module engine if the add-on is a Module or a Block. Here is a sample mvVersion.php
 Код:  |
/***
* @version $Id$
* @copyright (c) 2008 Yourname
* (c) 2004 - 2005 Project Minerva
* (c) 2001 - 2006 phpBB Group
* @license http://opensource.org/licenses/gpl-license.php GNU Public License
***/
if ( !defined('IN_R3BORN') )
{
die('Hacking attempt');
}
$mvVersion['type'] = ADDON_MODULE;
$mvVersion['displayname'] = 'My Module';
$mvVersion['description'] = 'This is a longer text entry to better describe exactly what the module does.';
$mvVersion['version'] = '1.0.0';
$mvVersion['copyright'] = 'My Module 1.0.0 by Your Name';
$mvVersion['version_check'] = 'http://www.yourserver.com/update.txt' |
If you have created a block, then you would simply change $mvVersion['type'] to...
| Код: |
| $mvVersion['type'] = ADDON_BLOCK; |
See the
Block/Module Version Checker article for more information about how to make your block/module compatible with the Version Checker.
mvConstants.php (Optional)
The contents of this file will be included for each enabled module/block on every page load.
You should add defines for any DB tables your module/block will use in this file and also register page ids for each page your module can potentially display.
Anything which would have been put in 'includes/constants.php' in phpBB 2.0.x should now be put in a file called mvConstants.php in the root of the new module/block directory.
Example
| Код: |
define('MY_MODULE_TABLE', $table_prefix.'thingy');
register_page_id('PAGE_MY_MODUE_INDEX', 'my_module.' .$phpEx, 'My Module Index'); |
Registering the page ids updates the sessions so that you can track vistors
access to the pages via the ACP and the optional View Online module.
Please note, blocks should not register page ids.
Additionally these page registrations update the layout manager which enables the site admin to assign blocks and access restrictions to each page.
Note! If you are creating a block to compliment an existing module then you may not need an mvConstants.php file since you can use the defines already assigned by the module the block will be complimenting.
Tip! If you module/block does not need a mvConstants.php file then do not ship one with the module/block. This will help improve the performance of the module engine since it won't be including as many files per page load.
mvHeaders.php (Optional)
The contents of this file will be included for each enabled module/block for every page load.
Anything which would have been put in 'includes/page_header.php' in phpBB 2.0.x should now be put in a file called mvHeaders.php in the root of the new module/block directory.
Note! Although blocks will include mvHeaders.php if they have one in their directory, it is not required since blocks are parsed in the core page_header(); function anyway.
Tip! If you module/block does not need a mvHeaders.php file then do not ship one with the module/block. This will help improve the performance of the module engine since it won't be including as many files per page load.
Module Install, Update and Uninstall(Optional)
If your module/block needs to make changes to the R3-born database then you will need to create a SQL installer, uninstaller and potentially an updater.
mvInstall.php
When a module is installed from the ACP for the first time it looks for a file called 'mvInstall.php' in the module 'install' directory. If the file exisits it will be executed. Typically, all this file should do is make the required database updates that the module requires.
The Comments, Downloads, Forum, Pages and Weblogs official module all have install, update and uninstall scripts. You should use them as a template to create these scripts for your module.
mvUpdate.php
When a newer version of the module is uploaded it needs updating from the ACP and it looks for a file called 'mvUpdate.php' in the module 'install' directory. If the file exisits it will be executed. Typically, all this file should do is make the required database changes from the old version of the module to the currently installed version.
mvUninstall.php
When a module is uninstalled from the ACP it looks for a file called 'mvUninstall.php' in the module 'install' directory. If the file exisits it will be executed. Typically, all this file should do is reverse the database updates that were made when the module was installed/updated.
Note! If your module/block does not need to make any changes to the R3-born database then you do not need to create these files or any SQL schemas.
Tip! If your module/block needs to update the database then you can use the
SQL Parser to create MS-SQL and Postgres SQL files from your MySQL schema.
Language files (Optional)
Each module/block can have two lang files in 'modules/modulename/language/lang_xxx/', one called 'lang_main.php' and one called 'lang_admin.php'.
'lang_main.php' will be included for each enabled module for every page load automatically. However, when in the ACP both 'lang_main.php' and 'lang_admin.php' will be included for each enabled module/block.
Therefore, you do not need any code in your module which includes language files since the module engine will do this automtically. If you are porting a phpBB 2.0.x MOD to R3-born, remove any language inclusion code and simply put the required $lang vars in 'lang_main.php' or 'lang_admin.php' as appropriate.
Care should be taken to prefix $lang vars with the module/block name to help avoid conflicts with other modules/blocks. For example...
| Код: |
| $lang['my_module_stuff'] = 'Stuff'; |
...would be good for the 'my_module' module. However...
| Код: |
| $lang['stuff'] = 'Stuff'; |
...is bad because another module could assign $lang['stuff'] and overwrite what has previously been assigned and lead to confusion.
Note! If a module defines new $lang vars then it must be shipped with an English language file as a minimum requirement.
Tip! If you are creating a block to compliment an existing module then you can re-use $lang vars from the module in your block code. This will help improve the performance of the module engine since it won't be including as many files per page load.
Hooks (Optional)
Yeah, I haven't written this bit yet...
The template .cfg file (Optional)
Yeah, I haven't written this bit yet...
The template .css file (Optional)
Yeah, I haven't written this bit yet...
Accessing a module
A module is accessed by specially formatted URL. To access the module 'my_module' the URL would be something like this...
| Код: |
| http://www.yourserver.com/index.php?module=my_module |
As no specific file from the module was requested in the URL above, the module engine will first see if the file 'my_module.php' exists, if so it will use it. If not, it will try 'index.php' and if that doesn't exist it will display a message saying that the module could not be found.
If you want to access a particular file in a module, then you format the URL something like this...
| Код: |
| http://www.yourserver.com/index.php?module=my_module&file=my_file |
This instructs the module engine to run 'my_file.php' from 'my_module' module.
Module Variables
There are a number of module engine variables in R3-born each is described breifly below...
$mvModuleName The name of the currently running module. Empty if no module is currently running.
$mvModule_root_path The path the to root of the currently running module, for exmaple '/modules/my_module/'.
$mvModules An array holding all the data about all of the modules/blocks regardless of there state.
$mvPages An array of page urls and unique ids for the session manager to determine what users are viewing which pages.
$mvLayouts An array of page urls and module is for the block manager to determine what block to display and for the layout manager to determine if the current user is permitted to view the current page.
$mvModuleTemplates An array of all the .tpls for the currently running module. Used by the template engine to determine which .tpl should be used for a given page.
None of these variables should be manipulted directly. See '/includes/functions_modules.php' for the module API.
