Criando um módulo simples para Joomla! 3.x

Segundo a documentação do Joomla!, "um módulo é uma extensão leve e flexível". Geralmente os módulos são utilizados para adicionar uma pequena funcionalidade em uma ou mais páginas, podendo ser posicionados em diversos locais, a depender do template utilizado.

Neste tutorial, você aprenderá a construir um módulo simples nos padrões Joomla! 3.x, isto é, compatível com as versões do Joomla! a partir da 3.0. Além disso, conhecerá a estrutura básica de um módulo, entendendo como ele funciona.

Estrutura de Arquivos

De acordo com a norma padrão, existem quatro arquivos básicos para o desenvolvimento de um módulo:

mod_helloworld.php - Este é o principal arquivo, que realiza todas as rotinas de inicialização, chama rotinas auxiliares para coletar os dados necessários e inclui o template que exibirá o módulo.
mod_helloworld.xml - Este arquivo contém informações sobre o módulo. Ele define os arquivos que o instalador do Joomla! precisa instalar e especifica os parâmetros de configuração do módulo, caso existam.
helper.php - Arquivo que contém a classe auxiliar responsável por obter as informações que serão exibidas pelo módulo (geralmente extraídas do banco de dados ou alguma outra fonte).
tmpl/default.php - Este é o template do módulo. Ele vai gerar o HTML que será exibido nas páginas.

Criando o arquivo mod_helloworld.php

Como se trata de um contexto bem básico, o arquivo mod_helloworld.php realizará apenas três tarefas:

Incluir o arquivo helper.php, responsável pela coleta de dados.
Invocar o método apropriado da classe helper para recuperar os dados.
Incluir o template para mostrar o resultado em HTML.

O resultado é um arquivo com o conteúdo abaixo:

<?php
// Impede o acesso direto.
defined( '_JEXEC' ) or die( 'Acesso restrito' );

// Inclui o arquivo helper.
require_once( dirname(__FILE__).'/helper.php' );

// Recupera os dados do helper. 
$hello = modHelloWorldHelper::getHello( $params );

// Invoca o template.
require( JModuleHelper::getLayoutPath( 'mod_helloworld' ) );
?>

Criando o arquivo helper.php

Como dito anteriormente, o helper.php contém a classe auxiliar que é responsável por obter os dados que serão exibidos pelo módulo. O conteúdo deste arquivo está abaixo. Atente para a função getHello(), que é acionada pelo mod_helloworld.php acima.

<?php
class modHelloWorldHelper
{
    /**
     * Retorna a mensagem de boas vindas.
     */    
    public static function getHello( $params )
    {
        return 'Hello, World!';
    }
}
?>

Criando o arquivo tmpl/default.php

Este arquivo apenas exibe o HTML. Neste contexto de módulo simples, é exibido um parágrafo como texto de boas vindas retornado pelo helper.

<?php 
// Impede o acesso direto.
defined( '_JEXEC' ) or die( 'Acesso restrito' );

// Exibe um parágrafo contendo a mensagem de boas vindas.
echo '<p>' . $hello . '</p>';
?>

Criando o arquivo mod_helloworld.xml

Este arquivo XML serve para que o instalador do Joomla! compreenda a estrutura do seu módulo, enxergando informações como nome, versão, autor, arquivos que fazem parte do módulo e parâmetros de configuração.

Veja abaixo o conteúdo do arquivo básico:

<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="3.1.0" client="site" method="upgrade">
    <name>Hello, World!</name>
    <author>Nome do Autor Aqui</author>
    <version>1.0.0</version>
    <description>Um módulo "Hello World" simples.</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>

Você deve ter observado que existem dois arquivos não mencionados previamente: index.html e tmpl/index.html. Eles são arquivos HTML em branco utilizados somente para impedir a listagem de diretórios, caso o servidor não tenha feito isso.

Criando o pacote de instalação

É possível ainda criar um pacote de instalação para o seu módulo, permitindo que ele seja instalado através do Gerenciador de Extensões do Joomla!. Para isso, crie um diretório com o mesmo nome do seu módulo (no nosso caso, mod_helloworld) e insira todos os arquivos criados anteriormente dentro desta pasta, respeitando a hiearquia de pastas. A estrutura final da sua pasta deverá ficar da seguinte forma:

mod_helloworld/
    helper.php
    index.html
    mod_helloworld.php
    mod_helloworld.xml
    tmpl/
        default.php
        index.html

Observe que os arquivos index.html vazios também precisaram ser inseridos, pois o Joomla! procurará por todos os arquivos listados no seu XML de configuração (cada arquivo entre as tags <filename> e </filename>).

Para que vocẽ possa utilizar como referência, criei o pacote de instalação do nosso módulo Hello World. Pode baixar e reutilizar à vontade.

Conclusão

O desenvolvimento de um módulo para Joomla! é um processo simples e direto. Isso permite que o desenvolvedor possa se preocupar apenas com a complexidade das suas regras de negócio.

Este tutorial foi construído com base neste artigo da documentação do Joomla!, acessado em 06/08/2014.

#a3a3a3

Criando um módulo simples para Joomla! 3.x