Crear Módulos en el ACP

Viendo el interés de muchos usuarios lanzan desarrollar sus propios MODs sin tener aun el conocimiento necesario para hacerlo, me atrevo a posteaer esta guía hecha por mi y basaba en el articulo de la Wiki de phpBB Using the phpBB3.0 Module System, para ayudarlos en su labor de desarrollar y mas que todo de aprender.
La guía puede llegar a tornarse algo compleja, así que tratare de ser lo mas claro posible, dejando de comienzo algunos puntos claros:

• Es para la creación de módulos en el ACP, mas no del UCP ni del MCP, aunque su funcionamiento sea exactamente igual.
• No muestra como enlazar funciones de phpBB con el módulo que vamos a crear.
• No enseña a crear MODs ni nada por el estilo solo modulos en el ACP de phpBB.

Dejo estos puntos claros para que las dudas que surjan, sean referentes a la guía y no a los puntos anteriores o similares.
Tomare como base el típico ejemplo del "Hola Mundo", que se podría decir es el primer programa que hacemos todos en cualquier lenguaje de programación.
El tutorial consta de la creación de 4 archivos y la edición de 1.
NOTA: Recuerden NO dejar ningún espacio en blanco al principio de los archivos antes del <?php

Sin mas rodeos comienzo, así que los archivos a crear con sus correspondientes rutas son:

• includes/acp/acp_hola_mundo.php
• includes/acp/info/acp_hola_mundo.php
• language/xx/mods/hola_mundo.php (xx es el o los idiomas en que vallan a desarrollar el módulo)
• adm/style/acp_hola_mundo.html

Todos los archivos están documentados mostrando que hace cada cosa, esto para hacer la guía mas breve.

Clase principal del Hola Mundo (includes/acp/acp_hola_mundo.php):

Código: Seleccionar todo

<?php

/**
 *
 * @package acp
 * @version $Id$
 * @copyright (c) 2007 phpBB Group 
 * @license http://opensource.org/licenses/gpl-license.php GNU Public License 
 *
 */
/**
 * @ignore
 */
if (!defined('IN_PHPBB')) {
    exit;
}

/**
 * @package acp
 */
class acp_hola_mundo {

    var $action;

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

        // Configuración inicial del módulo
        $user->add_lang('mods/hola_mundo'); //archivo de idioma language/xx/mods/
        $this->tpl_name = 'acp_hola_mundo'; //plantilla HTML del adm/style/
        $this->page_title = 'ACP_HELLO_WORLD'; //título del modulo en el ACP
        // Variables del módulo
        $hello = request_var('hello', '', true);
        $submit = request_var('submit', '', true) ? true : false;

        switch ($mode) {
            case 'index';
                $name = $user->data['username']; //Obtiene el nombre del usuario
                $info = $user->lang['CONFIG_UPDATED'] . adm_back_link($this->action); //Aviso de confimación
                break;
            case 'hello_world':
                $name = $user->lang['WORLD']; //Obtiene la varible de idioma 'WORLD'
                $info = sprintf($user->lang['SAY'], $hello, $name) . adm_back_link($this->action); //Aviso creado por nosotros
                break;
        }

        if ($submit) {
            trigger_error($info); // Muestra el aviso definido anteriormente.
        } else {
            $template->assign_vars(array(
                // Asignación de variables del sistema
                'S_NAME' => $name,
                'S_MODE' => $mode,
            ));
        }
    }

}

?>

Clase de información del Hola Mundo (includes/acp/info/acp_hola_mundo.php):

Código: Seleccionar todo

<?php

/**
 *
 * @package acp
 * @version $Id$
 * @copyright (c) 2005 phpBB Group
 * @license http://opensource.org/licenses/gpl-license.php GNU Public License
 *
 */

/**
 * @package module_install
 */
class acp_hola_mundo_info {

    function module() {
        return array(
            'filename' => 'acp_hola_mundo', // Nombre del archivo
            'title' => 'ACP_HELLO_WORLD', // Titulo de la pagina en el ACP
            'version' => '0.0.0', // Versión de nuestro módulo
            'modes' => array(//Sub-módulos de nuestro modulo
                'index' => array('title' => 'INDEX_HELLO_WORLD', 'auth' => 'acl_a_user', 'cat' => array('')), //Módulo de Configuración Inicial
                'hello_world' => array('title' => 'HELLO_WORLD', 'auth' => 'acl_a_user', 'cat' => array('')), //Módulo de Hola Mundo
            ),
        );
    }

    function install() {
        
    }

    function uninstall() {
        
    }

}

?>

En esta clase se hace necesario definir algunas funciones, además como punto importante a tener en cuenta, es que este archivo se debe llamar exactamente igual al de la clase principal, en este caso los he llamado a ambos "acp_hola_mundo.php".

filename: nombre del archivo que debe ser igual al nombre del archivos de la Clase principal.
title: Variable de idioma que tendrá el nombre del Módulo.
version: Versión del Módulo.
modes: Los Sub-módulos asociados a nuestro modulo.
title: Variable de idioma del Sub-módulo.
auth: Permisos que le voy a asignar al Modulo, puede ser mas de 1 separado por && (ej: 'acl_a_board && acl_a_group')
cat: Categoría donde quedara empotrado nuestro módulo, en este caso la dejamos vacía ya que mas adelante mostrare como asignarla desde el ACP.


