1. Orientaes para criao demdulo integrado ao Xoops 2.2.4 O Xoops o acrnimo de eXtensible Object Oriented Portal System. uma ferramenta para gerenciamento de portais. Todo o cdigo do Xoops pode ser obtido em http://www.xoops.org . Antes de criar o seu prprio mdulo, recomendamos que voc instale o xoops numa mquina, instale alguns mdulos disponveis e estude o cdigo destes mdulos para somente ento comear a desenvolver o seu mdulo. Neste exemplo, estamos supondo que o nome do mdulo a ser criado meu_modulo. Realizamos esta suposio com fins didticos a fim de tornar mais claro os nossos exemplos. O Xoops conta com diversas listas de discusso e fruns que podem ajudar o desenvolvedor na sua tarefa. Particularmente no Brasil, temos vrios grupos que mantm este tipo de ferramenta de suporte.1 Ambiente utilizado1.1 Linguagem de programao: PHP 4.3.101.2 Servidor Web: Apache 2.0.541.3 Banco de Dados: MySQL 4.0.241.3 Localizao dos arquivos: XOOPS_ROOT_PATH/modules/meu_modulo/1.4 URL: XOOPS_URL/modules/meu_modulo/2 Estrutura de diretrios Toda a estrutura de arquivos e diretrios dever ser criada dentro de XOOPS_ROOT_PATH/modules/meu_modulo/2.1 xoops_version.php Arquivo contento informaes bsicas sobre o mdulo.2.2 index.php Arquivo inicial do mdulo. Este arquivo ser carregado sempre que o usurio

