Antes de começarmos, é interessante que o conceito de módulo esteja claro na mente de todos:
Um módulo é um pedaço de código que irá compor a estrutura da página. Normalmente não interage ou interage pouco com o usuário. Diferentemente dos componentes, que são carregados no 'corpo' da página.
Nosso Módulo:
Minha idéia é fazer um módulo que possa ser reaproveitado (pelo menos a idéia dele) nos seus sites e tenho visto no forum e recebido diversos pedidos por e-mail a respeito do módulozinho que eu fiz para o MamboPros que mostra a última notícia de uma determinada categoria. Então é alguma coisa nesse sentido (uma versão um pouco simplificada, mas que funciona) que iremos fazer hoje!
Vamos chamar de mod_showsect e ele vai precisar de dois arquivos:
mod_showsect.xml -> conterá as informações sobre o módulo.
mod_showsect.php -> conterá o código do módulo em si.
Vamos começar!
Crie um arquivo chamado mod_showsect.xml com o seguinte conteúdo:
<?xml version="1.0" encoding="iso-8859-1"?>
<mosinstall type="module" version="4.5.2">
<name>Show Section</name>
<author>Matheus Mendes aka bigodines (TM Web)</author>
<creationDate>January 2005</creationDate>
<copyright>(C) 2005 MetaSig</copyright>
<license>http://www.gnu.org/copyleft/gpl.html GNU/GPL</license>
<authorEmail>
Este endereço de e-mail está protegido contra spambots. Você deve habilitar o JavaScript para visualizá-lo.
Este endereço de e-mail está protegido contra spambots. Você deve habilitar o JavaScript para visualizá-lo.
</authorEmail>
<authorUrl>www.mambopros.net</authorUrl>
<version>1.0</version>
<description>This module shows a specified number of items of a category.</description>
<files>
<filename module="mod_showsect">mod_showsect.php</filename>
</files>
<params>
<param name="setSecao" type="text" default="0" label="Categoria" description="Qual é o id da seção desejada?" />
<param name="setNum_intro" type="text" default="1" label="Número de introduções" description="Quantas notícias devem conter introdução" />
<param name="setNum_links" type="text" default="1" label="Número de links" description="Quantas notícias devem aparecer com links no módulo" />
<param name="setLink_titulo" type="radio" default="1" label="Link no título" description="Inserir um link para o fulltext no título do ítem?">
<option value="1">sim</option>
<option value="0">não</option>
</param>
</params>
</mosinstall>
Calma, calma! não se dezespere! Vamos analizar tudo com calma!
<?xml version="1.0" encoding="iso-8859-1"?>
<mosinstall type="module" version="4.5.2">
Nas linhas acima, nós dizemos ao instalador/leitor do mambo (que utiliza o famoso DOMIT) que o nosso arquivo se trata de um XML de instalação de um 'module' para a versão 4.5.2 do mambo. (Você notará nos próximos tutoriais que este 'type' é o que dirá ao mambo que tipo de arquivo estamos instalando.. se é módulo, mambot, componente ou template).
<name>Show Section</name>
<author>Matheus Mendes aka bigodines (TM Web)</author>
<creationDate>January 2005</creationDate>
<copyright>(C) 2005 MetaSig</copyright>
<license>http://www.gnu.org/copyleft/gpl.html GNU/GPL</license>
<authorEmail>
Este endereço de e-mail está protegido contra spambots. Você deve habilitar o JavaScript para visualizá-lo.
Este endereço de e-mail está protegido contra spambots. Você deve habilitar o JavaScript para visualizá-lo.
</authorEmail>
<authorUrl>www.mambopros.net</authorUrl>
<version>1.0</version>
<description>This module shows a specified number of items of a category.</description>
Nessas linhas temos as informações do módulo. Na ordem:
- Nome do módulo
- Nome do autor do módulo
- Data de criação
- Copyright
- Licença
- E-mail do autor
- URL do autor
- Versão do módulo
- Breve descrição.
Podem parecer perfumaria, mas dados obrigatórios (lembre-se que é nesse xml que o mambo irá se basear para montar a tela com os módulos instalados) e importantíssimos caso você queira disponibilizar seus módulos 'para fora'.
<files>
<filename module="mod_showsect">mod_showsect.php</filename>
</files>
Agora devemos informar para o instalador quais arquivos vão estar atribuidos ao nosso novo módulo. No nosso caso, só um (uma vez que o xml não precisa ser citado!) e também devemos informar qual será o nome físico do nosso módulo.
<params>
<param name="setSecao" type="text" default="0" label="Categoria" description="Qual é o id da seção desejada?" />
<param name="setNum_intro" type="text" default="1" label="Número de introduções" description="Quantas notícias devem conter introdução" />
<param name="setNum_links" type="text" default="1" label="Número de links" description="Quantas notícias devem aparecer com links no módulo" />
<param name="setLink_titulo" type="radio" default="1" label="Link no título" description="Inserir um link para o fulltext no título do ítem?">
<option value="1">sim</option>
<option value="0">não</option>
</param>
</params>
A parte dos parâmetros irá permitir que possibilitemos dar ao usuário a opção de configurar alguns aspectos no nosso módulo (ou seja, atribuir valores pelo admin que possam ser recuperados pelo módulo quando esteve estiver sendo executado). No nosso caso teremos 3 variáveis que serão passadas por parâmetro para nosso módulo: setNum_intro ; setNum_links e setLink_titulo . Esta última terá seus valores pré-definidos (1 para sim e 0 para não).
Por fim a tag </mosinstall> encerra nosso arquivo de configuração. Agora vamos para o código do nosso módulo!
Agora que já temos nosso arquivo de instalação, vamos criar o nosso módulo própriamente dito. Para isso, crie um novo arquivo chamado: mod_showsect.php que terá o seguinte código:
/**
------ Show Section Module! ----------
Author: Matheus Mendes aka bigodines (
Este endereço de e-mail está protegido contra spambots. Você deve habilitar o JavaScript para visualizá-lo.
Este endereço de e-mail está protegido contra spambots. Você deve habilitar o JavaScript para visualizá-lo.
)
Date: January, 2005
Version: 1 (will it have more than one?)
Package: mambo_4.5.1a
Description: This is my dumm, simple and dirty module to show items from only one section of your site.
* sorry folks, the header is the only english part of this file. that's because my english sux. *
*/
defined( '_VALID_MOS' ) or die( 'Direct Access to this location is not allowed.' );
global $mainframe;
$now = date( 'Y-m-d H:i:s', time() );
/* configurações */
// define a categoria dos ítens que serão mostrados.
$secao = intval( $params->get( 'setSecao' ) );
// quantas notícias serão mostradas as introduções.
$num_intro = intval ( $params->get( 'setNum_intro' ) );
// quantas notícias serão mostrados os links.
$num_links = intval ( $params->get( 'setNum_links' ) );
// define se o título linkará para a notícia.
$link_titulo = intval ( $params->get( 'setLink_titulo' ) );
/* fim das configurações. */
// precisava reduzir o número de queries usadas no getItemid
$bs = $mainframe->getBlogSectionCount();
$bc = $mainframe->getBlogCategoryCount();
$gbs = $mainframe->getGlobalBlogSectionCount();
$total = $num_intro + $num_links;
$sql = "SELECT c.id, c.title, c.introtext as intro, c.sectionid, c.catid
FROM #__content as c
LEFT JOIN #__sections as sect on sect.id = c.sectionid
WHERE ( c.state = '1' AND c.checked_out = '0' AND c.sectionid > '0' )"
. "n AND ( c.publish_up = '0000-00-00 00:00:00' OR c.publish_up <= '". $now ."' )"
. "n AND ( c.publish_down = '0000-00-00 00:00:00' OR c.publish_down >= '". $now ."' )"
. "nAND c.sectionid = $secao"
. "nORDER BY c.created DESC "
. "nLIMIT 0, $total";
$database->setQuery( $sql );
$resultado = $database->loadObjectList();
$i = 0; // preciso saber a hora de parar de mostrar a introdução.
// show me babe... ;P
foreach( $resultado as $r ) {
// pegando o itemid
$Itemid = $mainframe->getItemid( $r->id, 0, 0, $bs, $bc, $gbs );
// itemid é em branco quanto estiver com o SEF
if ($Itemid == NULL) {
$Itemid = '';
} else {
$Itemid = '&Itemid=';
}
if (++$i <= $num_intro) {
echo ($link_titulo > 0)?"<tr><td class="showsect"><a href="/.sefRelToAbs("index.php?option=com_content&task=view&id=$r->id".$Itemid."").">" .$r->title . "</a></td></tr>":"<tr><td class="showsect">" . $r->title . "</td></tr>";
echo "<tr><td align=justify class="showsect">" . $r->intro . "</td></tr>";
} else if ($i <= $total) {
echo "<tr><td class="showsect"><a href="/.sefRelToAbs("index.php?option=com_content&task=view&id=$r->id".$Itemid."").">" .$r->title . "</a></td></tr>";
}
}
Atenção: Eu não pretendo ensinar ninguém a programar em PHP, estou partindo do princípio de que você já é um programador e está querendo começar com o mambo (se você ainda não está familiarizado com a linguagem, recomendo que procure tutoriais pela internet e pare de ler este tutorial agora).
Vamos destrinchar um pouco desse arquivo e ver o que faz essa bagunça toda!
defined( '_VALID_MOS' ) or die( 'Direct Access to this location is not allowed.' );
global $mainframe;
$now = date( 'Y-m-d H:i:s', time() );
Bueno, a primeira linha irá matar a execução caso haja uma tentativa de acesso direto ao arquivo (possivelmente uma tentativa de hacking). Ela está presente em todos os módulos e componentes pois é uma verificação de segurança padrão do mambo.
Na segunda linha nós chamamos o objeto (que foi instanciado no index) $mainframe que é um objeto da classe mainframe (duh!) do mambo. Desta classe nós iremos utilizar os métodos para pegar o itemid correto do conteúdo que está sendo acessado. (prometo que vou escrever um tutorial só sobre a classe mainframe e como ela manipula a API do mambo).
/* configurações */
// define a categoria dos ítens que serão mostrados.
$secao = intval( $params->get( 'setSecao' ) );
// quantas notícias serão mostradas as introduções.
$num_intro = intval ( $params->get( 'setNum_intro' ) );
// quantas notícias serão mostrados os links.
$num_links = intval ( $params->get( 'setNum_links' ) );
// define se o título linkará para a notícia.
$link_titulo = intval ( $params->get( 'setLink_titulo' ) );
Está vendo alguma coisa famíliar? Não? Olhe novamente. Isso mesmo, estamos pegando os valores dos parâmetros que podem ser configurados na parte admnistrativa do módulo e atribuindo para uma variável.
// precisava reduzir o número de queries usadas no getItemid
$bs = $mainframe->getBlogSectionCount();
$bc = $mainframe->getBlogCategoryCount();
$gbs = $mainframe->getGlobalBlogSectionCount();
Pode parecer apavorante, mas esses métodos só retornam o número de categorias de blog e seções de blog publicadas. Vão servir para que possamos determinar o itemid correto do nosso conteúdo.
$total = $num_intro + $num_links;
Bom.. Nosso $total é o número de ítens com introdução + número de notícias que conterão apenas o link no título.
$sql = "SELECT c.id, c.title, c.introtext as intro, c.sectionid, c.catid
FROM #__content as c
LEFT JOIN #__sections as sect on sect.id = c.sectionid
WHERE ( c.state = '1' AND c.checked_out = '0' AND c.sectionid > '0' )"
. "n AND ( c.publish_up = '0000-00-00 00:00:00' OR c.publish_up <= '". $now ."' )"
. "n AND ( c.publish_down = '0000-00-00 00:00:00' OR c.publish_down >= '". $now ."' )"
. "nAND c.sectionid = $secao"
. "nORDER BY c.created DESC "
. "nLIMIT 0, $total";
$database->setQuery( $sql );
$resultado = $database->loadObjectList();
Nessa SQL nós pegamos o conteúdo que está atribuido à seção (lembre-se que a seção já foi configurada e passada por parâmetro para o nosso módulo pela parte administrativa).
O objeto $database será um de seus melhores amigos se você quiser levar esse lance de mambo realmente a sério. É uma classe de banco de dados muito completa, simples e eficaz. Um dos seus métodos mais utilizados é o loadObjectList que nada mais é do que montar um array de objetos (transforma os campos em atributos para este objeto). No nosso módulo, nós jogaremos tudo isso para dentro do array $resultado.
$i = 0; // preciso saber a hora de parar de mostrar a introdução.
// show me babe... ;P
foreach( $resultado as $r ) {
// pegando o itemid
$Itemid = $mainframe->getItemid( $r->id, 0, 0, $bs, $bc, $gbs );
// itemid é em branco quanto estiver com o SEF
if ($Itemid == NULL) {
$Itemid = '';
} else {
$Itemid = '&Itemid=';
}
if (++$i <= $num_intro) {
echo ($link_titulo > 0)?"<tr><td class="showsect"><a href="/.sefRelToAbs("index.php?option=com_content&task=view&id=$r->id".$Itemid."").">" .$r->title . "</a></td></tr>":"<tr><td class="showsect">" . $r->title . "</td></tr>";
echo "<tr><td align=justify class="showsect">" . $r->intro . "</td></tr>";
} else if ($i <= $total) {
echo "<tr><td class="showsect"><a href="/.sefRelToAbs("index.php?option=com_content&task=view&id=$r->id".$Itemid."").">" .$r->title . "</a></td></tr>";
}
}
Agora estamos mostrando o conteúdo da nossa query própriamente dita. O que fazemos aqui num primeiro momento é pegar o ItemID do nosso conteúdo (foi passa isso que nós trouxemos o $mainframe lembra? Mas se o usuário estiver com o SEF (Search Engine Friendly) do mambo ativo, não vai haver ItemID. Devemos estar preparados para isso. Depois que temos (ou não temos) o nosso itemd, fazemos uma verificação: 'O número de introduções que já foram exibidas é menor ou igual ao número de introduções que terão de ser exibidas? (lembre que tudo já foi configurado na parte administrativa). Em caso afirmativo, eu posso exibir o texto da introdução desse componente caso contrário faço um teste (acho que desnecessário, mas tudo bem) para ver se o número de notícias que já foram exibidas não excede o númerototal pré-configurado. Esse teste é desncessário pois o número total já está estabelecido na query. Mas vou deixar ele aqui por um motivo desconhecido :D
Alguém pode ter estranhado aquela função sefRefToAbs("link") ali no meio do link. Bom, como todos sabem, o mambo oferece suporte à SEF. Ou seja, uma url index.php?option=com_content&task=view&id=25 pode virar index.php/option,com_content/task,view/id,25 Ou ainda http://www.mambopros.net/nome_do_artigo/ essa é a função que irá garantir que o link padrão irá funcionar mesmo que os components SEF estejam instalados.
Bom pessoal, sei que este tutorial pode ser muito avançado para uns, muito iniciante para outros. Algumas explicações podem ter deixado a desejar ou foram muito confusas. Mas acho que pelo menos deu para ter uma noção do funcionamento de um módulo, e da classe $database (pelo menos era essa a intenção).
Estou aguardando os e-mails com sugestões, comentários e dicas (ou quem sabe alguma correção no código).
Abraço e até a próxima,
Matheus Mendes
