Viso geral Para Programadores ( Componentes)

V 1. 0

ndice
ndice .......................................................................................................................................iii ndice de Figuras ..................................................................................................................... v ndice de Tabelas.................................................................................................................... vii 1 O Joomla para programadores ........................................................................................ 9
1.1 1.2 1.3 1.4 Desenvolvendo componentes para o Joomla................................................................................. 16 Instalando um componente ............................................................................................................ 18 Definindo a lgica............................................................................................................................ 20 Definindo a apresentao ............................................................................................................... 21

iii

ndice de Figuras
Figura 9 Diagrama de do processamento de um pedido no Joomla. _________________________________ 11 Figura 10 Estrutura de ficheiros tpica de um componente ________________________________________ 18

ndice de Tabelas
Tabela 6 Principais ficheiros da raiz do site Joomla ______________________________________________ 9 Tabela 7 Variveis globais mais importantes usadas num programa Joomla __________________________ 10 Tabela 8 Nomenclatura usada nos principais ficheiros de um componente ____________________________ 17

vii

Viso Geral para Programadores

1 O Joomla para programadores

O primeiro aspecto a reter quando se comea a desenvolver no Joomla o facto de que o Joomla per si no um produto de software, apenas uma framework interpretadora de componentes, mdulos, mambots e templates (conhecidos por extenses) dos quais o Joomla completamente alheio do que fazem ou do seu aspecto. um programa escrito em PHP, usa como motor de base de dados o MySQL e o APACHE como servidor. Outro aspecto muito importante e que geralmente no mencionado que no existe o conceito de pagina Web como o conhecemos, pois tudo o que aparece no browser gerado a partir de um nico ficheiro, o tpico e conhecido index.php que se encontra na raiz do site. Devido abstraco do Joomla relativamente as suas extenses possvel desenvolver subsistemas que podem ser publicados separadamente sem o sistema original. Isto permite manipular, gerir ou remover parte do sistema sem afectar o resto do sistema. Qualquer um pode desenvolver uma extenso para o Joomla desde que cumpra os mtodos prescritos para a criao dos mesmos. Mais acerca do funcionamento das extenses pode ser encontrado nos prximos captulos. Para entender como funciona a plataforma Joomla vamos analisar como so processados os pedidos ao servidor e entender quais so os ficheiros envolvidos e as principais classes, variveis globais envolvidas no processo. Primeiro vamos conhecer melhor a hierarquia de ficheiros do Joomla.

Tabela 1 Principais ficheiros da raiz do site Joomla Nome Administrator Descrio Pasta onde se encontram todos os ficheiros que tratam da parte administrativa do site. Components Todos os ficheiros dos componentes instalados, excepto os da parte administrativa. Includes Laguages Ficheiros do ncleo do Joomla Todos os ficheiros de linguagem

hugosoares2@gmail.com

Viso Geral para Programadores

Manbots Modules Templates Index.php Index2.php Configuration.php Globals.php

Todos os ficheiros dos mambots do site. Todos os ficheiros dos mdulos de front-end instalados. Ficheiros de todos os templates de front-end. Ficheiro de inicio do front-end do site. Ficheiro de inicio do back-end do site. Ficheiro que contem vrias variveis de configurao do site. Ficheiro que trata de declarar vrias variveis globais usadas durante a execuo do programa.

Agora uma nota sobre algumas variveis que nos iro acompanhar ao longo deste relatrio bem como em qualquer programa desenvolvido na plataforma Joomla.

Tabela 2 Variveis globais mais importantes usadas num programa Joomla Nome $_VALID_MOS Descrio Permite implementar uma medida de segurana que impede o acesso directo aos ficheiros de cdigo excepto index.php $option $act $task Especifica qual o componente a carregar Especifica o tipo de informao a carregar Especifica o que fazer ao tipo de informao especificada em $act, por exemplo guardar ou apagar. $Itemid Especifica o id nico do elemento que est a fazer um pedido, por exemplo o id de um link de menu. Indica qual o contedo a apresentar. $database Um objecto de conexo base de dados. Implementa vrios mtodos que facilitam a manipulao dos dados. NO SIM SIM SIM SIM NO URL ou POST

hugosoares2@gmail.com

10

Viso Geral para Programadores

