J3.x:Creating a simple module/Developing a Basic Module/es

Joomla! 

3.x

Tutorial

Crear un módulo simple

"'Artículos de esta Serie"'

• Introducción
• Desarrollo de un Módulo Básico
• Utilizar la Base de datos
• Agregar Campos de Formulario
• Agregar Actualización Automática
• Agregar un archivo secuencia de comandos instalar-desinstalar-actualizar

Esta es una serie de artículos múltiples sobre cómo crear un módulo para Joomla! Versión . Puedes navegar por los artículos en esta serie usando el menú desplegable de navegación.

Comienza con la Introducción y navega por los artículos de esta serie usando el botón de navegación en la parte inferior o en el cuadro de la derecha ("Artículos de esta serie").

Los módulos son una extensiones ligeras y flexibles. Se utilizan para pequeñas partes de la página que generalmente son menos complejas y son capaces de ser vistos a través de diferentes componentes.

Puedes ver muchos ejemplos de módulos en la instalación estándar de Joomla!: Menús - Últimas Noticias - Formulario de inicio de sesión y muchos más.

En este tutorial se explica cómo realizar la creación de un módulo simple Hello World. A través de este tutorial vamos a aprender la estructura básica del archivo de un módulo. Esta estructura básica puede luego ser ampliada para producir módulos más elaborados.

Estructura del archivo

Hay cuatro tipos básicos de archivos que se utilizan en el patrón estándar del desarrollo de un módulo:

• mod_helloworld.php - Este archivo es el principal punto de entrada para el módulo. Llevará a cabo las rutinas de inicialización necesarias, llamará a rutinas auxiliares para recopilar todos los datos necesarios e incluirá la plantilla que va a mostrar el módulo de salida.

• mod_helloworld.xml - Este archivo contiene información sobre el módulo. Define los archivos que necesitan ser instalados por el instalador de Joomla! y especifica los parámetros de configuración para el módulo.

• helper.php - Este archivo contiene la clase helper que se utiliza para hacer el trabajo real en la recuperación de la información que se muestra en el módulo (generalmente a partir de la base de datos o alguna otra fuente).

• tmpl/default.php - Esta es la plantilla del módulo. Este archivo va a tomar los datos recogidos por mod_helloworld.php y generar el código HTML que se mostrará en la página.

Crear el archivo mod_helloworld.php

El archivo mod_helloworld.php realiza tres tareas:

• incluir el archivo helper.php que contiene la clase que se utiliza para recoger los datos necesarios
• invocar el método de la clase helper adecuado para recuperar los datos
• incluir la plantilla para mostrar la salida.

La clase helper se define en nuestro archivo helper.php. Este archivo se incluye con una declaración require_once:

require_once dirname(__FILE__) . '/helper.php';

require_once se utiliza porque nuestro helper son funciones definidas dentro de una clase y sólo queremos que la clase sea definida una vez.

Nuestra clase helper no se ha definido aún, pero cuando lo sea, contendrá un método: getHello(). Para nuestro ejemplo básico, no es realmente necesario - el mensaje "Hola, Mundo" que este método devuelve simplemente podría ser incluido en la plantilla. Utilizamos una clase helper para demostrar esta técnica básica.

Nuestro módulo en la actualidad no se utiliza ningún parámetro, pero vamos a pasar al método helper uno de todos modos, así puede ser utilizado más tarde si decidimos ampliar la funcionalidad de nuestro módulo.

El método de de la clase helper se invoca de la siguiente manera:

$hello = modHelloWorldHelper::getHello($params);

Archivo mod_helloworld.php completo

El archivo mod_helloworld.php completo es el siguiente:

<?php
/**
 * Hello World! Module Entry Point
 * 
 * @package    Joomla.Tutorials
 * @subpackage Modules
 * @license    GNU/GPL, see LICENSE.php
 * @link       http://docs.joomla.org/J3.x:Creating_a_simple_module/Developing_a_Basic_Module
 * mod_helloworld is free software. This version may have been modified pursuant
 * to the GNU General Public License, and as distributed it includes or
 * is derivative of works licensed under the GNU General Public License or
 * other free or open source software licenses.
 */

// No direct access
defined('_JEXEC') or die;
// Include the syndicate functions only once
require_once dirname(__FILE__) . '/helper.php';

$hello = modHelloWorldHelper::getHello($params);
require JModuleHelper::getLayoutPath('mod_helloworld');

Una línea que no hemos explicado hasta ahora es la primera. Esta línea de comprobaciones es para asegurarse que este archivo está siendo incluido desde la aplicación Joomla!. Esto es necesario para evitar la inyección de variables y otros posibles problemas de seguridad.

Crear el archivo helper.php

