Joomla - Desenvolver um componente - parte 2
Autor: Falando Sobre a Vida | Publicado: 2016-06-05T09:44:00-03:00



Olá pessoa! Depois de muito tempo resolvi dar continuidade a série de como desenvolver um componente Joomla 3.x.

No primeiro artigo defini como seria a estrutura básica para nosso componente, contendo os diretório e arquivos padrões de qualquer componente que se preze.

Agora vamos por as mãos nos códigos ;)

Primeiramente temos que definir um "Manifest", este é um arquivo onde ficam as informações sobre nosso componente e que o Joomla vai usar para integrá-lo ao core. O arquivo é bem simples, vou explicá-lo detalhadamente abaixo.

O arquivo se trata de um XML e por convenção deve ser nomeado como manifest.xml ou ter o mesmo nome do componente (sem ou com o prefixo "com_"), no nosso caso com_mapmarker.xml e deve ser colocado na raiz do diretório do componente, vamos montá-lo passo a passo:

Como todo arquivo XML devemos com a tag "xml", indicando a versão e a codificação que iremos usar:

&lt;?xml version="1.0" encoding="utf-8"?&gt;

Como vemos a versão do XML é 1.0: ... version="1.0" ...
E a codificação é a conhecida utf-8: ... encoding="utf-8" ...

Nunca esqueça de criar está linha corretamente, pois pode lhe trazer dores de cabeça...

Se quiser saber mais sobre XML vou deixar links no fim desse artigo ;)

A próxima tag é onde começa o código que será usado pelo Joomla!, veja:

&lt;extension type="component" version="3.0" method="upgrade"&gt;

Bom, essa tag contém algumas especificações do nosso componente.

O primeiro atributo "type" serve para especificar o tipo de extensão, ou seja, se é um component, plugin, template, etc. Veja a lista de possíveis valores:

component - Componente
file - Arquivos a serem adicionados na instalação
language - Pacote de idiomas
library - Biblioteca
module - Módulo
package - Um pacote contendo template, módulos, componentes, etc. Tudo será instalado de uma só vez.
plugin - Plugins, para adicionar/modificar funções do sistema.
template - Templates (temas)

A tag "version" define a versão do Joomla para que a extensão foi criada, mas nada impede instalar extensões com versões diferentes do Joomla a ser usado. Atualmente esse valor pode ser: 2.5 e 3.0

O atributo "method" define o tipo de instalação:

install - Aborta a instalação caso já exista um diretório do componente. Usado para componentes que devem ser instalados somente uma vez e não podem ser sobre-escritos posteriormente.

upgrade - Criar uma instalação nova ou atualização a instalação existente.

Agora vamos aos metadados, são dados usados para exibir informações sobre seu componente, como nome, autor, licença, etc. Veja:

&lt;name&gt;com_mapmarker&lt;/name&gt; 
&lt;!-- Nome do componente --&gt;

&lt;version&gt;0.0.1&lt;/version&gt;
&lt;!-- Versão do componente. Muito importante ao usar o "method" upgrade. --&gt;

&lt;description&gt;Gerenciador de localizações&lt;/description&gt;
&lt;!-- Descrição do componente --&gt;

&lt;author&gt;Everaldo Reis&lt;/author&gt;
&lt;!-- Criador do componente --&gt;

&lt;authorEmail&gt;contato@everaldoreis.com.br&lt;/authorEmail&gt;
&lt;!-- E-mail do criador --&gt;

&lt;authorUrl&gt;http://everaldoreis.com.br&lt;/authorUrl&gt;
&lt;!-- URL do site do criador --&gt;

&lt;creationDate&gt;16/12/2014&lt;/creationDate&gt;
&lt;!-- Data de criação do componente --&gt;

&lt;copyright&gt;Todos os direitos reservados&lt;/copyright&gt;
&lt;!-- Direitos autorais --&gt;