$mainframe

Objecto que possui muitas rotinas de interaco com o Joomla.

NO

Na tabela em cima o modificador de url ou post significa que esta varivel iniciada algures no cdigo a partir das variveis get ou post com o mesmo nome, recebidas no servidor aps os pedidos pelo utilizador. Estas variveis so usadas para que o servidor execute as tarefas que foram pedidas pelo utilizador.

Figura 1 Diagrama de do processamento de um pedido no Joomla.

1- Carregar ndex.php e definir $_VALID_MOS 2- Existe o ficheiro configuration.php? 3- Carregar configuration.php 4- Carregar joomla.php 5- Carregar database.php 6- Carregar frontend.php
hugosoares2@gmail.com 11

Viso Geral para Programadores

7- Existem as variveis option ou itemid? 8- Criar objecto de base de dados (varivel $database) 9- Tentar obter uma option se no foi especificado em 7 10- Criar objecto mosMainframe 11- Criar o array $_MOS_OPTION 12- Carregar o componente 13- Carregar o template 14- Carregar frontend.html.php 15- mosShowHead 16- mosLoadModules 17- mosMainBody 18- Mostrar a pgina

No diagrama em cima cada passo da cor do ficheiro que est na realidade a executar o cdigo, os ficheiros de cor branca indicam que executam apenas cdigo de apoio a algumas tarefas. Para explicar cada passo iremos usar a letra D para representar o diagrama seguido do ponto decimal e o nmero do passo (exemplo [D.3]). Alguns passos foram omitidos por uma razo de simplicidade, pois correspondem apenas garantia de compatibilidade com antigas verses do PHP e do Joomla. Sempre que um utilizador visita o site, escrevendo o endereo ou carregando num link, o Joomla recebe um pedido e executa uma srie de tarefas para determinar o tipo de utilizador que fez o pedido, a seco pretendida e o contedo em particular a ser exibido.

Como seria de esperar o primeiro ficheiro a ser executado o index.php [D.1] encontrado no directrio de raiz do site. Se examinarmos este ficheiro podemos ver que no tem nenhum cdigo html prprio. Isto porque este ficheiro apenas executa uma quantidade de tarefas e delega funes mas no gera nenhum contedo. Note que no diagrama a sua execuo s termina quando o contedo apresentado ao utilizador. O contedo exibido recolhido e

hugosoares2@gmail.com

12

Viso Geral para Programadores

formatado por outros ficheiros os componentes e mdulos que so includos pelo index.php. A primeira tarefa do index.php definir a varivel global $_VALID_MOS com o cdigo define (_VALID_MOS, 1), assim a primeira linha em todos os outros do Joomla : defined ( '_VALID_MOS' ) or die( 'Direct Access to this location is not allowed.' ); Isto uma medida de segurana que impossibilita o acesso directo aos ficheiros do Joomla excepto ao index.php. Assim, se tentar-mos aceder, por exemplo, ao ficheiro mod_mainmenu.php directamente pelo seu url, $_VALID_MOS, que definida em index.php, no ter sido definida logo o utilizador s ver uma mensagem que dir Direct Access to this location is not allowed.'. De seguida index.php verifica a existncia de configuration.php [D.2]. Este ficheiro contm a configurao bsica do Joomla que usada pelo ncleo do site, os seus componentes, mdulos e templates. Se o ficheiro configuration.php no existir o Joomla carrega um script de instalao que permite instalar o Joomla com as definies por defeito bem como alguma informao inserida pelo utilizador como o nome da base de dados e o nome de usurio e palavra-chave do MySQL. Este ficheiro uma lista de variveis usadas para guardar informao de caminhos para directrios internos, nome de usurio e palavra-chave do MySQL, fuso horrio e outras informaes de administrao. Se o ficheiro configuration.php existir ento carregado [D.3] e a execuo do Joomla corre o seu rumo normal.

O prximo passo carregar o joomla.php [D.4]. Este um dos ficheiros com maior carga de trabalhos da API do Joomla e contm muitas classes e funes que tornam o trabalho do programador muito mais fcil. Algumas destas classes e funes sero descritas mais a frente mas para j interessa saber que este ficheiro muito importante e aconselhvel perder algum tempo a conhece-lo melhor.

