Tutorial para criação de módulo no Xoops 2.4

2,137 views
2,055 views

Published on

Published in: Technology
0 Comments
1 Like
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
2,137
On SlideShare
0
From Embeds
0
Number of Embeds
5
Actions
Shares
0
Downloads
108
Comments
0
Likes
1
Embeds 0
No embeds

No notes for slide

Tutorial para criação de módulo no Xoops 2.4

  1. 1. Orientações para criação de módulo integrado ao Xoops 2.2.4 O Xoops é o acrônimo de eXtensible Object Oriented Portal System. É uma ferramenta para gerenciamento de portais. Todo o código do Xoops pode ser obtido em http://www.xoops.org . Antes de criar o seu próprio módulo, recomendamos que você instale o xoops numa máquina, instale alguns módulos disponíveis e estude o código destes módulos para somente então começar a desenvolver o seu módulo. Neste exemplo, estamos supondo que o nome do módulo a ser criado é “meu_modulo”. Realizamos esta suposição com fins didáticos a fim de tornar mais claro os nossos exemplos. O Xoops conta com diversas listas de discussão e fóruns que podem ajudar o desenvolvedor na sua tarefa. Particularmente no Brasil, temos vários grupos que mantém este tipo de ferramenta de suporte. 1 – Ambiente utilizado 1.1 Linguagem de programação: PHP 4.3.10 1.2 Servidor Web: Apache 2.0.54 1.3 Banco de Dados: MySQL 4.0.24 1.3 – Localização dos arquivos: XOOPS_ROOT_PATH/modules/meu_modulo/ 1.4 – URL: XOOPS_URL/modules/meu_modulo/ 2 – Estrutura de diretórios Toda a estrutura de arquivos e diretórios deverá ser criada dentro de XOOPS_ROOT_PATH/modules/meu_modulo/ 2.1 xoops_version.php Arquivo contento informações básicas sobre o módulo. 2.2 index.php Arquivo inicial do módulo. Este arquivo será carregado sempre que o usuário
  2. 2. solicitar entrar no módulo sem especificar um destino específico. 2.3 admin/ Diretório opcional contendo todos os arquivos necessários para criar uma área administrativa para o módulo. 2.3.1 admin/menu.php Arquivo contendo uma lista de todos as páginas administrativas que deverão compor o menu de administração do Xoops. 2.3.2 admin/index.php Arquivo principal da administração do módulo. 2.4 blocks/ Diretório opcional contendo blocos do módulo. Um bloco no Xoops é uma área de destaque para algum conteúdo do módulo que pode ser exibido em diversas situações diferentes do site. 2.5 class/ Diretório a ser utilizado para todas as classes a serem utilizadas no módulo. Caso o módulo não utilize classes, este diretório poderá ser omitido. O nome de cada arquivo contendo as classes deverá ter o prefixo “class.” e terminar com a extensão “.php”. 2.6 language/ Diretório onde serão criados os textos a serem exibidos. Deverão ser criados pelo menos dois diretórios, um chamado brazil/ para os arquivos em Português do Brasil e um chamado english/ para os arquivos em inglês. 2.6.1 language/brazil/modinfo.php Arquivo contendo textos básicos do módulo meu_modulo na língua Português do Brasil 2.6.2 language/english/modinfo.php Arquivo contendo textos básicos do módulo meu_modulo na língua inglesa 2.7 include/ Diretório onde serão criadas funções a serem incluídas em outros arquivos 2.8 images/ Diretório onde serão armazenadas todas as imagens a serem utilizadas pelo módulo meu_modulo 2.9 images/meu_modulo_logo.png Logotipo do módulo meu_modulo a ser utilizado na administração do portal.
  3. 3. Deverá estar no formato png e possuir as dimensões de 92 pixels de largura por 52 pixels de altura 2.10 meu_modulo/sql/mysql.sql Arquivo contendo um script SQL com o DDL para a criação de todas as tabelas, visões e seqüências do sistema. Todos os objetos criados no banco de dados deverão possuir um prefixo “meu_modulo_” no seu nome. 2.11 templates/ Diretório contendo os temas para exibição do conteúdo do módulo. Todos os nomes de arquivos desta pasta deverão possuir o prefixo meu_modulo_ e a extensão .html . 2.11.1 templates/blocks Diretório contento os temas para exibição dos blocos do módulo. Todos os nomes de arquivos desta pasta deverão possuir o prefixo meu_modulo_block_ e a extensão .html . 2.12 index.html Por motivos de segurança, todos os diretórios criados deverão ter um arquivo com o nome index.html com um conteúdo fixo de apenas uma linha: <script>history.go(-1);</script> 3 Informações sobre o módulo O módulo meu_modulo deverá ser integrado no portal através de instalação do mesmo. Para isso deverá fornecer informações básicas no arquivo xoops_version.php. 3.1 Nome do módulo $modversion['name'] = “XXX”; Esta linha deve constar para descrever o nome do módulo durante a instalação. Substitua XXX pelo nome do módulo. Sugerimos utilizar o nome meu_modulo ou algo parecido e curto. 3.2 Versão $modversion['version'] = XXX; Versão do módulo meu_modulo. Substituir XXX pelo número da versão como por exemplo 1.0 3.3 Descrição $modversion['description'] = _MI_meu_modulo_DESC; Descrição do módulo meu_modulo (o que ele faz). A variável MI_meu_modulo_DESC deverá ser definida nos arquivos modinfo.php
  4. 4. 3.4 Créditos $modversion['credits'] = quot;XXXquot;; Créditos do módulo desenvolvido. Aqui é de praxe substituir XXX pelo nome dos desenvolvedores. 3.5 Autor $modversion['author'] = quot;XXX”; Pessoa que detém os créditos pelo módulo. Aqui é de praxe substituir XXX pelo nome da empresa ou equipe que possui direitos autorais sobre o módulo. 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 usuários do portal com algum direito administrativo. O arquivo meu_modulo_help.html deverá constar em help/ e poderá utilizar outros arquivos dentro do mesmo diretório. Caso não seja criada uma estrutura de help, o parâmetro deverá ser colocado como: $modversion['help'] = quot;quot;; 3.7 Licença $modversion['license'] = quot;XXXquot;; Tipo de licença utilizada pelo módulo. Substitua XXX pelo nome da licença utilizada. 3.8 Flag official $modversion['official'] = 0; Esta linha é utilizada pelo portal para identificar que o módulo não faz parte do sistema originalmente mantido pela equipe de desenvolvimento do portal. 3.9 Logotipo do módulo: $modversion['image'] = quot;images/meu_modulo_slogo.pngquot;; Esta linha identifica o logotipo do módulo meu_modulo que será exibido na interface administrativa do portal. 3.10 Diretório do módulo $modversion['dirname'] = quot;meu_moduloquot;; Esta linha descreve o nome do diretório do módulo.
  5. 5. 3.11Arquivo SQL $modversion['sqlfile']['mysql'] = quot;sql/mysql.sqlquot;; Esta linha descreve o arquivo que será utilizado para criar as tabelas do módulo meu_modulo. 3.12 Tabelas do módulo $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 módulo. Deve-se utilizar uma linha para cada tabela e substituir XXX, YYY, ZZZ pelo nome das tabelas. Não existe um limite para o número de tabelas utilizadas, apenas deve-se tomar o cuidado de incrementar seqüencialmente o contador entre colchetes a partir do zero. 3.13 Área administrativa $modversion['hasAdmin'] = 0; Esta linha descreve se o módulo possui uma área administrativa. Em caso negativo, deve-se deixar o valor da variável em zero, caso contrário, deve-se deixar a variável 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 deverão ser criados no diretório 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 páginas aos usuários dos conteúdos do módulo. 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 conteúdo distinto. É possível utilizar qualquer número de templates, a partir de um, incrementando-se sempre o contador em um para cada template . A descrição é opcional, mas se existir, deve-se utilizar uma variável definida em modinfo.php em language/ 3.15 Blocos Blocos são estruturas opcionais em um módulo, eles são utilizados para dar destaque em algum conteúdo específico. Cada bloco deve ter: – um arquivo em blocks/ referenciado na opção file; – um nome armazenado no arquivo modinfo.php do diretório language/
  6. 6. referenciado na opção name; – uma descrição sobre o que o bloco faz referenciada na opção description; – o nome de uma função dentro do arquivo anteriormente referenciado para exibir o conteúdo do bloco referenciado na opção show_func; – o nome de uma função opcional dentro do arquivo anteriormente referenciado de uma função de edição de parâmetros opcionais da função referenciado na opção edit_func; – opções utilizadas na função opcional de edição. Na opção referenciada por options colocar o valor default de cada opção separada por um “|”; – um arquivo em templates/blocks/ referenciado na opção 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 administração dos blocos fornecida pelo Xoops. Podem ser criados nenhum bloco ou vários deles, para atender diversos propósitos. Para cada bloco deve- se incrementar o contador entre colchetes em um. 3.16 Busca $modversion['hasSearch'] = 1; Estas linhas descrevem a integração com o mecanismo de busca. A opção “has_Search” deve estar em um para que a integração 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 função meu_modulo_search contendo o código necessário. $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 não for adicionado nenhum link no menu principal e em um caso contrário. Esta opção também afeta os locais diferentes onde os blocos podem aparecer, sendo possível 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 opção 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 diretório raiz
  7. 7. do módulo. Podem ser adicionados quantos itens de menu se quiserem, incrementando sempre o contador entre colchetes em um para cada item 3.18 Configuração do módulo Podem ser adicionadas opções a serem setadas por algum usuário com privilégios administrativos no site. Para isso, cada opção deve ser possuir: – Um nome definido na opção name; – Um título definido na opção title referenciado no arquivo modinfo.php do diretório /languages – Uma descrição definida na opção description referenciada no arquivo modinfo.php do diretório /languages – Um tipo de item de formulário HTML definida na opção formtype que pode ser: – uma caixa de seleção para utilizando o valor select; – uma opção do tipo “sim ou não” utilizando o valor yesno; – uma caixa de texto utilizando o valor textbox; – uma caixa de seleção de data utilizando o valor date; – Um tipo de valor de retorno definida na opção valuetype que pode ser: – texto utilizando o valor text; – inteiro utilizando o valor int; – Um valor default definido na opção default; – Valores listados numa caixa de seleção no formato de array definidos na opção 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('Opção A' => 'A', 'Opção B' => 'B', 'Opção 10' => 10, 'Opção 20' => 20); Podem ser criadas quantas opções de configuração se desejar, incrementando sempre o contador entre colchetes em um para cada item As variáveis definidas nas configurações do módulo estarão disponíveis no formato através da variável $xoopsModuleConfig['xxx'] que poderá ser acessada a qualquer momento no código do módulo, uma vez que você inclua os arquivos indicados, conforme descrito mais adiante. 4 – Internacionalização O Xoops dispõe de um mecanismo simples de internacionalização que permite que os textos exibidos pelo portal possam trocar de língua automaticamente. Para isso, são criados arquivos para contextos diferentes para cada língua utilizada em /languages. A língua padrão é o inglês, portanto ela deve sempre existir. Se a língua inglesa for omitida o portal apresentará um erro. A estrutura do arquivo de internacionalização é o seguinte: define('_MI_meu_modulo_NAME','Biblioteca meu_modulo'); define('_MI_meu_modulo_DESC,'Módulo de exibição do conteúdo do sistema meu_modulo'); São Definidas apenas uma linha para cada variável.
  8. 8. 5 – Templates Os templates são utilizados no Xoops para separar a camada de dados da camada de visualização no sistema. Visando agilizar esta operação, ele utiliza um formato ágil de exibição do conteúdo através da tecnologia conhecida como Smarty. Documentação específica 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 conteúdo através da função: $xoopsTpl->assign('var_name', $value); Onde $value é o valor (que pode ser um array ou não) que será passado para o template e var_name é o nome da variável que será utilizada no template da seguinte forma: <{var_name}> 6 – Área administrativa Uma área administrativa é utilizada para inserir novos conteúdos no módulo, alterar opções de exibição ou instanciar blocos. A área administrativa possui dois arquivos principais guardados em /admin: – index.php Este arquivo consiste na página de menu propriamente dita. Ela deve possuir o seguinte formato: <?php include_once quot;../../../mainfile.phpquot;; include_once XOOPS_ROOT_PATH.quot;/class/xoopsmodule.phpquot;; include_once XOOPS_ROOT_PATH.quot;/include/cp_functions.phpquot;; include_once XOOPS_ROOT_PATH.quot;/include/xoopscodes.phpquot;; include_once XOOPS_ROOT_PATH.'/class/xoopsformloader.php'; include '../../../include/cp_header.php'; if ( file_exists(quot;../language/quot;.$xoopsConfig['language'].quot;/modinfo.phpquot;) ) { include(quot;../language/quot;.$xoopsConfig['language'].quot;/modinfo.phpquot;); } else { include(quot;../language/english/modinfo.phpquot;); } /* Insira as funções para cada menu aqui */ $op = 'default'; if(isset($_POST['op'])) { $op=$_POST['op']; } else { if(isset($_GET['op'])) { $op=$_GET['op']; } }
  9. 9. switch ($op) { case quot;xxxquot;: xxx(); break; case quot;yyyquot;: yyy(); break; case quot;defaultquot;: default();$adminmenu[3]['title'] = _MI_meu_modulo_ADMENU3; $adminmenu[3]['link'] = quot;admin/groupperms.phpquot;; $adminmenu[3]['title'] = _MI_meu_modulo_ADMENU3; $adminmenu[3]['link'] = quot;admin/groupperms.phpquot;; break } xoops_cp_footer(); ?> Note que você deve criar uma função para cada ítem de menu administrativo. Substitua xxx, yyy e default pelas funções que você criar. – menu.php Este arquivo deve conter um lista com todos os itens de menu administrativo do seu módulo: <?php $adminmenu[1]['title'] = _MI_meu_modulo_ADMENU1; $adminmenu[1]['link'] = quot;admin/index.php?op=xxxquot;; $adminmenu[2]['title'] = _MI_meu_modulo_ADMENU2; $adminmenu[2]['link'] = quot;admin/index.php?op=yyyquot;; ?> Note que você deve definir em modinfo.php do diretório /languages os nomes de cada menu e que o endereço de cada menu será o mesmo resgatado em admin/index.php 7 – 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 são obtidos através da variável <{$block.var_name}> sendo var_name um ítem do array. Os dois arquivos utilizados pelo bloco são: – xxx.php em blocks/ <?php function b_news_topics_show($options) { /* Coloque aqui o código do seu bloco */ $block['var_name'] = $value; return $block;
  10. 10. } ?> Note que as opções definidas no bloco são passadas para a função como um array ($options[0], $options[1], $options[2], etc). Caso não seja definida nenhuma opção para o bloco, definimos a função somente como function b_news_topics_show(). Para blocos que utilizam opões, tabém devemos criar uma função responsável por exibir a opção no formulário que instancia o bloco armazenando todo o código html na variável $form como no exemplo abaixo: function b_news_topicsnav_edit($options) { $form = _MB_NEWS_SHOW_NEWS_COUNT.quot; <input type='radio' name='options[]' value='1'quot;; if ($options[0] == 1) { $form .= quot; checked='checked'quot;; } $form .= quot; />quot;._YES; $form .= quot;<input type='radio' name='options[]' value='0'quot;; if ($options[0] == 0) { $form .= quot; checked='checked'quot;; } $form .= quot; />quot;._NO; return $form; – meu_modulo_block_xxx.html em templates/blocks/ <div> <{$block.var_name}> </div> 8 – Busca A busca integrada ao site deverá pesquisar no módulo a correspondência com uma ou mais palavras chaves, retornando um nome e link para cada item que casarem com o critério. Um único arquivo deverá ser criado em include/search.inc.php com o seguinte formato: <?php if (!defined('XOOPS_ROOT_PATH')) { die(quot;XOOPS root path not definedquot;); } function news_search($queryarray, $andor, $limit, $offset, $userid){ global $xoopsDB, $xoopsUser; // $queryarray = array contendo uma ou mais palavras-chave de busca // $andor = critério de busca é E ou OU // $limit = número máximo de linhas a serem retornadas // $offset = número de linhas a serem puladas // $userid = id do usuário que está acessando a busca /* Insira aqui o código da busca do seu módulo */ /* Inclua um loop com a variável $i numérica para cada item que casar com as palavras-chave $ret[$i]['image'] = $imagem; $ret[$i]['link'] = $link; $ret[$i]['title'] = $titulo;
  11. 11. $ret[$i]['time'] = $data_criacao; $ret[$i]['uid'] = $id_usuário_criacao; return $ret; } ?> 9 – Conteúdo principal O conteúdo a ser exibido deve possuir um arquivo que selecione o conteúdo, como index.php na raiz do módulo e um template. Para que sejam carregadas as variáveis de ambiente e todo o cabeçalho, rodapé, barra lateral esquerda e direita, blocos etc, é preciso seguir o seguinte padrão: <?php include quot;../../mainfile.phpquot;; if ( file_exists(quot;language/quot;.$xoopsConfig['language'].quot;/modinfo.phpquot;) ) { include(quot;language/quot;.$xoopsConfig['language'].quot;/modinfo.phpquot;); } else { include(quot;language/english/modinfo.phpquot;); } /* Coloque aqui o código para seleção do conteúdo */ $xoopsTpl->assign('var_name', $value); include_once XOOPS_ROOT_PATH.'/footer.php'; ?> Onde cada valor a ser exportado (no formato array ou não) deverá utilizar a classe $xoopsTpl como explicado no item 5 deste documento. 10 – Funções e classes O Xoops possui uma série de funções e classes embutidas que devem ser utilizadas dentro de cada módulo. Estas classes, além de garantir a integração entre o módulo e o core do Xoops, também garantem uma série de checagens de segurança, além de facilitarem o trabalho de desenvolvimento. 10.1 Acesso ao Banco de Dados Todo o acesso ao banco de dados deverá ser feito através de classes do Xoops disponíveis em XOOPS_ROOT_PATH/class/database. Para acessar as classes deve-se utilizar a declaração: global $xoopsDB; São utilizadas básicamente 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. 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 Segurança Após instalar um módulo, o Xoops cria automaticamente dois níveis de permissão: module_admin e module_read. O primeiro concede permissão para o usuário acessar a interface administrativa do módulo, o segundo condede permissão para visualizar o conteúdo do módulo. Novas permissões podem ser criadas para itens específicos do seu módulo. As permissões são gravadas na tabela xoops_group_permission do banco de dados. Para verificar, criar e alterar a permissão de acesso a um módulo ou a um ítem de um módulo, é preciso utilizar as funções descritas em XOOPS_ROOT_PATH/kernel/groupperm.php . 10.3 Formulários Itens de formulários podem se criados com o auxílio de classes prontas, descritas em XOOPS_ROOT_PATH/class/xoopsform 10.4 Redirecionamento de páginas Existem funções prontas para redirecionar o usuário para páginas especícias no caso de uma operação ilegal ser realizada. Esta função se encontra em XOOPS_ROOT_PATH/include/functions.php . 11 Referência Este texto foi fortemente baseado no conteúdo 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 também 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. 13. – Comunidade Xoops Total http://www.xoopstotal.com.br/ 12 Licença Copyright © <2006> Fábio Telles Rodriguez <fabio.telles@gmail.com> Este artigo é uma publicação 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

×