&lt;license&gt;GPLv2&lt;/license&gt;
&lt;!-- Licença de uso --&gt;

Vamos definir agora a estrutura de arquivos e diretórios que devem ser copiados para o servidor durante a instalação do componente:

&lt;files folder="site"&gt;
&nbsp; &nbsp; &lt;filename&gt;index.html&lt;/filename&gt;
&nbsp; &nbsp; &lt;filename&gt;mapmarker.php&lt;/filename&gt;
&nbsp; &nbsp; &lt;filename&gt;model.php&lt;/filename&gt;
&nbsp; &nbsp; &lt;filename&gt;view.php&lt;/filename&gt;
&nbsp; &nbsp; &lt;filename&gt;controller.php&lt;/filename&gt;
&nbsp; &nbsp; &lt;folder&gt;models&lt;/folder&gt;
&nbsp; &nbsp; &lt;folder&gt;views&lt;/folder&gt;
&nbsp; &nbsp; &lt;folder&gt;controllers&lt;/folder&gt;
&nbsp; &nbsp; &lt;folder&gt;helpers&lt;/folder&gt;
&nbsp; &nbsp; &lt;folder&gt;language&lt;/folder&gt;
&nbsp; &nbsp; &lt;folder&gt;media&lt;/folder&gt;
&nbsp; &nbsp; &lt;folder&gt;js&lt;/folder&gt;
&nbsp; &nbsp; &lt;folder&gt;css&lt;/folder&gt;
&lt;/files&gt;

Explicando... o atributo "site" na tag "files" indica que estes arquivos serão usados no sie, na parte publica visualizada pelos visitantes. Note que quando for um arquivo usamos &lt;filename&gt; e quando for diretórios colocamos &lt;folder&gt;, vou explicar a importância de cada arquivo agora.

[padrão] &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;index.html - Medida de prevenção contra "directory listing"

[padrão] &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;mapmarker.php - Arquivo de boot do componente

[personalizado] &nbsp;model.php - Esse arquivo eu costumo usar como uma classe Abstrata para reunir métodos comuns a todos os models da aplicação, como por exemplo checagem de parâmetros antes de salvar os dados, ou log de ações, etc.

[personalizado] &nbsp;view.php - Mesmo motivo do model.php

[personalizado] &nbsp;controller.php - Também usado como classe Abstrata.

[padrão] models - Diretórios onde ficam os modelos.

[padrão] views - Aqui colocamos nossas "views", ou seja, arquivos que geram o HTML.

[padrão] controllers - A camada de controle da aplicação, responsável por verificar a requisição e entrega a view correta.

[padrão] helpers - Helpers contendo métodos estáticos para ajudar em algumas tarefas.

[padrão] language - Diretório onde ficam os idiomas usados para traduzir os textos do componente de acordo com a linguagem escolhida (em sistemas multi-idiomas)

[padrão] media - Aqui guardamos nossas imagens, vídeos, pdfs, etc. Qualquer arquivo de mídia.

[padrão] &nbsp;js - Arquivos Javascript.

[padrão] css - Nossas folhas de estilo.

Esses são os arquivos que usaremos para criar a parte visível ao público e que poderá ser linkada através de menus, como veremos no decorrer do desenvolvimento.

Vamos agora a marcação para definir como será a estrutura na "administration":