Outro ficheiro muito importante para o programador database.php. Este ficheiro carregado pelo Joomla [D.5] e contm todas as classes e funes necessrias para interagir com a base de dados tornando estas capacidades acessveis a todos os ficheiros subsequentes. Entraremos em pormenor mais a frente mas para j importante saber que este ficheiro oferece um vasto leque de funes de query com diferentes tipos de retorno e funes de debugging.

hugosoares2@gmail.com

13

Viso Geral para Programadores

O prximo ficheiro de ncleo a ser carregado o frontend.php [D.6], que trabalha em srie com Joomla.php para levar a cabo a maior parte das tarefas do Joomla como iniciar e carregar mdulos ou carregar o contedo principal de uma pgina. Os templates interagem directamente com este ficheiro pois ele est directamente ligado apresentao do contedo. Depois de todos os ficheiros do ncleo do Joomla serem carregados o index.php tenta identificar o estado de option e ItemId [D.7] que so passadas pela url query string ou pelo post dependendo do tipo de pedido, para identificar qual o contedo pretendido pelo utilizador. Se este passo falhar o Joomla simplesmente passa para o prximo passo. De seguida criado um novo objecto de base de dados [D.8], criando uma instancia da classe database que naturalmente se encontra em database.php. Como o HTTP no mantm uma ligao permanente ao servidor sempre que feito um novo pedido necessrio criar um novo objecto de conexo base de dados.

Em [D.9] o Joomla volta tratar da questo do option e Itemid. Se em [D.7] option no foi definido mas foi definido um Itemid ento o Joomla tenta descobrir qual o componente a carregar procurando na base de dados pelo item de menu especificado em itemid que, por sua vez, contm toda a informao do contedo desse link. Se o anterior falhar ento o Joomla baseia-se na option e Itemid do primeiro elemento do menu principal que se assume ser a pgina inicial do site. Note que tudo isto s acontece se no for especificado um componente atravs do option caso contrario o componente ser carregado e tratado no prximo passo.

O prximo passo criar um objecto mosMainframe [D.10] na varivel global $mainframe. Este objecto proporciona uma grande carga de trabalhos por ter muitas rotinas de interaco com o sistema. Muitas das rotinas deste objecto sero usadas pelo componentes que vir a ser carregado, por exemplo para ler do ficheiro configuration.php carregado em [D.3], determinar o template usado, colocar alguma informao na parte header e metadata do cdigo HTML da pgina. O mosMainframe tambm iniciar uma sesso ou actualizar no caso de esta no ter expirado. As sesses permitem que um utilizador previamente autenticado navegue de pgina para pgina sem ter de inserir novamente as suas credenciais.

hugosoares2@gmail.com

14

Viso Geral para Programadores

Neste momento, o Joomla ir preparar-se para executar o cdigo do componente que foi determinado nos passos 7 ou 9. Apesar de tudo o contedo resultante desta execuo ainda no ser apresentado, em vez disso guardado num buffer temporrio para que mais tarde possa ser misturado com o HTML do template. No ficheiro index.php criado um array chamando $_MOS_OPTION [D.11] e de seguida usada a capacidade de buffering do PHP para capturar o contedo de sada do componente. Isto feito da seguinte forma: - Chamar o comando PHP ob_start() - Executar o cdigo do componente - Retirar o contedo do buffer usando ob_get_contents() - Colocar o contedo em $_MOS_OPTION para mais tarde ser usado - Limpar o buffer com ob_end_clean() Finalmente chega o momento de carregar o template [D.13]. Este dever ter chamadas a procedimentos do frontend.php mosShowHead, mosLoadModules e mosMainBody. Para carregar os mdulos para uma dada posio o ficheiro frontend.php primeiro carrega frontend.html.php [D.14] e s depois inicia os mdulos escrevendo o HTML. O frontend.html.php primeiro verifica se um mdulo em particular um mdulo instalado ou um mdulo stored, sendo que a diferena que os mdulos instalados so ficheiros separados no directrio dos mdulos e os mdulos stored so criados na rea de administrao dos mdulos e guardados na base de dados. Depois de carregado o frontend.html.php, a funo mosShowHead() [D.15] chama a funo do objecto mosMainframe, getHead() que retorna a informao do header previamente tratada no passo 10.

