Detalhes

Categoria: Joomla

Atualização: Terça, 21 Abril 2009 21:22

Autor: vovó Vicki

Acessos: 33499

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:

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:

O mod_boasvindas.php completo

O arquivo mod_boasvindas.php completo é o seguinte:

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.

O arquivo helper.php

O arquivo helper.php contém a classe helper que é usada para obter dados que serão mostrados na saída do módulo. Como já foi dito anteriormente, nossa classe helper terá apenas um método: getOla(). Este método retorna a mensagem 'Olá, receba as boas vindas'.

Aqui está o código:

Não existe uma regra que diz como dar um nome a uma classe helper, mas é bom fazê-lo como no exemplo porque fica mais fácil saber do que se trata e de identificar e localizar o que queremos.

Módulos mais sofisticados podem incluir solicitações ao banco de dados e outras funcionalidades nos métodos da classe helper.

:info: Observe que a palavra "Olá" está escrita de uma forma estranha. É que o "á" precisa ser definido em UTF-8, o padrão do Joomla.

O arquivo tmpl/default.php

O arquivo default.php é um modelo (template) que mostra a saída do módulo. O código é o seguinte:

É importante saber que o arquivo template tem o mesmo escopo que o arquivo mod_boasvindas.php. Isto significa que a variável $ola pode ser definida no arquivo mod_boasvindas.php e depois ser usada no arquivo default.php sem qualquer declaração extra ou chamada a funções.

O arquivo mod_boasvindas.xml

O mod_boasvindas.xml é usado para especificar quais arquivos o instalador precisa copiar e é usado pelo Module Manager (Administrador de Módulos) para determinar quais parâmetros são usados para configurar o módulo. Outras informações sobre o módulo também são especificadas neste arquivo.

O código de mod_boasvindas.xml é o seguinte:

:info: ATENÇÃO: Não use vogais acentuadas ou letras do ASCII expandido (tipo ç ou Ç) neste arquivo xml. O Joomla vai estrilar dizendo que NÃO ENCONTRA O ARQUIVO DE INSTALAÇÃO simplesmente porque não reconhece estes caracteres. Ou você deixa todos os acentos e c cedilhas de lado, ou os substitua pelos equivalentes em UTF-8. Observe que qo invés de "vovó Vicki" usei "vovo Vicki" :smile:

Não é por nada não, mas é que já me embananei mais de uma vez com este negócio de UTF-8. Espero que você não caia na mesma armadilha..."

Você deve ter notado que existem dois arquivos adicionais que ainda não foram mencionados: index.html e tmpl/index.html. Estes arquivos são incluídos para que estes diretórios não possam ser listados. Se um usuário tentar acessar estes diretórios através do navegador, receberá uma página em branco porque os arquivos index.html possuem apenas uma única linha:

Como o módulo não usa parâmetros, esta seção está vazia.

Pacote de instalação

Crie um diretório chamado mod_boasvindas. Coloque os arquivos mod_boasvindas.php, index.html e helper.php neste diretório. Crie um subdiretório chamado tmpl. Neste subdiretório coloque os arquivos default.php e index.html. A seguir, faça um pacote zip do diretório mod_boasvindas. Isto é tudo: o mod_boasvindas.zip é o pacote de instalação que o Joomla 1.5 espera receber para instalar o módulo.

Desejo sucesso a todos vocês!

:vovo: vovó Vicki

Referência

• Creating a Hello World Module for Joomla 1.5, exemplo dado no Wiki de Documentação do Developer Net.