创建phpBB3的Module

概 要
这一章描述phpBB3 module系统。
phpBB3使用Module系统扩展Administration Panel (ACP), User Control Panel (UCP), and Moderator Control Panel (MCP)

目  录
* 1.5.1. 添加一个Module
* 1.5.2. 写一个Module
  o 1.5.2.1. Modules和Modes
  o 1.5.2.2. Info文件
     + 一个info文件例子
  o 1.5.2.3. Module类文件
  o 1.5.2.4. Templates文件
  o 1.5.2.5. Language文件

* 1.5.1. 添加一个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.

重要:需要A_MODULES权限增加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.

提示: Modules被组织在“cateories”下.

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.

提示: 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. 写一个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.
  o 1.5.2.1. Modules和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.
  o 1.5.2.2. Info文件
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).

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.
     + 一个info文件例子

<?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()
    {
    }

}
?>

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.
  o 1.5.2.3. Module类文件
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.

  o 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 -->

  o 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',
                    
));
            
?>