&lt;administration&gt;
&nbsp; &nbsp; &lt;menu&gt;Map Marker&lt;/menu&gt;
&nbsp; &nbsp; &lt;submenu&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &lt;menu view="markers"&gt;Markers&lt;/menu&gt;
&nbsp; &nbsp; &lt;/submenu&gt;
&nbsp; &nbsp; &lt;files folder="admin"&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &lt;filename&gt;index.html&lt;/filename&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &lt;filename&gt;mapmarker.php&lt;/filename&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &lt;filename&gt;model.php&lt;/filename&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &lt;filename&gt;view.php&lt;/filename&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &lt;filename&gt;controller.php&lt;/filename&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &lt;filename&gt;config.xml&lt;/filename&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &lt;filename&gt;access.xml&lt;/filename&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &lt;folder&gt;models&lt;/folder&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &lt;folder&gt;views&lt;/folder&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &lt;folder&gt;controllers&lt;/folder&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &lt;folder&gt;tables&lt;/folder&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &lt;folder&gt;helpers&lt;/folder&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &lt;folder&gt;language&lt;/folder&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &lt;folder&gt;media&lt;/folder&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &lt;folder&gt;js&lt;/folder&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &lt;folder&gt;css&lt;/folder&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &lt;folder&gt;sql&lt;/folder&gt;
&nbsp; &nbsp; &lt;/files&gt;
&lt;/administration&gt;

A "administration" possui uma estrutura um pouco diferente do front do site, vou explicar:

&lt;menu&gt;Map Marker&lt;/menu&gt;
&lt;!-- Menu a ser exibido como submenu de "Components" --&gt;

&lt;submenu&gt; - Submenu do submenu "Map Markers" adicionado a "Components"

&lt;menu view="markers"&gt; - Item de submenu. "view" é a view correspondente ao menu.

Os arquivos a serem copiados seguem a mesma estrutura do frontend, apenas adicionando mais alguns arquivos, que são:

config.xml - Arquivos para gerar parâmetros de configuração do componente.
access.xml - Onde podemos definir regras de acesso ao componente baseado em "roles".

E alguns outros diretórios:

tables - Arquivos para operações usando tabelas do banco de dados.

sql - Onde ficam os arquivos usados para criação das tabelas durante a instalação do componente, os sql usados em cacos de upgrades e os sql para remover as tabelas durante a desinstalação do componente.

Essa foi a parte do backend, ou seja tudo que será usando para criar a interface no admin do site.

Agora resta algumas outras tags importantes:

&lt;install&gt;
&nbsp; &nbsp; &lt;sql&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &lt;file driver="mysql" charset="utf8"&gt;sql/install.mysql.utf8.sql&lt;/file&gt;
&nbsp; &nbsp; &lt;/sql&gt;
&lt;/install&gt;

A tag "install" indica onde estão os arquivos sql usados para criar as tabelas durante a instalação.
Veja que você deve especificar o driver (no caso mysql) e o charset (codificação).
Este arquivos deve ficar dentro do diretório admin/sql seguindo o padrão: install.driver.codificacao.sql

&lt;uninstall&gt;
&nbsp; &nbsp; &lt;sql&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &lt;file driver="mysql" charset="utf8"&gt;sql/uninstall.mysql.utf8.sql&lt;/file&gt;
&nbsp; &nbsp; &lt;/sql&gt;
&lt;/uninstall&gt;

Segue o mesmo conceito do "install" porém é utilizado para remover as tabelas ao desinstalar o componente.

&lt;update&gt;
&nbsp; &nbsp; &lt;schemas&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &lt;schemapath type="mysql"&gt;sql/updates/mysql/&lt;/schemapath&gt;
&nbsp; &nbsp; &lt;/schemas&gt;
&lt;/update&gt;

A tag update é usada para indicar de onde o sistema vai pegar os arquivos .sql a serem usados durante um upgrade. Os updates seguem de acordo com a "version" definida no início do arquivo xml do componente. Por exemplo, se estamos a fazer upgrade de uma versão 0.0.1 para 0.0.2 devemos colocar um arquivo chamado 0.0.2.sql dentro do diretório admin/sql/updates/mysql. Lembre-se que em nosso caso usamos mysql mas se fosse outro driver teríamos que alterar o nome do diretório para admin/sql/updates/postgre por exemplo.

Segue o &nbsp;XML completo:

&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;extension type="component" version="3.0" method="upgrade"&gt;