2. solicitar entrar no mdulo sem especificar um destino especfico.2.3 admin/ Diretrio opcional contendo todos os arquivos necessrios para criar uma rea administrativa para o mdulo.2.3.1 admin/menu.php Arquivo contendo uma lista de todos as pginas administrativas que devero compor o menu de administrao do Xoops.2.3.2 admin/index.php Arquivo principal da administrao do mdulo.2.4 blocks/ Diretrio opcional contendo blocos do mdulo. Um bloco no Xoops uma rea de destaque para algum contedo do mdulo que pode ser exibido em diversas situaes diferentes do site.2.5 class/ Diretrio a ser utilizado para todas as classes a serem utilizadas no mdulo. Caso o mdulo no utilize classes, este diretrio poder ser omitido. O nome de cada arquivo contendo as classes dever ter o prefixo class. e terminar com a extenso .php.2.6 language/ Diretrio onde sero criados os textos a serem exibidos. Devero ser criados pelo menos dois diretrios, um chamado brazil/ para os arquivos em Portugus do Brasil e um chamado english/ para os arquivos em ingls.2.6.1 language/brazil/modinfo.php Arquivo contendo textos bsicos do mdulo meu_modulo na lngua Portugus do Brasil2.6.2 language/english/modinfo.php Arquivo contendo textos bsicos do mdulo meu_modulo na lngua inglesa2.7 include/ Diretrio onde sero criadas funes a serem includas em outros arquivos2.8 images/ Diretrio onde sero armazenadas todas as imagens a serem utilizadas pelo mdulo meu_modulo2.9 images/meu_modulo_logo.png Logotipo do mdulo meu_modulo a ser utilizado na administrao do portal. 3. Dever estar no formato png e possuir as dimenses de 92 pixels de largura por 52 pixels de altura2.10 meu_modulo/sql/mysql.sql Arquivo contendo um script SQL com o DDL para a criao de todas as tabelas, vises e seqncias do sistema. Todos os objetos criados no banco de dados devero possuir um prefixo meu_modulo_ no seu nome.2.11 templates/ Diretrio contendo os temas para exibio do contedo do mdulo. Todos os nomes de arquivos desta pasta devero possuir o prefixo meu_modulo_ e a extenso .html .2.11.1 templates/blocks Diretrio contento os temas para exibio dos blocos do mdulo. Todos os nomes de arquivos desta pasta devero possuir o prefixo meu_modulo_block_ e a extenso .html .2.12 index.html Por motivos de segurana, todos os diretrios criados devero ter um arquivo com o nome index.html com um contedo fixo de apenas uma linha: 3 Informaes sobre o mdulo O mdulo meu_modulo dever ser integrado no portal atravs de instalao do mesmo. Para isso dever fornecer informaes bsicas no arquivo xoops_version.php.3.1 Nome do mdulo $modversion['name'] = XXX;Esta linha deve constar para descrever o nome do mdulo durante a instalao. Substitua XXX pelo nome do mdulo. Sugerimos utilizar o nome meu_modulo ou algo parecido e curto.3.2 Verso $modversion['version'] = XXX;Verso do mdulo meu_modulo. Substituir XXX pelo nmero da verso como por exemplo 1.03.3 Descrio $modversion['description'] = _MI_meu_modulo_DESC;Descrio do mdulo meu_modulo (o que ele faz). A varivel MI_meu_modulo_DESC dever ser definida nos arquivos modinfo.php 4. 3.4 Crditos $modversion['credits'] = quot;XXXquot;;Crditos do mdulo desenvolvido. Aqui de praxe substituir XXX pelo nome dos desenvolvedores.3.5 Autor $modversion['author'] = quot;XXX;Pessoa que detm os crditos pelo mdulo. Aqui de praxe substituir XXX pelo nome da empresa ou equipe que possui direitos autorais sobre o mdulo.3.6 Help $modversion['help'] = quot;meu_modulo_help.htmlquot;;Esta linha opcional, mas pode apontar para um arquivo que contenha um html que ser um tutorial sobre o sistema para ser utilizado pelos usurios do portal com algum direito administrativo. O arquivo meu_modulo_help.html dever constar em help/ e poder utilizar outros arquivos dentro do mesmo diretrio.Caso no seja criada uma estrutura de help, o parmetro dever ser colocado como: $modversion['help'] = quot;quot;;3.7 Licena $modversion['license'] = quot;XXXquot;;Tipo de licena utilizada pelo mdulo. Substitua XXX pelo nome da licena utilizada.3.8 Flag official $modversion['official'] = 0;Esta linha utilizada pelo portal para identificar que o mdulo no faz parte do sistema originalmente mantido pela equipe de desenvolvimento do portal.3.9 Logotipo do mdulo: $modversion['image'] = quot;images/meu_modulo_slogo.pngquot;;Esta linha identifica o logotipo do mdulo meu_modulo que ser exibido na interface administrativa do portal. 3.10 Diretrio do mdulo $modversion['dirname'] = quot;meu_moduloquot;;Esta linha descreve o nome do diretrio do mdulo. 5. 3.11Arquivo SQL $modversion['sqlfile']['mysql'] = quot;sql/mysql.sqlquot;;Esta linha descreve o arquivo que ser utilizado para criar as tabelas do mdulo meu_modulo.3.12 Tabelas do mdulo $modversion['tables'][0] = quot;xxxquot;; $modversion['tables'][1] = quot;yyyquot;; $modversion['tables'][2] = quot;zzzquot;;Estas linhas descrevem todo o conjunto de tabelas utilizadas pelo mdulo. Deve-se utilizar uma linha para cada tabela e substituir XXX, YYY, ZZZ pelo nome das tabelas. No existe um limite para o nmero de tabelas utilizadas, apenas deve-se tomar o cuidado de incrementar seqencialmente o contador entre colchetes a partir do zero.3.13 rea administrativa $modversion['hasAdmin'] = 0;Esta linha descreve se o mdulo possui uma rea administrativa. Em caso negativo, deve-se deixar o valor da varivel em zero, caso contrrio, deve-se deixar a varivel em 1 (um) e acrescentar as seguintes linhas:$modversion['adminindex'] = quot;admin/index.phpquot;; $modversion['adminmenu'] = quot;admin/menu.phpquot;;No caso de ser criada uma rea administrativa, os arquivos index.php e menu.php devero ser criados no diretrio admin/.3.14 Templates $modversion['templates'][1]['file'] = 'XXX.html'; $modversion['templates'][1]['description'] = ''; $modversion['templates'][2]['file'] = 'YYY.html'; $modversion['templates'][2]['description'] = ''; $modversion['templates'][3]['file'] = 'ZZZ.html'; $modversion['templates'][3]['description'] = '';Estas linhas descrevem o template utilizado para exibir as pginas aos usurios dos contedos do mdulo. Substitua XXX, YYY e ZZZ pelos nomes dos arquivos contidos em templates/ . de praxe utilizar um template para cada arquivo principal que exibir um tipo de contedo distinto. possvel utilizar qualquer nmero de templates, a partir de um, incrementando-se sempre o contador em um para cada template . A descrio opcional, mas se existir, deve-se utilizar uma varivel definida em modinfo.php em language/3.15 Blocos Blocos so estruturas opcionais em um mdulo, eles so utilizados para dar destaque em algum contedo especfico. Cada bloco deve ter: um arquivo em blocks/ referenciado na opo file; um nome armazenado no arquivo modinfo.php do diretrio language/ 6. referenciado na opo name; uma descrio sobre o que o bloco faz referenciada na opo description; o nome de uma funo dentro do arquivo anteriormente referenciado paraexibir o contedo do bloco referenciado na opo show_func; o nome de uma funo opcional dentro do arquivo anteriormentereferenciado de uma funo de edio de parmetros opcionais da funoreferenciado na opo edit_func; opes utilizadas na funo opcional de edio. Na opo referenciada poroptions colocar o valor default de cada opo separada por um |; um arquivo em templates/blocks/ referenciado na opo template.$modversion['blocks'][1]['file'] = quot;xxx.phpquot;; $modversion['blocks'][1]['name'] = _MI_meu_modulo_XXX; $modversion['blocks'][1]['description'] = yyy; $modversion['blocks'][1]['show_func'] = quot;b_meu_modulo_xxx_showquot;; $modversion['blocks'][1]['edit_func'] = b_meu_modulo_xxx_edit; $modversion['blocks'][1]['options'] = aaa|bbb|ccc; $modversion['blocks'][1]['template'] = 'meu_modulo_block_xxx.html';Os blocos podem ser exibidos em qualquer local do portal, a partir da administrao dos blocos fornecida pelo Xoops. Podem ser criados nenhum bloco ou vrios deles, para atender diversos propsitos. Para cada bloco deve- se incrementar o contador entre colchetes em um.3.16 Busca $modversion['hasSearch'] = 1;Estas linhas descrevem a integrao com o mecanismo de busca. A opo has_Search deve estar em um para que a integrao esteja ativada ou em zero para inabilita-la. Para habilitar a busca, deve-se incluir as linhas seguintes e criar um arquivo meu_modulo.inc.php em include/ contendo uma funo meu_modulo_search contendo o cdigo necessrio.$modversion['search']['file'] = quot;include/search.inc.phpquot;; $modversion['search']['func'] = quot;meu_modulo_searchquot;;3.17 Menu principal $modversion['hasMain'] = 1;Esta linha deve estar com o valor em zero se no for adicionado nenhum link no menu principal e em um caso contrrio. Esta opo tambm afeta os locais diferentes onde os blocos podem aparecer, sendo possvel selecionar um local diferente para cada item do menu. Caso se deseje ativar os itens do menu principal, deve-se adicionar as linhas abaixo para cada item do menu:$modversion['sub'][1]['name'] = _MI_meu_modulo_YYY; $modversion['sub'][1]['url'] = quot;xxx.phpquot;; $modversion['sub'][2]['name'] = _MI_meu_modulo_YYY; $modversion['sub'][2]['url'] = quot;yyy.phpquot;;Onde a opo name deve constar do nome da do item de menu definido em modinfo.php em language/ e a URL deve ser um arquivo que conste no diretrio raiz 7. do mdulo. Podem ser adicionados quantos itens de menu se quiserem, incrementando sempre o contador entre colchetes em um para cada item3.18 Configurao do mdulo Podem ser adicionadas opes a serem setadas por algum usurio com privilgios administrativos no site. Para isso, cada opo deve ser possuir: Um nome definido na opo name; Um ttulo definido na opo title referenciado no arquivo modinfo.php dodiretrio /languages Uma descrio definida na opo description referenciada no arquivomodinfo.php do diretrio /languages Um tipo de item de formulrio HTML definida na opo formtype que podeser: uma caixa de seleo para utilizando o valor select; uma opo do tipo sim ou no utilizando o valor yesno; uma caixa de texto utilizando o valor textbox; uma caixa de seleo de data utilizando o valor date; Um tipo de valor de retorno definida na opo valuetype que pode ser: texto utilizando o valor text; inteiro utilizando o valor int; Um valor default definido na opo default; Valores listados numa caixa de seleo no formato de array definidos naopo options.$modversion['config'][1]['name'] = 'xxx'; $modversion['config'][1]['title'] = '_MI_CONFIG_XXX'; $modversion['config'][1]['description'] = '_MI_CONFIG_XXX_DESC'; $modversion['config'][1]['formtype'] = 'select'; $modversion['config'][1]['valuetype'] = 'text'; $modversion['config'][1]['default'] = 5; $modversion['config'][1]['options'] = array('Opo A' => 'A', 'Opo B' => 'B', 'Opo 10' => 10, 'Opo 20' => 20);Podem ser criadas quantas opes de configurao se desejar, incrementando sempre o contador entre colchetes em um para cada item As variveis definidas nas configuraes do mdulo estaro disponveis no formato atravs da varivel $xoopsModuleConfig['xxx'] que poder ser acessada a qualquer momento no cdigo do mdulo, uma vez que voc inclua os arquivos indicados, conforme descrito mais adiante.4 Internacionalizao O Xoops dispe de um mecanismo simples de internacionalizao que permite que os textos exibidos pelo portal possam trocar de lngua automaticamente. Para isso, so criados arquivos para contextos diferentes para cada lngua utilizada em /languages. A lngua padro o ingls, portanto ela deve sempre existir. Se a lngua inglesa for omitida o portal apresentar um erro. A estrutura do arquivo de internacionalizao o seguinte: define('_MI_meu_modulo_NAME','Biblioteca meu_modulo'); define('_MI_meu_modulo_DESC,'Mdulo de exibio do contedo do sistema meu_modulo'); So Definidas apenas uma linha para cada varivel. 8. 5 Templates Os templates so utilizados no Xoops para separar a camada de dados da camada de visualizao no sistema. Visando agilizar esta operao, ele utiliza um formato gil de exibio do contedo atravs da tecnologia conhecida como Smarty. Documentao especfica desta tecnologia pode ser encontrada em http://smarty.php.net/ Para se utilizar os templates com smarty no Xoops basta que a camada de dados exporte o contedo atravs da funo: $xoopsTpl->assign('var_name', $value); Onde $value o valor (que pode ser um array ou no) que ser passado para o template e var_name o nome da varivel que ser utilizada no template da seguinte forma: 6 rea administrativa Uma rea administrativa utilizada para inserir novos contedos no mdulo, alterar opes de exibio ou instanciar blocos. A rea administrativa possui dois arquivos principais guardados em /admin: index.php Este arquivo consiste na pgina de menu propriamente dita. Ela deve possuir o seguinte formato: Note que voc deve criar uma funo para cada tem de menu administrativo. Substitua xxx, yyy e default pelas funes que voc criar. menu.php Este arquivo deve conter um lista com todos os itens de menu administrativo do seu mdulo: Note que voc deve definir em modinfo.php do diretrio /languages os nomes de cada menu e que o endereo de cada menu ser o mesmo resgatado em admin/index.php7 Blocos Blocos posuem uma estrutura simples e utilizam precisam apenas retornar um array contendo os dados a serem exibidos e um template especial onde os dados so obtidos atravs da varivel sendo var_name um tem do array. Os dois arquivos utilizados pelo bloco so: xxx.php em blocks/ Note que as opes definidas no bloco so passadas para a funo como um array ($options[0], $options[1], $options[2], etc). Caso no seja definida nenhuma opo para o bloco, definimos a funo somente como function b_news_topics_show(). Para blocos que utilizam opes, tabm devemos criar uma funo responsvel por exibir a opo no formulrio que instancia o bloco armazenando todo o cdigo html na varivel $form como no exemplo abaixo:function b_news_topicsnav_edit($options) { $form = _MB_NEWS_SHOW_NEWS_COUNT.quot; quot;._YES; $form .= quot;quot;._NO; return $form;meu_modulo_block_xxx.html em templates/blocks/

8 Busca A busca integrada ao site dever pesquisar no mdulo a correspondncia com uma ou mais palavras chaves, retornando um nome e link para cada item que casarem com o critrio. Um nico arquivo dever ser criado em include/search.inc.php com o seguinte formato: 9 Contedo principalO contedo a ser exibido deve possuir um arquivo que selecione o contedo, como index.php na raiz do mdulo e um template. Para que sejam carregadas as variveis de ambiente e todo o cabealho, rodap, barra lateral esquerda e direita, blocos etc, preciso seguir o seguinte padro: Onde cada valor a ser exportado (no formato array ou no) dever utilizar a classe $xoopsTpl como explicado no item 5 deste documento.10 Funes e classes O Xoops possui uma srie de funes e classes embutidas que devem ser utilizadas dentro de cada mdulo. Estas classes, alm de garantir a integrao entre o mdulo e o core do Xoops, tambm garantem uma srie de checagens de segurana, alm de facilitarem o trabalho de desenvolvimento.10.1 Acesso ao Banco de Dados Todo o acesso ao banco de dados dever ser feito atravs de classes do Xoops disponveis em XOOPS_ROOT_PATH/class/database. Para acessar as classes deve-se utilizar a declarao: global $xoopsDB; So utilizadas bsicamente as seguintes classes: SELECT: $sql = quot;select campo1, campo2, campo3 from quot; . $xoopsDB->prefix(meu_modulo_xxx) . quot; where condicao1 = quot; . $value; $result = $xoopsDB->query($sql); $num_linhas = $xoopsDB->getRowsNum($result); while ($linha = $xoopsDB->fetchArray($result) ) { $campo1 = $linha['campo1']; $campo2 = $linha['campo2']; $campo3 = $linha['campo3']; } 12. INSERT, UPDATE ou DELETE: $sql = sprintf(quot;UPDATE %s SET campo1 = %u, campo2 = '%s' WHERE condicao1 = %uquot;, $xoopsDB- >prefix(meu_modulo_xxx), intval($value1), $value2); if ( !$result = $xoopsDB->query($sql) ) {ErrorHandler::show('0022'); } 10.2 Segurana Aps instalar um mdulo, o Xoops cria automaticamente dois nveis de permisso: module_admin e module_read. O primeiro concede permisso para o usurio acessar a interface administrativa do mdulo, o segundo condede permisso para visualizar o contedo do mdulo. Novas permisses podem ser criadas para itens especficos do seu mdulo. As permisses so gravadas na tabela xoops_group_permission do banco de dados. Para verificar, criar e alterar a permisso de acesso a um mdulo ou a um tem de um mdulo, preciso utilizar as funes descritas em XOOPS_ROOT_PATH/kernel/groupperm.php .10.3 Formulrios Itens de formulrios podem se criados com o auxlio de classes prontas, descritas em XOOPS_ROOT_PATH/class/xoopsform10.4 Redirecionamento de pginas Existem funes prontas para redirecionar o usurio para pginas especcias no caso de uma operao ilegal ser realizada. Esta funo se encontra em XOOPS_ROOT_PATH/include/functions.php .11 Referncia Este texto foi fortemente baseado no contedo dos seguintes links: Module Dev Guide: http://dev.xoops.org/modules/phpwiki/index.php/ModuleDevGuide Xoops Module Development Guide http://dev.xoops.org/ Xoops Development Log http://devteam.xoops.org/ Recomendamos tambm conhecer os seguintes links: Site oficial do Xoops http://www.xoops.org Comunidade Xoops Paran http://www.xoops.pr.gov.br/ Comunidade XoopsBR http://xoopsbr.org/ 13. Comunidade Xoops Total http://www.xoopstotal.com.br/12 Licena Copyright Fbio Telles Rodriguez Este artigo uma publicao livre, voc pode redistribui-lo/modifica-lo sob os termos da GNU/GPL v 2 (junho de 1991) conforme publicada pela Free Software Foudation em http://www.gnu.org/licences/gpl.html