Documentation

1.5. Using the phpBB3.0 Module System

Kellanved

smithy_dll

$Id: v3_modules.xml 52 2007-12-09 19:45:45Z jelly_doughnut $

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).

Example 1.8. A sample info file

                         					
<?php
/** 
*
* @package acp
* @version $Id: v3_modules.xml 52 2007-12-09 19:45:45Z jelly_doughnut $
* @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()
	{
	}

}
?>
					

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.

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: v3_modules.xml 52 2007-12-09 19:45:45Z jelly_doughnut $
* @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>
	<p 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: v3_modules.xml 52 2007-12-09 19:45:45Z jelly_doughnut $
* @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',
					
));
			
?>