Creación de Módulos para XOOPS
Autor
Juan Garcés Bustamante
www.educacioninformatica.com
Introducción
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 atrevan 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:
error_reporting(0);
if ($xoopsConfig['debug_mode'] == 1) {
y lo reemplazas con:
error_reporting(E_ALL);
} else {
// Turn off error handler
$xoopsErrorHandler->activate(false);
}
error_reporting(0);
if ($xoopsConfig['debug_mode'] = 1) {
error_reporting(E_ALL);
} else {
// Turn off error handler
$xoopsErrorHandler->activate(false);
}
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:
 |
admin:
contiene los archivos que sólo podrá ver quién
posea permisos de administración sobre el módulo. |
|
blocks: contine los archivos que poseen los
posibles bloques que tenga el sistema. |
|
|
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. |
|
|
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.
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.
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:
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:
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 <HTML> hasta la tabla que contiene a tu módulo, luego de pones todo lo relativo a tu módulo, no incluya nuevamente las etiquetas <HTML> 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:
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:
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.
Si deseas guardar una copia de este tutorial dejo aquí para tí el link para descargarlo:
Consultas y aportes
Si tienes algún aporte o si existe alguna inconsistencia o error en el tutorial me puedes escribir a wmaster@educacioninformatica.com y con gusto recibiré tu sugerencia.
Consultas y otras sugerencias puedes realizarlas en http://www.educacioninformatica.com