Juan Garcés

Personal Blog

Creación de Módulos XOOPS

junio 7th, 2013

Saludos Amigos usuarios de XOOPS.

Soy un usuario bastante antiguo de XOOPS, lo utilizo desde sus primeras versiones y me tiene gratamente sorprendido el trabajo que se ha realizado al desarrollar un CMS de estas características, por ello estas primeras líneas son para felicitar a todo el TEAM de desarrolladores de XOOPS.

Este pequeño tutorial espera orientar a todos aquellos que necesitan o quieran realizar un módulo para XOOPS. No es un manual, pues no conozco todos los por menores que XOOPS en su programación tiene, pero creo que ayudará a que muchos se 27atrevan a realizar sus propios módulos y así hacer crecer XOOPS.


Este tutorial lo estoy escribiendo mientras está vigente la versión 2.0.7 de XOOPS, por lo que algunas referencias en cuanto a números de líneas de código o nombres de archivos pueden variar.

Antes de comenzar recuerden lo siguiente: Si la primera vez no funciona, no desesperes, modifica el archivo /include/common.php y buscas al rededor de la línea 89 lo siguiente:

al poner el signo «=» en lugar de hacer la comparación con «==», realizará una asignación, por lo que siempre será verdadero, quedando error_reporting(E_ALL) activado. Esto te permitirá ver todos los errores que tenga la página que estes realizando.

Todo OK, ya estamos en condiciones para comenzar. Disfruta la lectura.

Estructura Básica

Todo módulo tiene una estructura básica de directorios y archivos. En la siguiente imagen se pueden apreciar:

directorio

admin:
contiene los archivos que sólo podrá ver quién
posea permisos de administración sobre el módulo.

-index.php: puede contener un menú o directamente
la administración del módulo.
-menu.php: contiene los links que aparecerán en el
ícono de administración, al pasar el mouse sobre él.
-administracion.php: puede ser el archivo de administración.
Su nombre puede ser distinto, sólo debe ser indicado en menu.php
con el nombre indicado.

blocks: contine los archivos que poseen los
posibles bloques que tenga el sistema.

-bloque.php: podrá tener el contenido del bloque que
posea el módulo.

class: si estas programando con orientación a objetos,
es conveniente que guardes dicho código en diferentes archivos
contenidos en esta carpeta. Luego para usar las clases creadas sólo
deberás incluir el archivo.

images: es la carpeta donde podrás almacenar
tus imágenes.

Generalmente, slogo.png es el ícono de administración.

include: en esta carpeta podrás guardar todos
aquellos archivos que contienen funciones que te permitirán
la implementación del módulo. Luego para usarlo sólo
deberás incluirlo en donde desees.

-search.inc.php: corresponde al archivo que contiene la
función de búsqueda del módulo y que será
utilizada por el buscador global que posee XOOPS.

language: esta carpeta contendrá las carpetas
de lenguajes que crees para el módulo. Es conveniente siempre
tener creada la carpeta english con sus archivos aunque no estén
bien traducidos, pues es el lenguaje original de XOOPS y tal vez
alguién más en el futuro los pueda traducir.

-admin.php: contiene el lenguaje que será incluido
para la administración. Si tu módulo no posee administración
no es necesario este archivo.

-blocks: contiene el lenguaje para los bloques si los haz
creado. En caso contrario no es necesario tener este archivo.

-main.php: contiene el lenguaje que será incluido
en la presentación al usuario del módulo. Si tu módulo
sólo posee administración, puedes omitir este archivo.

-modinfo.php: contiene el lenguaje que será utilizado
principalmente en la descripción del sistema. Sus constantes
serán incluídas en la creación del archivo
xoops_version.php.

sql: esta carpeta contiene los scripts sql que posea
el módulo. Así se incluye en esta carpeta el archivo
mysql.sql, que corresponde a los scripts de creación
de tablas e inserciones básicas para el servidor de bases
de datos MySQL, que hasta el momento es sobre el que se soporta
nuestro XOOPS.

templates: los templates son plantillas, HTML principalmente,
en las cuales se presentarán los datos que el módulo
entregue al usuario. El módulo puede tener o no templates,
todo depende de cómo el programador desee crear su módulo.
En caso de poseer templates, es conveniente poner nombres descriptivos,
por ejemplo, la página index.php posee el template
theme_index.html