O mosLoadModules() poder ser chamado quantas vezes for necessrio dependendo das regies definidas no template. O Joomla permite no mximo 26 posies com nomes como Top, Left, Right, Bottom, user1, user2 Estas posies organizam os mdulos em grupos. Quando no mosLoadModules() passado um parmetro(primeiro) indicando a posio, o Joomla carrega todos os mdulos do grupo dessa posio. Aps executar o cdigo do modulo o frontend.php envolve-o em cdigo HTML adicional se for especificado um parmetro (segundo) adicional de estilo em mosLoadModules(). Por exemplo mosLoadModules('left', -1) indica que 'left' a grupo de posio e -1 o estilo do
hugosoares2@gmail.com 15

Viso Geral para Programadores

mdulo. Neste caso -1 indica que no necessrio adicionar mais nenhum HTML e que o ttulo no deve ser mostrado. O parmetro de estilo 0 o estilo por defeito e indica que o mdulo deve ser envolvido numa tabela da classe moduletable.

A parte final do cdigo a ser executada o mosMainBody() [D.17] que uma funo muito simples pois a sua nica tarefa ir buscar o contedo de sada do componente ao array $_MOS_OPTION que foi por sua vez guardado em $GLOBALS no passo 12. Neste momento todo o HTML de sada dos componentes, mdulos e Joomla junto para mostrar a pgina gerada ao utilizador [D.18].

1.1 Desenvolvendo componentes para o Joomla

Como j vimos em captulos anteriores os componentes so compostos por uma parte de administrao e uma parte visvel ao utilizador. Em termos de hierarquia de ficheiros estas duas partes encontram-se separadas, a parte de administrao encontra-se em

administrator/components/com_* e parte de front-end em components/com_* (todos os componentes comeam com com_ seguidos no seu nome). Podemos fazer absolutamente tudo o que quisermos com eles desde que se usem os mtodos e regras necessrias a sua integrao no Joomla. Essas regras incluem usar determinadas nomenclaturas nos ficheiros do componente, criar um ficheiro xml com a lista dos ficheiros do componente e informao de instalao, usar mtodos da framework para tarefas internas, criar ficheiros de instalao e remoo. Embora o Joomla oferea vrios mtodos e classes de apoio ao desenvolvimento de extenses, estas no so indispensveis para o funcionamento dos mesmos. Se, por exemplo, tivermos um programa em PHP que queremos integrar no Joomla como componente podemos facilmente, dependendo da complexidade do programa, fazer a transio apenas com pequenas alteraes de cdigo para garantir a segurana e alguma integrao com outros componentes. Geralmente o desenvolvimento de componentes segue uma arquitectura bem definida e simples que embora no sendo obrigatria bastante aconselhada pois simplifica muito a compreenso de todos os aspectos do programa. Basicamente aconselhada a separao de
hugosoares2@gmail.com 16

Viso Geral para Programadores

tarefas de lgica e de apresentao em ficheiros separados. As tarefas de lgica podem ser gravar, listar, ler da base de dados, que fazem chamadas a mtodos da parte de apresentao que se encarregam de imprimir todo o HTML para formulrios, listagens de contedo, etc. O ficheiro de apresentao constitudo sempre por pelo menos uma classe com vrios mtodos e sem construtor que ser usada como camada de apresentao do componente. Um terceiro ficheiro que muito frequente usar o de classes da base de dados. Este contm classes que so representaes das tabelas da base de dados usadas pelo componente. Estas classes podem ser uma extenso da classe do Joomla chamada mosDBTable e fazer uso de algumas funes que ai esto implementadas para simplificar a comunicao com a base de dados.

Tabela 3 Nomenclatura usada nos principais ficheiros de um componente Nomenclatura Ficheiro Lgica Apresentao Classes (*) - Nome do componente. Administrao admin.(*).php admin.(*).html.php admin.(*).class.php front-end (*).php (*).html.php (*).class.php

muito importante usarmos a nomenclatura descrita em cima porque quando o Joomla carrega um componente, baseia-se no nome deste para descobrir qual o ficheiro inicial do programa, que como j deve ter suspeitado o ficheiro de lgica. Outra vantagem de usar esta nomenclatura o facto de existirem algumas funes internas que facilitam, por exemplo, a incluso dos vrios ficheiros bastando para isso indicar se quer o de classes, de apresentao ou de lgica.

