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. 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. 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. 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. 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. 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. 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. 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. 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. }
?>
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. $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. 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. – 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