Archivos
bases del Módulo:
aquí se encuentran los archivos
que permitirán instalar el módulo y enlazarlo con XOOPS.
Así, en header.php podremos incluir todos aquellos
archivos que requiera el módulo.
-index.php: este archivo entregará al usuario el acceso
a los datos que entregue el módulo. Si el módulo sólo
es para administración, puede omitir este archivo, caso en
el cual deberá incluir un archivo index.html que explicaremos
más adelante.
-xoops_version.php: es el archivo que contiene toda la información
referente al módulo. Siempre debe existir, pues sin él
el módulo no podrá ser instalado.

El archivo index.html que se include en prácticamente todas las carpetas es un archivo que generalmente está en blanco o con una instrucción que permite volver a la página anterior. Esto es para impedir que los usuarios naveguen libremente por los directorios de nuestro sitio con tan sólo modificar el URL y así no vean los archivos que podamos tener en ellos.

Todo módulo puede tener todas o alguna de las carpetas que se han detallado anteriormente, pero sin excepción, todo módulo deberá poseer su archivo xoops_version.php, pues en él se especifican las opciones del módulo, datos de su script sql, tablas, templates, etc.

El Archivo xoops_version.php

Ahora analicemos el archivo xoops_version.php. Para ello utilizaremos el código del mismo que se presenta en el siguiente cuadro de texto:

En este archivo hay muchas cosas que se pueden omitir y/o dejar como comentarios en caso de que quien construya el módulo no implemente alguna de ellas.

Es importante aclarar que todo lo que aparece en este archivo XOOPS lo procesa automáticamente, no debes programar una función especial para guardar las opciones de configuración por ejemplo. Es más, XOOPS provee de un formulario con las opciones que le indiquemos en $modversion[‘config’] y las actualizaremos sin programar una línea de código, pues XOOPS ya lo ha hecho por nosotros.

Creación del archivo de Administración «menu.php»

Este es el archivo que contiene el menú para la administración. Es el que aparece al pasar el mouse sobre el ícono de administración del módulo. La estructura de este archivo es la siguiente:

La variable $adminmenu es un arreglo asociativo que permite guardar los links para ser presentados en el menú de administración.

$adminmenu[1][‘title’] -> esta permite guardar el texto que aparece en el link.

$adminmenu[1][‘link’] -> esta permite guardar la página a que llevara el link.

Si el menú tiene varias opciones, sólo se debe aumentar el índice en el arreglo anterior, $adminmenu[1][‘link’].

Creación de un archivo de bloque

Los bloques pueden o no existir. No es raro encontrarnos con módulos que no poseen bloques. En el caso que lo requieras, puedes crear un bloque de la siguiente forma:

La variable $block es un arreglo asociativo que contendrá nuestro bloque.

Se pueden incluir etiquetas HTML y luego pasarlo a la variable como se indica en el ejemplo.

Puedes incluir consultas SQL si lo requieres. Luego XOOPS se encargará de mostrar tu bloque donde le indiques.

Creación de un archivo de Clases (class)

La creación de una clase en PHP es muy simple, sólo debes indicar la instrucción Class y seguir con el nombre de la clase. Para qué explicar más esto, quienes programan con Orientación a Objetos ya lo sabrán y no es mi intención aburrirles.

Creación de un archivo de Funciones

Esta clase de archivos es muy simple, sólo contienen funciones que tu requiera para implementar tu módulo, luego este archivo lo podrás incluir con la función include(«archivo»); Un ejemplo de este archivo puede ser:

Igualmente que en los demás archivos, puedes incluir consultas SQL y otras características que XOOPS ya posee. Más adelante explicaremos cómo puedes realizarlo.

Creación de los archivos de Lenguaje

Los archivos de lenguaje poseen el mismo nombre, ya sea para spanish o english o cualquier otro. Aquí te presento la estructura básica de estos archivos.

admin.php

main.php

blocks.php

modinfo.php

Estos archivos son muy simples, sólo debes cuidar el no repetir los nombres de las constantes (que están al lado izquierdo del define()), pués si lo haces el valor que le des se reemplazará.

Creación del Script SQL

El script SQL puede contener la creación de las tablas o inserciones básicas para el funcionamiento del módulo. Recuerda que pueden existir módulos que no requieran de la base de datos, en tal caso sólo pasa por alto este punto.

mysql.sql

Este es un script de ejemplo. Si no sabes el lenguaje SQL ni la sintaxis de MySQL, puedes usar PHPMyAdmin y su herramienta para creación de tablas. Una vez creada, puedes usar la opción de Exportación y así tendrás el código de la misma.

Creación de Templates

Si decides crear templates para mostrar los datos en tu módulo, puedes realizar las plantillas respectivas como en el ejemplo siguiente:

theme_index.html

