Orientações para criação de módulointegrado ao Xoops 2.2.4

O Xoops é o acrônimo de eXtensible Object Oriented Portal System. É umaferramenta para gerenciamento de portais. Todo o código do Xoops pode ser obtidoem http://www.xoops.org . Antes de criar o seu próprio módulo, recomendamos quevocê instale o xoops numa máquina, instale alguns módulos disponíveis e estude ocó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 maisclaro os nossos exemplos. O Xoops conta com diversas listas de discussão e fórunsque podem ajudar o desenvolvedor na sua tarefa. Particularmente no Brasil, temosvá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óriosToda a estrutura de arquivos e diretórios deverá ser criada dentro deXOOPS_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áriosolicitar 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 áreaadministrativa para o módulo.

2.3.1 admin/menu.php

Arquivo contendo uma lista de todos as páginas administrativas que deverão comporo 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 dedestaque para algum conteúdo do módulo que pode ser exibido em diversassituações diferentes do site.

2.5 class/

Diretório a ser utilizado para todas as classes a serem utilizadas no módulo. Caso omó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 terminarcom a extensão “.php”.

2.6 language/

Diretório onde serão criados os textos a serem exibidos. Deverão ser criados pelomenos dois diretórios, um chamado brazil/ para os arquivos em Português do Brasile 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 doBrasil

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ódulomeu_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 pixelsde 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ãopossuir 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_ ea extensão .html .

2.11.1 templates/blocks

Diretório contento os temas para exibição dos blocos do módulo. Todos os nomesde 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 onome index.html com um conteúdo fixo de apenas uma linha:

<script>history.go(-1);</script>

3 Informações sobre o móduloO módulo meu_modulo deverá ser integrado no portal através de instalação domesmo. Para isso deverá fornecer informações básicas no arquivoxoops_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 oualgo 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 porexemplo 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 dosdesenvolvedores.

3.5 Autor

$modversion['author'] = "XXX”;

Pessoa que detém os créditos pelo módulo. Aqui é de praxe substituir XXX pelonome 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 queserá um tutorial sobre o sistema para ser utilizado pelos usuários do portal comalgum direito administrativo. O arquivo meu_modulo_help.html deverá constar emhelp/ 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çautilizada.

3.8 Flag official

$modversion['official'] = 0;

Esta linha é utilizada pelo portal para identificar que o módulo não faz parte dosistema 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 nainterface 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ódulomeu_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-seutilizar uma linha para cada tabela e substituir XXX, YYY, ZZZ pelo nome dastabelas. Não existe um limite para o número de tabelas utilizadas, apenas deve-setomar o cuidado de incrementar seqüencialmente o contador entre colchetes a partirdo 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ávelem 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.phpdeverã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 dosconteúdos do módulo. Substitua XXX, YYY e ZZZ pelos nomes dos arquivoscontidos em templates/ . É de praxe utilizar um template para cada arquivo principalque exibirá um tipo de conteúdo distinto. É possível utilizar qualquer número detemplates, 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áveldefinida em modinfo.php em language/

3.15 Blocos

Blocos são estruturas opcionais em um módulo, eles são utilizados para dardestaque 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 paraexibir o conteúdo do bloco referenciado na opção show_func;

o nome de uma função opcional dentro do arquivo anteriormente referenciadode uma função de edição de parâmetros opcionais da função referenciado naopção edit_func;

opções utilizadas na função opcional de edição. Na opção referenciada poroptions 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çãodos 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 contadorentre 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 zeropara inabilita-la. Para habilitar a busca, deve-se incluir as linhas seguintes e criarum arquivo meu_modulo.inc.php em include/ contendo uma funçãomeu_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 adicionadonenhum link no menu principal e em um caso contrário. Estaopção também afeta os locais diferentes onde os blocos podemaparecer, sendo possível selecionar um local diferente para cadaitem 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 menudefinido em modinfo.php em language/ e a URL deve ser um arquivoque conste no diretório raiz do módulo. Podem ser adicionadosquantos 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áriocom privilégios administrativos no site. Para isso, cada opção deveser possuir:

Um nome definido na opção name;

Um título definido na opção title referenciado no arquivomodinfo.php do diretório /languages

Uma descrição definida na opção description referenciada noarquivo modinfo.php do diretório /languages

Um tipo de item de formulário HTML definida na opçãoformtype 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 quepode 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 arraydefinidos 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ção20' => 20);

Podem ser criadas quantas opções de configuração se desejar,incrementando sempre o contador entre colchetes em um paracada item

As variáveis definidas nas configurações do módulo estarãodisponíveis no formato através da variável $xoopsModuleConfig['xxx']que poderá ser acessada a qualquer momento no código domódulo, uma vez que você inclua os arquivos indicados, conformedescrito mais adiante.

4 – InternacionalizaçãoO Xoops dispõe de um mecanismo simples de internacionalização que permite queos 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ínguainglesa for omitida o portal apresentará um erro. A estrutura do arquivo deinternacionalizaçã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 – TemplatesOs templates são utilizados no Xoops para separar a camada de dados da camada devisualização no sistema. Visando agilizar esta operação, ele utiliza um formato ágilde exibição do conteúdo através da tecnologia conhecida como Smarty.Documentação específica desta tecnologia pode ser encontrada emhttp://smarty.php.net/

Para se utilizar os templates com smarty no Xoops basta que a camada de dadosexporte 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 otemplate e var_name é o nome da variável que será utilizada no template daseguinte forma:

<{var_name}>

6 – Área administrativaUma área administrativa é utilizada para inserir novos conteúdos no módulo, alteraropçõ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 oseguinte 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 seumó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 decada menu e que o endereço de cada menu será o mesmo resgatado emadmin/index.php

7 – BlocosBlocos posuem uma estrutura simples e utilizam precisam apenasretornar um array contendo os dados a serem exibidos e umtemplate especial onde os dados são obtidos através da variável<{$block.var_name}> sendo var_name um ítem do array. Os doisarquivos 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çãocomo um array ($options[0], $options[1], $options[2], etc). Caso não sejadefinida nenhuma opção para o bloco, definimos a função somentecomo function b_news_topics_show(). Para blocos que utilizam opões,tabém devemos criar uma função responsável por exibir a opçãono formulário que instancia o bloco armazenando todo o códigohtml 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 – BuscaA busca integrada ao site deverá pesquisar no módulo acorrespondência com uma ou mais palavras chaves, retornandoum nome e link para cada item que casarem com o critério. Umúnico arquivo deverá ser criado em include/search.inc.php com oseguinte 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, comoindex.php na raiz do módulo e um template. Para que sejam carregadas as variáveisde 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 destedocumento.

10 – Funções e classesO Xoops possui uma série de funções e classes embutidas que devem ser utilizadasdentro de cada módulo. Estas classes, além de garantir a integração entre o móduloe o core do Xoops, também garantem uma série de checagens de segurança, além defacilitarem 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 Xoopsdisponíveis em XOOPS_ROOT_PATH/class/database. Para acessar asclasses 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) . " wherecondicao1 = " . $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árioacessar a interface administrativa do módulo, o segundo condede permissão paravisualizar o conteúdo do módulo. Novas permissões podem ser criadas para itensespecíficos do seu módulo. As permissões são gravadas na tabelaxoops_group_permission do banco de dados. Para verificar, criar e alterar apermissão de acesso a um módulo ou a um ítem de um módulo, é preciso utilizar asfunçõ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, descritasem 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 casode uma operação ilegal ser realizada. Esta função se encontra emXOOPS_ROOT_PATH/include/functions.php .

11 ReferênciaEste 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 Guidehttp://dev.xoops.org/

Xoops Development Loghttp://devteam.xoops.org/

12 LicençaEste 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 SoftwareFoudation em http://www.gnu.org/licences/gpl.html