Archivos donde estarán las variables de idioma (language/es/mods/hola_mundo.php):

Código: Seleccionar todo

<?php

/**
 *
 * hello_world [Spanish]
 *
 * @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' => 'Hola',
            'WORLD' => 'Mundo',
            'HELLO_WORLD' => 'Hola Mundo',
            'HELLO_WORLD_EXPLAIN' => 'Explicación del Hola Mundo.',
            'ENABLE_HELLO_WORLD' => 'Habilitar "Hola Mundo"',
            'HELLO_WHO' => 'Quien dijo "Hola" ?',
            'SAY' => '%1$s dijo "Hola %2$s"',
        ));
?>

En este caso Español, pero lo pueden hacer en los idiomas que quieran y adjuntarlos a las carpetas correspondientes.


Archivo de estilo para nuestro módulo en el ACP (adm/style/acp_hola_mundo.html):

Código: Seleccionar todo

<!-- INCLUDE overall_header.html -->

<a name="maincontent"></a>

<h1>{L_HELLO_WORLD}</h1>

<p>{L_HELLO_WORLD_EXPLAIN}</p>

<form id="acp_hello" method="post" action="{U_ACTION}">
    <fieldset>
        <legend>{L_HELLO} &nbsp;{S_NAME}</legend>
        <dl>
            <!-- IF S_MODE == index -->
            <dt><label for="hello">{L_ENABLE_HELLO_WORLD}</label></dt>
            <dd>
                <label><input type="radio" name="enable" value="1" class="radio" checked="checked" /> {L_YES}</label>
                <label><input type="radio" name="enable" value="0" class="radio" /> {L_NO}</label>
            </dd>
            <!-- ELSEIF S_MODE == hello_world  -->
            <dt><label for="hello">{L_HELLO_WHO}:</label></dt>
            <dd><input name="hello" type="text" id="hello" maxlength="255" /></dd>
            <!-- ENDIF -->
        </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 -->

En este archivo van incluidas las dos opciones de los sub-módulos que creamos en el ACP.

Por último en el manejo de archivos debemos agregar las variables de idioma que contendran los titulos de módulo y los sub-módulos, para esto debemos editar el archivo language/es/acp/common.php y agregar al final del archivo antes de ?> lo siguiente:

Código: Seleccionar todo

// Hola mundo
$lang = array_merge($lang, array(
        'ACP_HELLO_WORLD'   => 'Hola mundo en el ACP',
        'INDEX_HELLO_WORLD'   => 'Configuración inicial',
        'HELLO_WORLD'   => 'Hola mundo',
));  

---

Ahora viene la parte interesante y en la que muchos pueden perderse, que es la y creación y asignación del módulo a la pestaña MODs del ACP.
Luego de haber creado y subido los archivos al foro, debemos ir a:
ACP >> Sistema >> ADMINISTRACIÓN DE MÓDULOS >> Ir al Panel de Administración (ACP) >> Mods.

Aquí encontraran un campo de texto y un botón que dice Crear nuevo módulo, hay que introducir la variable de idioma que tiene el módulo ACP_HELLO_WORLD y que definimos anteriormente en el archivo language/es/acp/common.php
dejo una imagen para mejor comprensión.

La configuración que deben poner allí es la siguiente:
Tipo de módulo: Módulo
Padre: Mods
Módulo habilitado: SI
Módulo mostrado: SI
Elegir módulo: Hola Mundo en el ACP [acp_hola_mundo]
Elegir modo: Configuración Inicial
Tal como muestro en la imagen



Envían y ya les debe aparecer el módulo creado y habilitado, si no les aparece habilitado lo habilitan.

Ahora a este módulo hay que asignarle los sub-módulos, para esto hacemos un proceso similar:
ACP >> Sistema >> ADMINISTRACIÓN DE MÓDULOS >> Ir al Panel de Administración (ACP) >> Mods >> Hola mundo en el ACP.

Aquí ya no van a la opción de Crear nuevo módulo, sino a la que hay a la derecha que dice:

1. Añadir módulo que es de opción desplegable,
2. Buscan Hola Mundo en el ACP [acp_hola_mundo]
3. Escogen Configuración inicial,
4. Luego click Añadir módulo,
5. Sale una opción para confirmar, le dan SI y el sub-módulo se agregara,
6. Luego de esto lo Habilitan ya que por defecto esta deshabilitado.

Hacen lo mismo para el segundo sub-módulo que se llama Hola Mundo

Ya con esto habremos terminado, podran ir a la pestaña MODs y encontrar el módulo habilitado y funcionado


Cualquier duda referente a la Guía no duden en preguntar e intentare resolverla lo antes posible, ojala les sea de utilidad.

Fuera de tema

Este Script y tutorial lo hice yo (Alorse) para los usuarios de phpBB-es.COM, así que si lo quieres sacar de esta web, respeta la Autoria y cita la página exacta de donde lo sacaste, osea esta.