From phpBB Development Wiki

Contents 1 Introduction 2 Brief Tutorial 3 Sample ACP Module 3.1 Main class 3.2 Info Class 3.3 Language File 3.4 Sample Style HTML

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 ('filename' => 'mcp_foo'). 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:

<!-- INCLUDE mcp_header.html -->

Hello, World!

<!-- INCLUDE mcp_footer.html -->

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.

Sample ACP Module

Main class

includes/acp/acp_foo.php

class acp_foo
{
   var $u_action;
   var $new_config;
   function main($id, $mode)
   {
      global $db, $user, $auth, $template;
      global $config, $phpbb_root_path, $phpbb_admin_path, $phpEx;
      $user->add_lang('mods/foo');
      switch($mode)
      {
         case 'index':
            $this->page_title = 'ACP_FOO';
            $this->tpl_name = 'acp_foo';
            break;
      }

   }
}

Info Class

includes/acp/info/acp_foo.php

class acp_foo_info
{
    function module()
    {
        return array(
            'filename'    => '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()
    {
    }
}

Language File

language/en/mods/info_acp_foo.php

/**
* 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(
    '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

adm/style/acp_foo.html

<!-- INCLUDE overall_header.html -->

Hello, World!

<!-- INCLUDE overall_footer.html -->

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