Creación simple de Módulo Joomla 2.5

Un módulo, a diferencia de un artículo común, puede consultar información de nuestra base de datos, contar con programación en PHP, JavaScript, agregar estilos CSS y demás detalles que mejoran nuestra aplicación. Por ejemplo, un slider de imágenes, un menú nuevo, una lista de categorías. Aprendamos la estructura básica para generar nuestros módulos e instalarlos correctamente en Joomla 2.5.

Lo que relataremos a continuación es información substraída de la documentación oficial de Joomla, y probada al 100% por nosotros.

Para comenzar este tutorial deberán conocer lo básico de Joomla, haberlo instalado y utilizado preferentemente, para estar familiarizado con los conceptos básicos de su uso.

Al finalizar este tutorial, tendrán su primer módulo, instalado y funcionando en su proyecto de Joomla. También conocerán la estructura de archivos que interpretará el sistema, conociendo cómo y dónde modificar los archivos para lograr el comportamiento o estilo deseado.

Creación de la estructura de archivos Joomla 2.5

La estructura de árbol de Joomla es muy rígida para la creación de cualquier tipo de extensión. Debemos crear nuestra estructura, y para eso podremos usar el IDE (Dreamweaver, Eclipse, NetBeans, etc.) o editor (Gedit, Notepad++, etc.) que más nos guste.

¡Importante! No creemos nuestro módulo dentro de nuestro sitio Joomla. Luego la instalaremos y se creará automáticamente la carpeta correspondiente. Creemos la estructura como un nuevo proyecto preferentemente.

Primero crearemos nuestra carpeta contenedora. Nuestro módulo será una simple lista de categorías de artículos del sitio. Llamemos, por ejemplo, “mod_sitecategories”; utilizando el prefijo “mod_” para aclarar que se trata de un módulo, y el resto para saber sobre qué tratará dicho módulo.

Dentro de la carpeta que creamos, debemos crear estos archivos:

·         mod_sitecategories.xml

·         mod_sitecategories.php

·         helper.php

·         index.html

·         en-GB.mod_sitecategories.ini

·         es-ES.mod_sitecategories.ini

·         tmpl (folder)

o   tmpl/default.php

o   tmpl/ordered_list.php

o   tmpl/index.html

Para entender mejor esta estructura, vamos archivo por archivo a analizarlo.

mod_sitecategories.xml

Este archivo contendrá toda la metadatos de nuestro módulo, su información y parámetros. La estructura del archivo deberá ser respetada tal cual está aquí escrita:

<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="1.6.0" client="site" method="install">
        <name>Site Categories</name>
        <author>Federico Dávila</author> 
        <creationDate>2013</creationDate> 
        <copyright>Todos los derechos reservados para Laboratorio Software Libre UTN FRA.</copyright> 
        <license>GPL 2.0</license> 
        <authorEmail>info@lslfra.com.ar</authorEmail> 
        <authorUrl>www.lslfra.com.ar</authorUrl> 
        <version>1.0.0</version> 
        <description>Provee la lista de categorías del sitio</description>
    <!-- Listing of all files that should be installed for the module to function -->
        <files>
        <!-- The "module" attribute signifies that this is the main controller file -->
               <filename module="mod_sitecategories"> mod_sitecategories.php</filename>
               <filename>index.html</filename>
               <filename>helper.php</filename>
               <filename>tmpl/default.php</filename>
               <filename>tmpl/ordered_list.php</filename>
               <filename>tmpl/index.html</filename>
        </files>
 
    <languages>
        <!-- Any language files included with the module -->
        <language tag="en-GB">en-GB.mod_sitecategories.ini</language>
        <language tag="es-ES">es-ES.mod_sitecategories.ini</language>
    </languages>
 
    <!-- Optional parameters -->
        <config>
            <fields name="params">
                <fieldset name="basic">
                    <field 
                        name="moduleclass_sfx" 
                        type="text" 
                        default="" 
                        label="LABEL_CLASS_SUFFIX" 
                        description="DESC_MOD_SUFFIX">
                    </field>
                    <field 
                        name="@spacer" 
                        type="spacer" 
                        default="" 
                        label="" 
                        description="">
                    </field>
                    <field 
                        name="categoriescount" 
                        type="text" 
                        default="5" 
                        label="LABEL_CATEGORIES_COUNT" 
                        description="DESC_CATEGORIES_COUNT">
                    </field>
                    <field 
                        name="layout" 
                        type="list" 
                        default="default" 
                        label="LABEL_CATEGORIES_LAYOUT" 
                        description="DESC_CATEGORIES_LAYOUT">
                       <option
                               value="default">Unordered List</option>
                       <option
                       value="ordered_list">Ordered List</option>
                    </field>
                </fieldset>
            </fields>
    </config>
</extension>

