J3.x:Creating a simple module/Developing a Basic Module/pt-br

Joomla! 

3.x

Tutorial

Criando um módulo simples

Articles in this Series

• Introduction
• Developing a Basic Module
• Using the Database
• Adding Form Fields
• Adding Auto Update
• Adding an install/uninstall/update script file

Esta é uma série de múltiplos artigos sobre a forma de criar um módulo para Joomla! Versão . Você pode navegar pelos artigos desta série, usando o menu de navegação

Comece com a Introdução, e navegue pelos artigos desta série usando o botão de navegação abaixo ou a caixa à direita (Artigos desta série).

Um módulo é uma extensão leve e flexível. São usados para adicionar pequenas funcionalidades na página e são geralmente menos complexos e capazes de serem visto através de componentes diferentes.

Você pode encontrar muitos exemplos de módulos na instalação padrão do Joomla: - Menu - Artigos - Últimas Notícias -Formulário de Acesso - e muito mais.

N.T. disponível em: <seu site>/administrator/index.php?option=com_installer&view=manage

Este tutorial irá explicar como criar um módulo Hello World simples. Através deste tutorial, você aprenderá a estrutura básica de um módulo. Esta estrutura básica pode então ser expandida para produzir módulos mais elaborados.

Estrutura dos Arquivos

Existem quatro arquivos básicos que são usados no desenvolvimento de módulo:

• mod_helloworld.php - Este arquivo é o ponto de entrada principal do módulo. Ele executará todas as rotinas de inicialização necessárias, rotinas auxiliares de chamada para coletar quaisquer dados necessários e incluirá o modelo que exibirá a saída do módulo.

• mod_helloworld.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 (auxiliar) que é usada para fazer o trabalho real na recuperação das informações a serem exibidas no módulo (geralmente a partir do banco de dados ou alguma outra fonte).

• tmpl/default.php - Este é o template do módulo. Este arquivo pegará os dados coletados pelo mod_helloworld.php e gerará o HTML que será exibido na página.

Criando mod_helloworld.php

O arquivo mod_helloworld.php executará três tarefas:

• Incluir o arquivo helper.php que contém a classe a ser usada para coletar os dados necessários
• Invocar o método apropriado da classe helper para a recuperação dos dados
• Incluir o template para exibir o resultado.

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

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

require_once é usado porque nossas funções auxiliares são definidas dentro de uma classe helper, e só queremos que a classe seja incluída apenas uma vez.

Nossa classe helper ainda não foi definida, mas quando for, ela conterá um método: getHello(). Para o nosso exemplo básico, não é realmente necessário fazer isso - a mensagem "Hello, World" que esse método retorna simplesmente pode ser incluída no modelo. Usamos uma classe auxiliar aqui para demonstrar essa técnica básica.

Atualmente, nosso módulo não usa parâmetros, mas vamos passá-los para o método do helper de qualquer forma para que possa ser usado mais tarde se decidimos expandir a funcionalidade do nosso módulo.

O método da classe helper é invocado da seguinte maneira:

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

Arquivo mod_helloworld.php concluído

O arquivo completo mod_helloworld.php é o seguinte:

<?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');

A única linha que não explicamos até agora é a primeira linha. Esta linha verifica se este arquivo está sendo incluído a partir do Joomla!. Isso é necessário para evitar a injeção de variáveis e outros problemas potenciais de segurança.

Criando helper.php

O arquivo helper.php contém essa classe auxiliar que é usada para recuperar os dados a serem exibidos na saída do módulo. Como mencionado anteriormente, nossa classe auxiliar terá um método: getHello(). Esse método retornará a mensagem 'Hello, World'.

Aqui está o código do arquivo 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!';
    }
}

Não há nenhuma regra afirmando que devemos nomear nossa classe auxiliar (helper) como fizemos, mas é útil para que seja facilmente identificável e localizável. Observe que é obrigatório estar nomeada dessa forma se você planeja usar o plugin com_ajax.

Os módulos mais avançados podem incluir requisições em banco de dados ou outras funcionalidades dentro dos métodos da classe helper.

Criando tmpl/default.php

O arquivo default.php é o template que exibe a saída do módulo.

O código para o default.php é o seguinte:

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

Um ponto importante é que o arquivo de template tem o mesmo escopo do mod_helloworld.php. Isso significa que a variável $hello pode ser definida no arquivo mod_helloworld.php e então utilizada no arquivo de template sem nenhuma declaração externa ou chamada de função.

Criando mod_helloworld.xml

O arquivo mod_helloworld.xml é usado para especificar quais arquivos o instalador necessita copiar e é usado pelo Gerenciador de Módulos para determinar quais parâmetros são usados para configurar o módulo. Outras informações sobre o módulo são também especificados nesse arquivo.

O código do mod_helloworld.xml é o seguinte:

<?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>

Manifest files explica os detalhes técnicos dos elementos usados no arquivo XML.

Você irá notar que lá existem dois arquivos adicionais que ainda não foram mencionados: index.html. Esses arquivos são incluídos para que as pastas não sejam pesquisáveis. Se um usuário tentar apontar o browser para essas pastas, o index.html será exibido. Esses arquivos podem ser deixados em branco ou conter uma linha simples:

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

que ira exibir uma página em braco.

Uma vez que nosso módulo não faz uso de nenhum campo de formulário, a seção de configuração está vazia.

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.

Conclusão

O desenvolvimento de módulos para o Joomla! é um processo bastante simples e direto. Usando as técnicas descritas neste tutorial, uma infinita variedade de módulos podem ser desenvolvidos com pouco ou nenhum aborrecimento.

Ant: Introdução

Próx: Usando o Banco de Dados