hugosoares2@gmail.com

17

Viso Geral para Programadores

1.2 Instalando um componente

Os componentes so publicados no formato de compresso zip e seguem uma hierarquia de ficheiros prpria que necessria para que o Joomla os reconhea como vlidos. prtica corrente usar directrios separados para os diferentes tipos de ficheiros, assim tipicamente existir um directrio de imagens, um directrio de javascripts, um directrio de folhas de estilo css e na raiz todos os ficheiros de cdigo fonte PHP.

Figura 2 Estrutura de ficheiros tpica de um componente

Para instalar o componente o Joomla comea por procurar nos elementos do componente um ficheiro xml com o mesmo nome do componente (na figura em cima podemos ver o ficheiro gilt.xml). Este ficheiro contm a descrio de todos os ficheiros do componente, que usa para copiar e criar os directrios na rea de font-end e de back-end, os comandos sql necessrios para interagir com a base dados (criando assim a estrutura de dados usada pelo componente) e outra informao acerca do componente.

hugosoares2@gmail.com

18

Viso Geral para Programadores

O esquema seguinte exemplifica uma possvel estrutura do ficheiro xml de instalao.

<?xml version="1.0"?> <mosinstall type="component" version="4.5.1"> <name>Gilt</name> <creationDate>May 2006</creationDate> <author>Hugo Jorge Soares</author> <copyright>All rights reserved</copyright> <authorEmail>hugosoares2@gmail.com</authorEmail> <authorUrl>gilt.isep.ipp.pt</authorUrl> <version>1.0</version> <description>Gilt component</description> <files><filename>gilt.php</filename></files> <images><filename>images/logo.gif</filename></images> <install> <queries> <query>CREATE TABLE inscricoes (total INT(11) NULL ,name VARCHAR( 80 ) NOT NULL ,email VARCHAR( 80 ) NOT NULL ,morada VARCHAR( 150 ) ,telefone INT( 9 ) ,events TEXT NOT NULL,id TINYINT auto_increment NOT NULL ,PRIMARY KEY ( id )) ENGINE = INNODB;</query> </queries> </install> <uninstall><queries> <query>DROP TABLE Pessoa_Events;</query></queries> </uninstall> <installfile>install.gilt.php</installfile> <uninstallfile>uninstall.gilt.php</uninstallfile> <administration> <menu>GILT</menu> <submenu><menu act="peo">People</menu></submenu> <files><filename>admin.gilt.php</filename></files> </administration> </mosinstall>

Como podemos ver comea-mos por descrever alguma informao sobre o componente como o autor a data, etc. De seguida temos uma lista de ficheiros que devem ser copiados para a rea de front-end (files e images). Nas seces install e uninstall temos a possibilidade de escrever os comandos sql necessrios para a instalao ou remoo do componente, que sero

hugosoares2@gmail.com

19

Viso Geral para Programadores

executados nessa altura. Os ndulos xml installfile e uninstallfile indicam respectivamente qual o ficheiro a carregar aquando da instalao ou remoo do componente. A ltima parte respeitante rea de administrao e permite construir o menu de administrao do componente indicando quais os links e os valores a serem passados nas variveis de url. Tal como para p front-end tambm obrigatria a descrio dos ficheiros que compem esta rea. Como j foi dito o Joomla carrega um ficheiro aquando da instalao ou remoo do componente. No caso de instalao o Joomla tenta correr a funo com_install() e na remoo com_uninstall(). Estas funes tm de existir forosamente e nelas podemos inserir comandos adicionais para completar a instalao ou remoo. Isto particularmente til para fazer algum tipo de integrao com componentes ou mdulos existentes como por exemplo a criao de links de menu.

1.3 Definindo a lgica

Para definir as tarefas a executar o ficheiro de lgica usa as variveis que j conhecemos, $act e $task, em duas clusulas switch encadeadas como exemplifica o cdigo seguinte:
switch($act){ case eventos: switch ($task){ case save: save($option,$act); break; case list: list($option); break; } break; case pessoas: . }

hugosoares2@gmail.com

20

