phpBB

Development Wiki

Using the phpBB3.0 Module System

From phpBB Development Wiki

Abstract

This chapter describes the phpBB3 module system.

phpBB3 uses a module system for the Administration Panel (ACP), User Control Panel (UCP), and Moderator Control Panel (MCP).

1.5.1. Adding a Module

Olympus supports three flavours of Modules: ACP, MCP, and UCP modules. Modules of each flavour are added via the respective pages in the ACP, which can be found under the System tab (MODULE MANAGEMENT). A module is a pluggable component, which offers a set of functionalities for the corresponding panel. A module can offer several modes, each of which can be a page in its own right.


Important
You need the A_MODULES permission to add modules.


To add a module, visit the System tab in the ACP. Find the option for the kind of module you want to add (either ACP, UCP, or MCP) and click it. You will see a list of the currently installed top-level modules and categories. Under that list, you should be able to see two buttons: one to the left, labelled CREATE NEW MODULE, and one to the right labelled, ADD MODULE.


Tip
Modules are organised in categories.


The button CREATE NEW MODULE will direct you to the form to add a new module category. Module categories behave much like directories. Categories can be nested; a category can contain other categories as well as modules. Note that nesting hierarchies deeper than two are not generally supported. If you do not wish to add a new category, use the MODULE TYPE dropbox. The software will use a lang entry matching the value entered under MODULE LANGUAGE NAME, if there is one defined.

By selecting MODULE in the MODULE TYPE dropbox, you can add a new module. The system will display all available modules for the current module flavour; upon selecting a module, the CHOOSE MODULE MODE dropbox will display all modes defined in the module's info file. Select a parent to display the new module at an appropriate place, and then click SUBMIT.


Tip
You can also change a module's position after adding it


Alternatively, you can use theADD MODULE dropbox located to the right to add new modules. The dropbox is filled with all modules and their modes to allow the quick addition of module pages. The default settings set it so that these pages will be added to the top category and be disabled. You can change that by using the icons in the right column of the module table.


Important
Please note that the ACP requires at least a top-category and a sub-category for your module to be put in (three-level-menu), whereas the UCP and the MCP only requires one category for your modules (two-level-menu). Have a look at the category/module structure to get an idea of where the modules need to be put in.

1.5.2. Writing a Module

Now, this is the part that MOD authors may find interesting. A module can include several modes. It usually consists of a module file, an info file and a template file; a language file might be useful as well.

1.5.2.1. Modules and Modes

As hinted before, a single module can offer several modes. Modes are usually related functions collected in the module. While the module is written by the (MOD) author, the modes are what actually is added to the ACP/MCP/UCP.


Tip
Modes of one module can have different permission requirements.


1.5.2.2. The Info File

The info file tells phpBB3 how to handle your module. The info file should be named exactly like your module file and go into the info directory for the flavour of module you are developing (e.g. includes/acp/info; includes/ucp/info; includes/mcp/info).

See Example 1.8, “A sample info file” for an example of a module info file. Note that by convention, the name of the class is the filename of the module with "info" appended. The function module holds the important part.

Example 1.8. A sample info file

<?php
/** 
*
* @package acp
* @version $Id$
* @copyright (c) 2007 phpBB Group 
* @license http://opensource.org/licenses/gpl-license.php GNU Public License 
*
*/
                            
/**
* @package module_install
*/
class acp_hello_world_info
{
    function 
module()
    {
    return array(
        
'filename'    => 'acp_hello_world',
        
'title'        => 'ACP_HELLO_WORLD',
        
'version'    => '1.0.0',
        
'modes'        => array(
            
'hello_user'        => array('title' => 'HELLO_USER''auth' => 'acl_a_user''cat' => array('ACP_AUTOMATION')),
            
'hello_world'        => array('title' => 'HELLO_WORLD''auth' => 'acl_a_group''cat' => array('ACP_AUTOMATION')),
            
'hello_bertie'        => array('title' => 'HELLO_BERTIE''auth' => 'acl_a_board && acl_a_server''cat' => array('ACP_AUTOMATION')),
            ),
        );
        
    }
                            
    function 
install()
    {
    }
                                
    function 
uninstall()
    {
    }

}
?>

Entries in the module description array

KEY What they mean

FILENAME Where the module is defined

TITLE The title to use in the module management. This should match an existing language entry.

VERSION A stable version number

MODES The modes supported by the described module.

Entries in the mode description arrays

KEY What they mean

TITLE The title to use in the module management. This should match an existing language entry.

AUTH The permissions required to see/use the mode. This can use logical operators and are always prefixed with acl_. So, a_modules will be written as acl_a_modules. Furthermore, configuration items can be obtained too, by prefixing them with cfg_. (add link to a more comprehensive explanation of what is possible with the field, additionally explaining the use of aclf, forum ids, etc.)

CAT The default category of the mode


Note
The functions install and uninstall are not used in phpBB3.


Tip
The installer will automatically add all discovered modules with an info file during the Olympus installation.


1.5.2.3. The Module Class

