Criando Módulos XOOPS - 02: Constantes

Olá pessoal, estamos aqui com mais uma etapa do nosso aprendizado sobre o desenvolvimento de módulos para XOOPS, hoje trataremos das constantes de linguagem.

02: Constantes no XOOPS

02.1. O XOOPS é um CMS programado na linguagem PHP orientado a objetos, inclusive é o significado dos dois ós da palavra XOOPS, como qualquer linguagem de programação é comum falar em variáveis, que no php são identificadas pelo cifrão "$" seguido do nome da variável, sabemos também que variável é uma espécie de cápsula em que se armazena algum dado, porém o mesmo pode ser mudado a qualquer tempo, definindo novo dado para a mesma variável ou eliminando ela.

02.2. Pois bem, constante é praticamente a mesma coisa que a variável, porém seu conteúdo é definido de modo fixo ou único, seu valor não pode mudar durante a execução do script, com exceção das "constantes mágicas" (que não são constantes de verdade). Outra diferença que a constante não é identificada com nenhum sinal, ela é definida e a partir daque ponto ela carrega o dado definido para ela, vale lembrar que o PHP é sensível ao formato da letra (case-sensitive).

02.3. No XOOPS temos particularmente dois tipos de constantes, vamos chamar de constantes de programação e constantes de linguagem ou idioma (que fica melhor de identificar), por padrão do desenvolvimento do CMS, as constantes devem sempre estar escritas com todas as letras em maiúsculo, ou seja, CONSTANTES. Ainda nessa padronização, as CONSTANTES de programação são escritas direta e naturalmente, enquanto as CONSTANTES de idioma devem começar com um traço de chão (underline) "_", ficando assim _CONSTANTE. Essa padronização ajuda principalmente a tornar o código mais legível.

02.4. Para se definir uma constante, basta usar o comando "define()" PHP:

02.5. De princípio pode parecer estranho, mas esse recurso da linguagem é muito útil e com o tempo você vai perceber, como é útil o XOOPS também se utilizou desse recurso.

02.6: Constantes de Programação no XOOPS

02.6.1. Na primeira lição deste nosso mini curso utilizamos uma constante duas vezes, não deveria, mas a força do hábito acaba automatizando as coisas e fazemos sem perceber, já identificou onde usamos a tal constante?

02.6.2. Exatamente, usamos no arquivo index.php para chamar dois arquivos o header.php e o footer.php.

02.6.3. A constante em questão foi a XOOPS_ROOT_PATH, que como o seu próprio nome sugere o seu valor é o caminho da raiz do XOOPS, ou seja, aquele diretório onde se encontram todos os arquivos e subdiretórios do nosso querido CMS.

02.6.4. Estas constantes estão espalhadas por todo o código do XOOPS, exercendo a sua finalidade, porém podemos neste ponto do mini curso observar algumas constantes muito importantes, as que estão definidas no arquivos mainfile.php, no diretório raiz do XOOPS.

02.6.5. (Não vou postar o código do arquivo aqui, pois não é o foco do nosso tuto, mas vamos analisar as constantes do arquivo:

a) XOOPS_MAINFILE_INCLUDED, se a constante se não estiver setada como verdadeira a mesma será setada naquele momento. Esta constante não nos serve muito, a finalidade dela é dizer para o XOOPS se o sistema já está instalado, através da inclusão do arquivo mainfile;

b) XOOPS_ROOT_PATH, esta é praticamente a constante mais utilizada do XOOPS, pois define o caminho físico para o diretório raiz do XOOPS, para exemplificar, aqui no meu pc é "G:/xampp/htdocs/xoops/250" (sim, estou usando vindóvis neste momento), observamos que sem a barra final;

c) XOOPS_PATH, armazena o caminho físico para as bibliotecas do XOOPS;

d) XOOPS_VAR_PATH, armazena o caminho físico para os arquivos de dados do XOOPS;

e) XOOPS_TRUST_PATH, armazena o caminho físico para as bibliotecas do XOOPS, obsevamos pelos comentários do código que é uma solução temporária para compatibilidade, não recomendamos usar essa constante no módulo, pois eventualmente numa nova versão do XOOPS ela será removida e o módulo necessitará ser revisado para manter a compatibilidade com o próprio XOOPS;

f) XOOPS_PROT, armazena o protocolo HTTP ou HTTPS já com os dois pontos e as duas barras "://";

g) XOOPS_URL, esta constante disputa com a XOOPS_ROOT_PATH o posto de mais utilizada no código do CMS e dos módulos, pois ela armazena o endereço eletronico da página inicial do XOOPS, no meu pc é "http://localhost/xoops/250", vale lembrar que embora levem para o mesmo lugar são diferentes, principalmente no uso.

02.6.6. O arquivo tem mais constantes, mas paramos por aqui, pois estão serão muito úteis no desenvolvimento. Mas como usamos? Na escrita do código incluímos a constante como se o seu valor estivesse escrito lá, por exemplo:

02.6.7. No início deste item comentamos que utilizamos duas vezes a constante para chamar arquivos, mas vimos que chamamos três arquivos para o index.php, por que então não utilizamos três vezes a mesma constante? Está correto quem lembrou que a constante, assim como as variáveis, precisam ser definidas, sendo assim apenas após a execução do arquivo mainfile.php que as constantes começaram a existir para o nosso módulo.