El tag FIELDS es uno de los de mayor importancia. Este refiere a los parámetros que encontramos del lado derecho al habilitar un módulo, son los campos de configuración. En este caso configuramos cuatro campos:

·         Module Class Suffix: este campo lo tienen prácticamente todos los módulos. Refiere a una extensión para el nombre de las clases en las CSS.

·         Spacer: un simple separador.

·         El tercer campo es un selector que se refiere a la cantidad de categorías que deseamos mostrar en nuestro módulo.

·         El último campo es la forma en que se representarán las categorías. Este layout irá en la carpeta TMPL.

Otro punto a tener en cuenta son las variables de entorno; aquellas palabras escritas en mayúsculas, como "LABEL_CATEGORIES_COUNT". Estas variables deberemos incluirlas en nuestros archivos de idiomas, y serán traducidas automáticamente con Joomla 2.5.

mod_sitecategories.php

Este archivo será un simple controlador del modelo MVC, dirigiendo los archivos y funciones.

<?php
//don't allow other scripts to grab and execute our file
defined('_JEXEC') or die('Direct Access to this location is not allowed.');
 
//This is the parameter we get from our xml file above
$categoriesCount = $params->get('categoriescount');
 
// Include the syndicate functions only once
require_once dirname(__FILE__).'/helper.php';
 
//Returns the path of the layout file
require JModuleHelper::getLayoutPath('mod_sitecategories’, $params->get('layout', 'default'));
?>

helper.php

Aquí ubicaremos la lógica de nuestro módulo, por ejemplo consultando los datos que necesitamos para mostrar.

<?php
//No access
defined( '_JEXEC' ) or die;
 
//Add database instance
$db = JFactory::getDBO();
 
//Pass in query - Limit by the categoriesCount param
$query = "SELECT title FROM #__categories LIMIT {$categoriesCount}";
 
//Run it
$db->setQuery($query);
 
//Load it as an object into the variable "$rows"
$rows = $db->loadObjectList();
?>

Cuando este archivo es ejecutado, consulta a través de SQL los campos “title” de la tabla #__categories (siendo #__ el prefijo que seleccionamos en la instalación de Joomla 2.5), limitando la cantidad de resultados por el parámetro de configuración de nuestro módulo categoriesCount. Luego, utilizando loadObjectsList, los resultados serán cargados en la variable $rows, la cual podremos iterar dentro del archivo default.php que veremos más adelante.

index.html

Este archivo sólo se utilizaba para evitar que el usuario acceda a los módulos de forma directa, a través de la dirección URL.

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

tmpl/default.php

<ul>
    <?php
        foreach ($rows as $row){ ?>
        <li>
        <?php
               echo JText::sprintf('CATEGORY_LABEL', $row->title);
        ?>
        </li>
  <?php
        }
  ?>
</ul>

Este archivo ejecuta la vista por defecto de nuestro módulo. Aquí cargaremos la parte visual de nuestro código. Esencialmente crearemos el código HTML, utilizando todas las herramientas a nuestro alcance. En este caso, iteraremos la variable $row creada en el archivo helper.php, cargando la lista de categorías de nuestro sitio.

tmpl/ordered_list.php

<?php defined( '_JEXEC' ) or die( 'Restricted access' ); ?>
<ol>
    <?php
        foreach ($rows as $row){
    ?>
        <li>
            <?php
               echo JText::sprintf('CATEGORIES _LABEL', $row-> title);
            ?>
        </li>
  <?php } ?>
</ol>

Este es el layout de la lista ordenada. La única diferencia es que esta utilizará una lista numérada y no tendrá parámetros descripción.

tmpl/index.html

Al igual que el index.html anterior, es sólo por cuestiones de aislamiento y seguridad.

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

xx-XX.mod_sitecategories.ini

Estos son los archivos de idiomas. El formato es un simple clave=valor.

LABEL_CATEGORIES_COUNT="Categories Count"
DESC_CATEGORIES_COUNT="The number of categories to display"
LABEL_CLASS_SUFFIX ="Module Class Suffix"
DESC_MOD_SUFFIX ="Add a module css class suffix"
DESC_MODULE="Website Categories"
CATEGORY_LABEL="%s"

LABEL_CATEGORIES_COUNT="Cantidad de categorías"
DESC_CATEGORIES_COUNT="Número de categorías a mostrar"
LABEL_CLASS_SUFFIX ="Module Class Suffix"
DESC_MOD_SUFFIX ="Agregar un sufijo de la clase CSS para el módulo"
DESC_MODULE="Categorías del Website"
CATEGORY_LABEL="%s"

Empaquetar e instalar

Lo primero que debemos hacer es comprimir en ZIP la carpeta completa mod_sitecategories. Luego nos dirigimos a nuestro administrador Joomla, Administración de Extensiones, seleccionamos nuestro zip e instalamos.

Luego podremos ir a los módulos y configurarlo, para ver los resultados.