The Module class itself is very straightforward. It requires a field named "u_action" and a method "main", accepting two arguments: $id and $mode. When viewing the module, the module system will init the session and set the user object up - you won't need to take care of any of this. Then it will call your main method, supplying the module id and the mode; where the mode corresponds to the mode used when adding the module, taken from the info file. The name of the file needs to match the information in the info file.

The listing Example 1.8, “A sample info file” gives an example for a module class. Note that the class can contain more methods and variables. The u_action field is automatically initialised by the module system and holds the current page and query string. Use $this->tpl_name to define the template file to be used and $this->page_title for the name to be displayed. As usual, the latter can be a language entry's key.

<?php
/** 
*
* @package acp
* @version $Id$
* @copyright (c) 2007 phpBB Group 
* @license http://opensource.org/licenses/gpl-license.php GNU Public License 
*
*/
            
/**
* @package acp
*/
class acp_hello_world
{
    var 
$u_action;
                    
    function 
main($id$mode)
    {
        global 
$db$user$auth$template;
        global 
$config$phpbb_root_path$phpbb_admin_path$phpEx;
                    
        
$user->add_lang('mods/hello_world');
                            
        
// Set up the page
        
$this->tpl_name     'acp_hello_world';
        
$this->page_title     'ACP_HELLO_WORLD';
                            
        
// Set up general vars
        
$greeter    request_var('hello'''true);
        
$submit    = isset($_POST['submit']) ? true false;
        
$hello         '';
                            
        if (
$mode == 'hello_bertie')
        {
            
$hello $user->lang['BERTIE'];
        }
        else if (
$mode == 'hello_world')
        {
            
$hello $user->lang['WORLD'];
        }
        else if (
$mode == 'hello_user')
        {
            
$hello $user->data['username'];
        }
                             
        if (
$submit)
        {
            
trigger_error(sprintf($user->lang['SAY_HELLO'], $greeter$hello) . adm_back_link($this->u_action), E_USER_WARNING);
        }
        else
        {
            
$template->assign_vars(array(
                
'S_HELLO'            => $hello,
                
'S_SUBMIT'            => $this->u_action)
            );
        }
    }
}
            
?>


Tip
You can use the u_action field to create links back to the current module/mode.


1.5.2.4. Templates

Templates are one of the major differences between ACP modules and UCP/MCP modules. ACP modules are not affected by styles; their template files should go into /adm/style/ directory. UCP and MCP modules need styling, and thus use style-dependent templates.

<!-- INCLUDE overall_header.html -->
                
<
a name="maincontent"></a>
                                
<
h1>{L_HELLO}</h1>
                                    
<
p>{L_HELLO_EXPLAIN}</p>
                                
<
form id="acp_hello" method="post" action="{U_ACTION}">
    <
fieldset>
        <
legend>{L_HELLO} &nbsp;{S_HELLO}</legend>
        <
dl>
            <
dt><label for="hello">{L_HELLO_WHO}:</label></dt>
            <
dd><input name="hello" type="text" id="hello" maxlength="255" /></dd>
        </
dl>
                                            
    </
fieldset>
    <
class="submit-buttons">
        <
input class="button1" type="submit" id="submit" name="submit" value="{L_SUBMIT}" />&nbsp;
        <
input class="button2" type="reset" id="reset" name="reset" value="{L_RESET}" />
    </
p>
</
form>
                
<!-- INCLUDE 
overall_footer.html -->

1.5.2.5. Language

You can use the add_lang method of the user object to load custom language files for your module. The Mods directory is a good place to store those files. However, note that the language entries for module and mode titles needs to be placed in one of the default language files to take effect.


Tip
If the file language/en/mods/info_{module_name}.php (for example language/en/mods/info_ucp_karma.php) exists, it will automatically be included.


<?php
/** 
*
* hello_world [English]
*
* @package language
* @version $Id$
* @copyright (c) 2005 phpBB Group 
* @license http://opensource.org/licenses/gpl-license.php GNU Public License 
*
*/
                    
/**
* DO NOT CHANGE
*/
if (empty($lang) || !is_array($lang))
{
    
$lang = array();
}
                        
// DEVELOPERS PLEASE NOTE
//
// All language files should use UTF-8 as their encoding and the files must not contain a BOM.
//
// Placeholders can now contain order information, e.g. instead of
// 'Page %s of %s' you can (and should) write 'Page %1$s of %2$s', this allows
// translators to re-order the output of data while ensuring it remains correct
//
// You do not need this where single placeholders are used, e.g. 'Message %d' is fine
// equally where a string contains only two placeholders which are used to wrap text
// in a url you again do not need to specify an order e.g., 'Click %sHERE%s' is fine
                        
$lang array_merge($lang, array(
    
'HELLO'            => 'Hello',
    
'HELLO_EXPLAIN'    => 'Just a little example.',
    
'HELLO_WHO'        => 'Who says \'Hello\' ?',
    
'WORLD'            => 'World',
    
'SAY_HELLO'     => '%1$s says \'Hello %2$s\'',
                            
    
'BERTIE'    => 'Bertiezilla',
                    
));
            
?>