Creating modules

Introduction
In phpBB3 you can create your own modules for the User, Moderator and Administration Control Panel. This approach has many advantages over creating the complete page from scratch as described in Adding pages:
 * You can manage the module in the ACP
 * You don't have to care about handling authorization
 * You get a navigation tree for free
 * The UCP/MCP/ACP template already contains things like pagination, breadcrumbs or confirmation messages

The rest of this tutorial describes how to create a MCP module - if you want to create UCP modules, you usually only need to replace all occurrences of "mcp" with "ucp". An ACP module sample can be found below

Brief Tutorial
You need two files (plus template files) to create a working module:
 * The first one goes into the includes/mcp/info directory and contains information like name of the module, available submodes and required Permissions. For a detailed description see Mcp/info.
 * The second file contains the actual code for the module. This file goes into the includes/mcp directory and must be named as defined in the mcp/info file . This file must also contain one class with that name.

class mcp_foo {	function main($id, $mode) {		$this->page_title = 'MCP_FOO'; $this->tpl_name = 'mcp_foo'; } }

Now you only need to create the template file (mcp_foo.html) and you're ready to install and test your first module:

Hello, World!

The chosen mode (defined in the mcp/info file) is available in the $mode parameter. Of course you can also use all features (Template system, DBAL, etc.) you know from normal phpBB pages. You just need to globalize variables like $db or $template, because your code is now running inside a function and not in the global scope. Here is a more advanced example:

class mcp_foo {	var $p_master;

function mcp_foo(&$p_master) {		$this->p_master = &$p_master; }

function main($id, $mode) {		global $template;

switch($mode) {			case 'index': $this->page_title = 'MCP_FOO_INDEX'; $this->tpl_name = 'mcp_foo_index'; $template->assign_var('GREETING', 'Hello, World!'); break;

case 'details': $this->page_title = 'MCP_FOO_DETAILS'; $this->tpl_name = 'mcp_foo_details';

//Display name of selected user $username = request_var('username', '', true); $template->assign_var('USERNAME', $username); break; }	} }

Here we also added a constructor which takes $p_master as parameter. This class is defined in includes/functions_module.php and contains useful information like the currently selected module, its parent and a list of all modules.

If you are still confused, take a look at all the current classes and see if you can't figure them out.

Main class
page_title = 'ACP_FOO'; $this->tpl_name = 'acp_foo'; break; }

} } ?>

Info Class
 'acp_foo',            'title'        => 'ACP_FOO',            'version'    => '1.2.3',            'modes'        => array( 'index'		=> array('title' => 'ACP_FOO_INDEX_TITLE', 'auth' => 'acl_a_foo_auth', 'cat' => array('')), ),       );    }

function install {   }

function uninstall {   } } ?> Tip: If all you want to do is to know how a module appears in the ACP change   in the above to. That authorises any user with access to the ACP to use the foo module.

Language File
<?php /** 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
 * DO NOT CHANGE

$lang = array_merge($lang, array( 'ACP_FOO_INDEX_TITLE'						=> 'Foo Index', )); ?>


 * note: Module language files will be included automatically when the module is loaded if the file name is formatted in the following way: info_[acp|mcp|ucp|module type]_[module_name].php, and when the file is located in the mods directory: language/en/mods/

Sample Style HTML
Hello, World!

--Geoffreak 02:21, 18 May 2007 (UTC)