Aldeia Numaboa

Um módulo é uma extensão pequena e flexível usada para compor uma página. Os módulos são usados em pequenas áreas da página e podem ser associados a diversos componentes. Alguns exemplos são os menus, o formulário de login, visitantes online e outros tantos que são instalados por padrão junto com o Joomla.

Este tutorial vai explicar como criar um módulo para o Joomla 1.5 mostrando a estrutura básica de arquivos. Esta estrutura básica pode ser ampliada para criar módulos mais elaborados.

A estrutura de arquivos

Há quatro arquivos básicos que são usados no modelo padrão de desenvolvimento de módulos. Este tutorial mostra como criar o módulo Boas Vindas:

• mod_boasvindas.php - Este arquivo é a entrada principal para o módulo. Nele são realizadas as rotinas de inicialização, são chamadas rotinas do helper (ajudante) para obter os dados necessários e é onde se inclui o modelo (template) que controlará a aparência do módulo.
• mod_boasvindas.xml - Este arquivo contém informações sobre o módulo. Ele define os arquivos que precisam ser instalados pelo instalador do Joomla e especifica os parâmetros de configuração do módulo.
• helper.php - Este arquivo contém a classe helper que é usada para realizar trabalhos de busca. É aqui que as informações a serem mostradas são obtidas, geralmente do banco de dados ou outra fonte qualquer.
• tmpl/default.php - Este é o modelo (template) do módulo. Este arquivo utiliza os dados coletados por mod_boasvindas.php e gera o HTML que deve ser mostrado na página.

O arquivo mod_boasvindas.php

O arquivo mod_boasvindas.php vai realizar três tarefas:

1. Incluir o arquivo helper.php, que contém a classe responsável pela coleta de dados
2. Chamar métodos da classe helper que são necessários para obter os dados
3. Incluir o modelo para apresentar o resultado.

A classe helper é definida no arquivo helper.php. Este arquivo é incluído com uma declaração require_once:

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

A declaração require_once é usada no lugar da require porque as funções helper (ajudantes) estão definidas dentro de uma classe e nós queremos que a classe seja definida apenas uma vez (require = requerer e once = uma vez).

A classe helper ainda não foi definida, mas, quando a definirmos, ela terá um método: getOla(). Neste exemplo básico nem seria necessário fazer isto - a mensagem "Olá, receba as boas vindas" que este método devolve poderia ser simplesmente incluída no modelo (template). O motivo de usarmos a classe helper é para demonstrar esta técnica básica.

Este módulo não usa qualquer tipo de parâmetro, mesmo assim vamos passá-los para o método do helper para que possam ser usados no futuro se decidirmos ampliar a funcionalidade do módulo.

O método da classe helper é chamado da seguinte forma:

$ola = modBoasVindasHelper::getOla( $params );

O mod_boasvindas.php completo

O arquivo mod_boasvindas.php completo é o seguinte:

<?php
/**
 * Boas Vindas! Ponto de Entrada do Módulo
 * 
 * @package    Joomla.Tutoriais
 * @subpackage Modules
 * @link       http://www.numaboa.com/
 * @license    Creative Commons
 * mod_boasvindas é software livre. Esta versão pode ser modificada devido
 * à licença Creative Commons de Atribuição, Uso Não-Comercial e
 * Compatilhamento pela mesma licença 2.5 Brasil
 */
 
// Evitar acesso direto
defined( '_JEXEC' ) or die( 'Área de acesso restrito' );
 
// Incluir as funções do helper apenas uma vez
require_once( dirname(__FILE__).DS.'helper.php' );
 
$ola = modBoasVindasHelper::getOla( $params );
require( JModuleHelper::getLayoutPath( 'mod_boasvindas' ) );
?>

A única linha que ainda não foi explicada é a para evitar acesso direto. Esta linha checa se este arquivo está sendo incluído através da aplicação Joomla. Ela é necessária para prevenir injeção de variáveis e outros problemas de segurança.