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
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. 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

3.4 Créditos
$modversion['credits'] = "XXX";

Créditos do módulo desenvolvido. Aqui é de praxe substituir XXX pelo nome dos
desenvolvedores.

3.5 Autor
$modversion['author'] = "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'] = "meu_modulo_help.html";

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'] = "";

3.7 Licença
$modversion['license'] = "XXX";

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'] = "images/meu_modulo_slogo.png";

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'] = "meu_modulo";

Esta linha descreve o nome do diretório do módulo.

3.11Arquivo SQL
$modversion['sqlfile']['mysql'] = "sql/mysql.sql";

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] = "xxx";

$modversion['tables'][1] = "yyy";

$modversion['tables'][2] = "zzz";
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'] = "admin/index.php";

$modversion['adminmenu'] = "admin/menu.php";

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/

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'] = "xxx.php";

$modversion['blocks'][1]['name'] = _MI_meu_modulo_XXX;

$modversion['blocks'][1]['description'] = “yyy”;

$modversion['blocks'][1]['show_func'] = "b_meu_modulo_xxx_show";

$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'] = "include/search.inc.php";

$modversion['search']['func'] = "meu_modulo_search";

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'] = "xxx.php";

$modversion['sub'][2]['name'] = _MI_meu_modulo_YYY;

$modversion['sub'][2]['url'] = "yyy.php";

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 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.

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 "../../../mainfile.php";

include_once XOOPS_ROOT_PATH."/class/xoopsmodule.php";

include_once XOOPS_ROOT_PATH."/include/cp_functions.php";

include_once XOOPS_ROOT_PATH."/include/xoopscodes.php";

include_once XOOPS_ROOT_PATH.'/class/xoopsformloader.php';

include '../../../include/cp_header.php';
if ( file_exists("../language/".$xoopsConfig['language']."/modinfo.php") ) {

include("../language/".$xoopsConfig['language']."/modinfo.php");

} else {

include("../language/english/modinfo.php");

/* 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'];

switch ($op)

case "xxx":

xxx();

break;

case "yyy":
yyy();

break;

case "default":

default();$adminmenu[3]['title'] = _MI_meu_modulo_ADMENU3;

$adminmenu[3]['link'] = "admin/groupperms.php";

$adminmenu[3]['title'] = _MI_meu_modulo_ADMENU3;

$adminmenu[3]['link'] = "admin/groupperms.php";

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'] = "admin/index.php?op=xxx";

$adminmenu[2]['title'] = _MI_meu_modulo_ADMENU2;

$adminmenu[2]['link'] = "admin/index.php?op=yyy";

?>
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;

?>

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." <input type='radio' name='options[]' value='1'";

if ($options[0] == 1) {

$form .= " checked='checked'";

$form .= " />"._YES;

$form .= "<input type='radio' name='options[]' value='0'";

if ($options[0] == 0) {

$form .= " checked='checked'";

$form .= " />"._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("XOOPS root path not defined");

}
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;

$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 "../../mainfile.php";

if ( file_exists("language/".$xoopsConfig['language']."/modinfo.php") ) {

include("language/".$xoopsConfig['language']."/modinfo.php");

} else {

include("language/english/modinfo.php");

/* 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 = "select campo1, campo2, campo3 from " . $xoopsDB->prefix(meu_modulo_xxx) . " where
condicao1 = " . $value”;

$result = $xoopsDB->query($sql);

$num_linhas = $xoopsDB->getRowsNum($result);

while ($linha = $xoopsDB->fetchArray($result) ) {

$campo1 = $linha['campo1'];

$campo2 = $linha['campo2'];

$campo3 = $linha['campo3'];

INSERT, UPDATE ou DELETE:

$sql = sprintf("UPDATE %s SET campo1 = %u, campo2 = '%s' WHERE condicao1 = %u", $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/

12 Licença
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