Viso Geral para Programadores

Desta forma podemos direccionar a execuo do cdigo no sentido pretendido pelo pedido do utilizador, fazendo as chamadas das respectivas funes que tratam da tarefa requerida.

Todas as funes que tenham como resultado final a apresentao de contedo devem fazer chamadas a mtodos do ficheiro de apresentao. No entanto previamente chamada destes mtodos toda a lgica deve ser tratada, incluindo leituras base de dados o que implica enviar apenas os dados a serem mostrados. Isto feito usando a classe de acesso a dados database que se encontra no ficheiro database.php e tem como varivel global $database. Nesta camada temos a possibilidade de obter dados da base dados sob a forma de arrays de objectos representativos das tabelas, que usaremos para enviar os dados para a camada de apresentao do componente.

As funes que tenham como resultado apenas a interaco com a base de dados (gravar, actualizar, apagar) apenas fazem chamadas camada de acesso a dados do Joomla e geralmente no interagem com mais nenhum ficheiro. Estas Funes podem fazer uso das classes do ficheiro de classes para facilitar a interaco com a base de dados. Geralmente so chamadas em resposta a um envio de um formulrio usando o mtodo post.

1.4 Definindo a apresentao

O ficheiro de apresentao constitudo por pelo menos uma classe geralmente com o nome lgico de HTML pois s disto que ela trata. Esta classe no possui construtor porque no existe necessidade de ser instanciada pois apenas os seus mtodos so de interesse. Estes mtodos efectuam tarefas bem especficas pelo que geralmente englobam todo o processamento no seu corpo. Recebem como parmetro, sob a forma de arrays, os dados que devem mostrar e escrevem o HTML para formatar e apresentar esse contedo. Na realidade o componente s tratar de escrever algum do HTML do bloco body da pgina o resto faz parte dos mdulos e claro do template. Existem alguns cuidados a ter quando estamos a desenvolver em HTML especialmente no que respeita aos formulrios pois o Joomla coloca algumas regras, nomeadamente: Os atributos name, id e class da tag form tm que ser adminForm

hugosoares2@gmail.com

21

Viso Geral para Programadores

O atributo action da tag form dever ser index.php para o front-end e index2.php para o back-end.

Como o formulrio ir ser tratado na parte de lgica ento teremos de colocar em elementos escondidos o valor das variveis $option, $act e $task. Desta forma quando o formulrio for submetido ao servidor o Joomla carregar o nosso componente atravs de $option, $act indicar qual a aco e $task a tarefa. Por exemplo: <input type="hidden" name="option" value="com_gilt" /> <input type="hidden" name="act" value="eventos" /> <input type="hidden" name="task" value="gravar" />

Neste caso quando o formulrio fosse submetido o Joomla iria carregar o componente gilt e chamar o mtodo que trata de gravar os eventos. Usar o mtodo addCustomHeadTag( $html ) do objecto mosMainframe para inserir algum cdigo necessrio no bloco head da pgina (lembrar que todo o html s inscrito numa fase posterior, dai a necessidade de um mtodo deste gnero). Ter bastante cuidado com o uso de javascript para que no existam conflitos com o scripts que o Joomla usa para o seu funcionamento. Usar os mtodos do Joomla para criar as barras de ferramentas que se usam para as tarefas de autoria, pois estas incluem automaticamente alguns scripts necessrios para interagir com outros elementos do formulrio.

Quanto ao aspecto do contedo deveremos sempre que possvel usar os atributos class dos elementos HTML para definirmos o seu estilo. Existem standards para os nomes de classes css que os templates devem usar, logo se usarmos esses nomes para os atributos class, temos a garantia de que o aspecto de toda a pgina ser homogneo. Para conhecermos estes nomes temos de investigar o css do template que est ser usado.

hugosoares2@gmail.com

22

Viso Geral para Programadores

Este trabalho est licenciado sob uma Licena Creative Commons Atribuio-Uso NoComercial-Compartilhamento pela mesma Licena 2.5. Para ver uma cpia desta licena, visite http://creativecommons.org/licenses/by-nc-sa/2.5/ ou envie uma carta para Creative Commons, 559 Nathan Abbott Way, Stanford, California 94305, USA

hugosoares2@gmail.com

23