02.6.8. Neste ponto a utilidade das constante já ficou mais clara.

02.7. Constantes de Idioma no XOOPS

02.7.1. As constantes de idioma têm a mesma função que as demais, porém específicas para propriciar a internacionalização do XOOPS e de seus módulos, para que o usuário possa num clique alterar todo o idioma do CMS.

02.7.2. Logicamente, dentro do diretório do módulo, as definições de linguagem ficam dentro do sub-diretório chamada "language" e o dentro de um novo sub-diretório com o nome do idioma a que se refere.

02.7.3. Para que um idioma funcione no XOOPS todos os diretórios que contiverem as traduções devem ter o mesmo nome, ou seja, se no diretório "language" principal do XOOPS o idioma português brasileiro estiver num sub-diretório chamado "pt-br_utf8" em todos os demais locais também deverão estar com o mesmo nome.

02.7.4. Aproveitamos para esclarecer que caso você obtenha um módulo com o diretório de linguagem chamado "portuguesebr" e o seu XOOPS usa "pt-br_utf8", basta alterar o nome do diretório para o mesmo do usado na sua instalação XOOPS. Observação: Não estou considerando a possibilidade dos arquivos estarem codificados em charsets diferentes.

02.7.5. Como já discutimos a função das constantes, sabemos que as constantes de idioma são definidas em um diretório próprio, que elas começam com um traço de chão, e queremos que nosso módulo tenha a capacidade de ser distribuido em várias línguas, vamos por a mão na massa e tornar nosso módulo multi idiomas. Vamos começar com o arquivo xoops_version.php, susbtituindo o nome, a descrição e a licença por constantes de idioma, que são os dados atuais do xoops_version que necessitariam e podem ser traduzidos, então o arquivo ficará assim:

02.7.5.1. Observamos que na variável "version" alteramos para 1.01, pois neste momento estamos implementando alterações no nosso módulo.

02.7.6. Agora que substituímos os valores por constantes, temos que definí-las, então dentro do diretório "modules/meumodulo/" criaremos a sub-diretório "language" e dentro deste criaremos os sub-diretórios "pt-br_utf8" e "english".

02.7.6.1. Criaremos um arquivo chamado "modinfo.php" dentro do diretório "modules/meumodulo/language/pt-br_utf8/" com os defines de idioma:

02.7.6.2. Agora criamos o mesmo arquivo, porém dentro do diretório "modules/meumodulo/language/english/" com os defines do idioma inglês:

02.7.6.3. Agora vamos ao nosso gerenciamento de módulos e veremos que já está indicando que devemos atualizar o módulo, ao atualizar, observamos que corre tudo bem. Outra marca que utilizamos para identificar esta alteração está no nome, antes o nome do módulo era apenas "Meu Módulo" agora é "Meu Módulo Xoops", apenas com a atualização o XOOPS não modifica o nome já registrado, para conferirmos que as constantes estão funcionando, vamos desinstalar o módulo e instalar novamente.

02.7.6.4. Agora criamos um arquivo chamado "main.php" dentro do diretório "modules/meumodulo/language/pt-br_utf8/" com os defines do idioma português para o index do módulo, e, depois repetimos para o idioma inglês:

02.7.6.5. Agora vamos ao nosso arquivo "index.php" para aplicar estas constantes:

02.7.6.6. Pronto, nosso módulo já pode falar inglês ou português.

02.7.7. Vamos agora entender um pouco do nome padronizado para as constantes:

02.7.7.1. Usamos o início _MI para "Module Information", ou seja, para quando lermos a constante saberemos que se trata de uma informação do módulo, _MD ou _MC para "Module Data" ou "Module Content", _MB para "Module Block", _AM para "Administration Module, e assim sucessivamente, sempre seguido pelo nome do módulo _MEUMODULO, e, depois pela identificação da função _NAME, etc.

02.7.7.2. Vejam que a sigla inicial é comum no XOOPS e toda a constante escrita em inglês, mas isso não obsta o programador a criar a constante da forma como ele quiser, porém dificultará a leitura e manutenção do código, bem como pode acabar criando um constante já existente e quando executar o módulo encontrar um conflito.

02.7.7.3. Todas as constantes de idioma para o xoops_version.php, ou seja, que tratem de informações do módulo e para o funcionamento do módulo ficam por padrão no arquivo modinfo.php, todas as constantes do conteúdo do módulo por padrão ficam no arquivo main.php, todas as constantes do consteúdo dos blocos ficam no arquivo blocks.php, e todas as constantes da administração do módulo ficam por padrão no arquivo admin.php, todos dentro do diretório "language/NomeDoIdioma/".

02.7.7.4. Estes arquivos são lidos automaticamente pelo XOOPS. Podemos também armazenar as constantes em outros arquivos caso achemos necessário, porém temos que chamar esses arquivos para dentro do script quando necessário.

02.8. Lembrem que as discussões e dúvidas estão no Fórum, no tópico Criando Módulos Xoops – 01: Constantes.