Para crear templates XOOPS nos provee de varias etiquetas que nos permiten entre otras cosas recorrer un arreglo asociativo y tomar decisiones.

Así, <{foreach item=mimodulo from=$mimodulocont}> recorre el arreglo asociativo $mimodulocont y obtiene los valores en la variable mimodulo, sin el signo de «$». Luego para obtener el valor sólo accesas la variable $mimodulo. La variable $mimodulocont es la que debes llenar en el archivo al cual pertenece el template.

Otra etiqueta muy útil es:

<{if condicion}>
<{/if}>

XOOPS se encarga de reemplazar estas etiquetas por su representación en PHP.

Creación de archivos para Administración

Ya hemos realizado lo que es apoyo para la creación de nuestro módulo. Ahora veamos cómo se realiza un archivo para la administración de nuestro módulo.

Estos archivos poseen una estructura similar. Puedes usar la siguiente:

administracion.php

La estructura que ves en el cuadro de texto puedes usarla tal cual, sólo debes modificar la línea donde está getByDirname(«mimodulo«); y poner el nombre de tu módulo reemplazando las letras en rojo.

Las función xoops_cp_header(); es la encargada de generar desde la primera etiqueta hasta la tabla que contiene a tu módulo, luego de pones todo lo relativo a tu módulo, no incluya nuevamente las etiquetas u otras del encabezado. Puedes comenzar con una simple tabla.

Luego de poner todo lo relativo a tu módulo, pones la función xoops_cp_footer(); y ésta se encargará de realizar todo el cierre de la página hasta la etiqueta HTML.

No debes preocuparte por los permisos ni nada relativo a la seguridad, pues XOOPS reconoce tu módulo y aplica las restricciones relacionadas. Sólo debes preocuparte de que el archivo que estes escribiendo contenga el código que se indica en el ejemplo. Por supuesto puedes incluir otros archivos php que requieras, pero trata de hacerlo después de las primeras líneas para que sean validados los permisos y no se incluyan por error.

Creación de archivos para Presentación de Datos

Si tu módulo posee acceso para los usuarios normales y no sólo administración, que es lo más probable, debes realizar un archivo que te permita mostrar los datos. Un archivo de este tipo se ve como el siguiente:

index.php

Este es un archivo típico para mostrar información. Sólo debes incluir los archivos mainfile.php y header.php. Ellos son los encargados de analizar tu módulo y permitir el acceso a quienes se los hayas permitido.

header.php realizará toda la página hasta antes del contenidod e tu módulo, o sea, crea el inicio de la página y los bloques de la izquierda.

footer.php crea los bloques de la derecha y el cierre de la página.

La sóla inclusión de estos archivos es suficiente, no debes llamar a ninguna función especial.

La función de Búsqueda

El archivo search.inc.php es el que contiene la función de búsqueda de tu módulo y que será utilizada por el buscador global que XOOPS posee. La estructura de éste es:

serach.inc.php

Si tu módulo no posee un buscador, sólo debes indicarlo en el archivo xoops_version.php y hacer la variable $modversion[‘hasSearch’] igual a 0.

Generalidades

Trabajo con la Base de Datos

$xoopsDB => es la variable para uso de la base de datos. Para usarla sólo debes poner global $xoopsDB antes de usarla en tus archivos.. Sus funciones principales son:

$xoops->query(«tu consulta sql»); => esta función te permite enviar consultas SQL a la base de datos y te retorna el resultado de la consulta.

$xoops->fetchRow($resultado); => esta función te permite obtener la siguiente fila del resultado obtenido en el query.

$xoops->fetchArray($resultado); => esta función te permite obtener la siguiente fila del resultado obtenido en el query, pero como un arreglo asociativo.
Constantes Globales

XOOPS_ROOT_PATH => esta constante contiene el path donde se encuantra tu sitio.

XOOPS_URL => esta constante contiene el URL de tu sitio.

Por supuesto XOOPS posee muchas otras funciones y clases, pero si las requieres puedes consultar los archivos en /class o en /include.

Bajar Archivos

Aquí dejo para ustedes los archivos básicos para la creación de un módulo simple, sin bloques, sin clases y sin templates.

Módulo Ejemplo

Si deseas guardar una copia de este tutorial dejo aquí para tí el link para descargarlo:

Tutorial Completo

Consultas y aportes

Si tienes algún aporte o si existe alguna inconsistencia o error en el tutorial me puedes escribir a jgarces@jgarces.info y con gusto recibiré tu sugerencia.

Consultas y otras sugerencias puedes realizarlas en http://www.jgarces.info

Juan Garcés

Personal Blog