&nbsp; &nbsp; &lt;name&gt;Map Marker&lt;/name&gt;
&nbsp; &nbsp; &lt;author&gt;Everaldo Reis&lt;/author&gt;
&nbsp; &nbsp; &lt;creationDate&gt;16/12/2014&lt;/creationDate&gt;
&nbsp; &nbsp; &lt;authorEmail&gt;contato@everaldoreis.com.br&lt;/authorEmail&gt;
&nbsp; &nbsp; &lt;authorUrl&gt;http://www.everaldoreis.com.br&lt;/authorUrl&gt;
&nbsp; &nbsp; &lt;copyright&gt;Todos os direitos reservados&lt;/copyright&gt;
&nbsp; &nbsp; &lt;license&gt;GPLv2&lt;/license&gt;
&nbsp; &nbsp; &lt;version&gt;0.0.1&lt;/version&gt;
&nbsp; &nbsp; &lt;description&gt;Listagem de locais&lt;/description&gt;

&nbsp; &nbsp; &lt;files folder="site"&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &lt;filename&gt;index.html&lt;/filename&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &lt;filename&gt;mapmarker.php&lt;/filename&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &lt;filename&gt;model.php&lt;/filename&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &lt;filename&gt;view.php&lt;/filename&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &lt;filename&gt;controller.php&lt;/filename&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &lt;folder&gt;models&lt;/folder&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &lt;folder&gt;views&lt;/folder&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &lt;folder&gt;controllers&lt;/folder&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &lt;folder&gt;helpers&lt;/folder&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &lt;folder&gt;language&lt;/folder&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &lt;folder&gt;media&lt;/folder&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &lt;folder&gt;js&lt;/folder&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &lt;folder&gt;css&lt;/folder&gt;
&nbsp; &nbsp; &lt;/files&gt;

&nbsp; &nbsp; &lt;administration&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &lt;menu&gt;Map Marker&lt;/menu&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &lt;submenu&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &lt;menu action="markers"&gt;Markers&lt;/menu&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &lt;/submenu&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &lt;files folder="admin"&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &lt;filename&gt;index.html&lt;/filename&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &lt;filename&gt;mapmarker.php&lt;/filename&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &lt;filename&gt;model.php&lt;/filename&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &lt;filename&gt;view.php&lt;/filename&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &lt;filename&gt;controller.php&lt;/filename&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &lt;filename&gt;config.xml&lt;/filename&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &lt;filename&gt;access.xml&lt;/filename&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &lt;folder&gt;models&lt;/folder&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &lt;folder&gt;views&lt;/folder&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &lt;folder&gt;controllers&lt;/folder&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &lt;folder&gt;tables&lt;/folder&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &lt;folder&gt;helpers&lt;/folder&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &lt;folder&gt;language&lt;/folder&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &lt;folder&gt;media&lt;/folder&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &lt;folder&gt;js&lt;/folder&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &lt;folder&gt;css&lt;/folder&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &lt;folder&gt;sql&lt;/folder&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &lt;/files&gt;
&nbsp; &nbsp; &lt;/administration&gt;

&nbsp; &nbsp; &lt;update&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &lt;schemas&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &lt;schemapath type="mysql"&gt;sql/updates/mysql/&lt;/schemapath&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &lt;/schemas&gt;
&nbsp; &nbsp; &lt;/update&gt;

&nbsp; &nbsp; &lt;install&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &lt;sql&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &lt;file driver="mysql" charset="utf8"&gt;sql/install.mysql.utf8.sql&lt;/file&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &lt;/sql&gt;
&nbsp; &nbsp; &lt;/install&gt;
&nbsp; &nbsp; &lt;uninstall&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &lt;sql&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &lt;file driver="mysql" charset="utf8"&gt;sql/uninstall.mysql.utf8.sql&lt;/file&gt;
&nbsp; &nbsp; &nbsp; &nbsp; &lt;/sql&gt;
&nbsp; &nbsp; &lt;/uninstall&gt;

&lt;/extension&gt;