El archivo helper.php contiene la clase helper que se utiliza para recuperar los datos que se muestran en la salida del módulo. Como se indicó anteriormente, nuestra clase helper tendrá un método: getHello(). Este método devolverá el mensaje 'Hola, Mundo'.

Aquí está el código para el archivo helper.php:

<?php
/**
 * Helper class for Hello World! module
 * 
 * @package    Joomla.Tutorials
 * @subpackage Modules
 * @link http://docs.joomla.org/J3.x:Creating_a_simple_module/Developing_a_Basic_Module
 * @license        GNU/GPL, see LICENSE.php
 * mod_helloworld is free software. This version may have been modified pursuant
 * to the GNU General Public License, and as distributed it includes or
 * is derivative of works licensed under the GNU General Public License or
 * other free or open source software licenses.
 */
class ModHelloWorldHelper
{
    /**
     * Retrieves the hello message
     *
     * @param   array  $params An object containing the module parameters
     *
     * @access public
     */    
    public static function getHello($params)
    {
        return 'Hello, World!';
    }
}

No hay ninguna regla que indique que como debemos nombrar nuestra clase helper, pero es útil hacerlo así, por que es fácilmente identificable y localizable. Ten en cuenta que es necesario usar este formato si planeas usar el plugin com_ajax.

Módulos avanzados pueden incluir solicitudes de base de datos u otro tipo de funcionalidad en el método de la clase helper.

Crear el archivo tmpl/default.php

El archivo default.php de plantilla es el que muestra la salida del módulo.

El código para el archivo default.php es el siguiente:

<?php 
// No direct access
defined('_JEXEC') or die; ?>
<?php echo $hello; ?>

Un punto importante a tener en cuenta es que el archivo de plantilla tiene el mismo alcance que el archivo mod_helloworld.php. Lo que esto significa es que la variable $hello puede ser definida en el archivo mod_helloworld.php y a continuación, utilizala en el archivo de plantilla sin ningún tipo de declaraciones extra o llamadas a funciones.

Crear el archivo mod_helloworld.xml

El mod_helloworld.xml se utiliza para especificar los archivos que el programa de instalación necesita copiar y es utilizado por el Módulo de Administrador para determinar qué parámetros se utilizan para configurar el módulo. Otra información sobre el módulo también se especifica en este archivo.

El código de mod_helloworld.xml es como sigue:

<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="3.1.0" client="site" method="upgrade">
    <name>Hello, World!</name>
    <author>John Doe</author>
    <version>1.0.0</version>
    <description>A simple Hello, World! module.</description>
    <files>
        <filename>mod_helloworld.xml</filename>
        <filename module="mod_helloworld">mod_helloworld.php</filename>
        <filename>index.html</filename>
        <filename>helper.php</filename>
        <filename>tmpl/default.php</filename>
        <filename>tmpl/index.html</filename>
    </files>
    <config>
    </config>
</extension>

Archivos Manifest explica los detalles técnicos de los elementos utilizados en el archivo XML.

Notarás que hay dos archivos adicionales que aún no hemos mencionado: index.html y tmpl/index.html. Estos archivos son incluidos para que estos directorios no se puede navegar. Si un usuario intenta apuntar su navegador a estas carpetas, el archivo index.html se mostrará. Estos archivos se pueden dejar vacíos o puede contener una simple línea:

<html><body bgcolor="#FFFFFF"></body></html>

que mostrará una página vacía.

Ya que nuestro módulo no hace uso de ningún campo de formulario, la configuración de la sección está vacía.

Installing and Viewing the Module

To install the module, zip up the parent directory of your source files, to create a file called mod_helloworld.zip. Note that it needs to be a .zip file because the server needs to be able to extract it using Apache's mod_zlib library. Go into Joomla admin, to the Extensions / Manage / Install form, click on the Update Package File tab, and upload your zip file. You should find that the module installs ok. If it doesn't, then compare carefully your code with the code above, and ensure your source code files are named correctly. To make the module visible on your site web pages go into the Extensions / Modules listing and click on the Hello World module to edit it.

1. set the Status to Published
2. select the Position where the module should appear (if you're unsure about which Position to set, then navigate to Extensions / Templates / Styles, check which template is assigned on your web pages, then follow this guide to finding the module positions).
3. on the Menu Assignment tab set the Module Assignment to "On all pages"

Save and Close your edit form. Now if you navigate to your site you should see "Hello, World!" displayed in your chosen module position.

Conclusión

El desarrollo de un módulo para Joomla! es bastante simple, un proceso sencillo. Utilizando las técnicas descriptas en este tutorial, una interminable variedad de módulos pueden ser desarrollados con poco esfuerzo.

Prev: Introducción

Sig: Utilizar la base de datos