Adaptando Módulos Xoops a EXM System

A pesar de que EXM System desciende directamente de XOOPS es necesario recordar que EXM no es XOOPS por lo que la compatibilidad con módulos existentes será limitada en gran medida por factores relacionados con la implementación de clases y otros aspectos en ambos sistemas.

Para facilitar la conversión de módulos XOOPS a EXM System hemos decidio mantener nombres de variables y constantes básicas intactas, des esta manera el trabajo será menor y los desarrolladores de módulos se sentirán mas familiarizados con la forma de trabajar en EXM System.

Importante: Para poder realizar conversiones de módulos XOOPS a EXM System es necesario contar con conocimientos PHP y HTML.

Otra de los cambios importantes desde XOOPS es la modificación de varias clases y funciones y por supuesto el reemplazo de XoopsForm por RMForm lo que significa que para adaptar módulos existentes es necesario considerar el cambio en varias funciones y clases.

En este documento trataremos de cubrir todos los aspectos de la conversión de módulos de Xoops a EXM System, sin embargo por la naturaleza de dicha actividad probablemente algunos aspectos podrían ser omitidos u olvidados por lo que ponemos a su disposión nuestros foros para cualquier duda que surja.

Algo a tener en cuenta es que este documento trata sobre los aspectos generales de la conversión de módulos con ejemplos prácticos, pero dada la naturaleza diferente de cada módulo, será responsabilidad tuya la forma en que esta información sea aplicada para realizar las adaptaciones. Es decir, nosotros te ofrecemos el conocimiento y tu lo aplicas.

Como primer paso para la adaptación de módulos es necesario modificar el archivo xoops_version.php orginal del módulo ya que la forma en que EXM System maneja este archivo difiere de la forma en que lo hace Xoops. Podrás encontrar na guía completa sobre el archivo xoops_version.php en nuestra sección de coumentación.

El mayor trabajo de conversión de un módulo será realizado en la sección administrativa ya que es aqui donde los módulos han perdido compatibilidad, en gran medida debido a la modificación de las funciones existentes y a la inclusión de funciones que facilitan el trabajo en el desarrollo de nuevos módulos, y ppor supuesto no debemos olvidar el hecho de que ahora Smarty esta disponible también en el panel de control de EXM System lo que te permitirá manejar plantillas para el panel de control del módulo y así evitar incluir etiquetas HTML dentro del código PHP.

Para empezar hablaremos un poco de las funciones que se han modificado y las que se han agregado en el panel de control de EXM System en comparación con el panel de control de XOOPS. Esta información será muy útil al momento de adaptar módulos o desarrollar nuevos.

La variable $db sustituye a la antigua variable $xoopsDB en el panel de control. Esta variable esta disponible en todo el panel de control de EXM System y en la sección frontal. Para usarla dentro de funciones es necesario declararla globalmente.

PHP Code:

function function_name($params){
    global $db;
    ...
}

Esta variable almacena una referencia a la clase RMUtils que te permite relizar múltiples operaciones para facilitarte el trabajo de desarrollo. Esta variable debe ser declarada como global al utilizarla en una función.

La variable $tpl contiene una referencia a la clase XoopsTpl que a su vez permite utilizar las capacidades de Smarty por lo que el uso de esta variable es similar al uso de $xoopsTpl que no esta disponible en el panel de control.

PHP Code:

// Ejemplo de Uso:
$tpl->assign("var_name", $value);

La variable $adminTemplate debe contener la plantilla que EXM System mostrará automáticamente en la sección administrativa del módulo. Esta variable será utilizada cuando se llame a la función xoops_cp_footer(). $adminTemplate debe contener el nombre de una plantilla almacenada en la base de datos del mismo modo que $xoopsOption["template_main"] guarda el nombre de la plantilla que se muestra en la sección frontal o bien, puede especificar la ruta a la plantilla relativa al directorio del módulo.

Es muy importante que $adminTemplate sea declarada como global cuando se utiliza dentro de funciones.

PHP Code:

global $adminTemplate;
$adminTemplate = "template_name.html";
 
// O usando una ruta relativa:
$adminTemplate = "templates/template_name.html";

Además, en EXM System están disponibles las variables normales utilizadas en XOOPS como $xoopsConfig, $xoopsModuleConfig, $xoopsModule, etc.

En EXM System están disponibles la mayoría de las funciones que existían en XOOPS pero muchas de ellas han sido modificadas y por supuesto, se han agregado otras nuevas.

Esta función permite establecer la barra de localización del panel de control para ayudar al usuario a desplazarse rápidamente por nuestro módulo. Además modifica el título de la ventana.

El parámetro que recibe esta función debe ser una cadena que puede contener enlaces para ayudar al usuario (haciendo click) a desplazarse por el módulo.

PHP Code:

xoops_cp_location("<a href='#'>".$xoopsModule->name()."</a> » Your_Location");

Esto presentará algo como: Nombre del Módulo » Your_Location tanto en la barra de localización como en el título de la ventana.

En realidad no se trata de una función, sin embargo es muy importante mencionarlo pues es una característica muy provechosa la capacidad de EXM System para mostrar una barra de menú personalziada para el panel de control del módulo. No hay que confundir el menú estándar del módulo con la barra de menus: La barra de menus es personalizable para cada sección de la administración de tu módulo.

La barra de menus se crea mediante el método append de Smarty y con la variable "xoopsOptions" de la manera que se muestra:

PHP Code:

$tpl->append('xoopsOptions', array('link'=>'./page.php', 'title'=>_LANG_CONSTANT, 'icon'=>'../path/to/icon.xxx', 'alt'=>'text to display on mouse over', 'target'=>'target frame'));

Los valores que se pueden especificar son:

• link. Enlace que se seguirá al hacer click en el menu.
• title. Texto para el menú.
• icon. Icono que mostrará el menú. Las medidas de este icono deben ser 16 x 16 pix.
• alt (opcional). Texto que se mostrará al pasar el ratón por sobre el menu.
• target (opcional). Indica al frame objetivo para el enlace. Por defecto es _self.

Lo mas indicado para el manejo de la barra de menus es crear una función para su creación, de esa manera nuestro código es mas eficiente.

En EXM System, la función xoops_cp_header tiene la misma función que en XOOPS, sin embargo ahora acepta un parámetro que permite establecer contenido para la sección HEAD de nuestro documento HTML del panel de control, del mismo modo que funciona 'xoops_module_header' en los temas.

Este parámetro debe ser una cadena de texto y puede servir para la inclusión de cualquier etiqueta válida en la sección HEAD.

PHP Code:

xoops_cp_header('<style type="text/css" href="path/to/style.css" media="all" />');

La función xoops_cp_footer() es identica en su uso por lo que solo es necesario llamarla. La forma correcta es llamarla después de haber llamado a xoops_cp_header().

PHP Code:

xoops_cp_header();
.... // Some content
xoops_cp_footer();

Esta función es un reemplazo para la función redirect_header() en el panel de administración de EXM System. El mérito de esta función es eliminar la pantalla de redirección ye el tiempo de espera. En lugar de eso muestra un mensaje inemdiatamente después de redirigir al usuario.

PHP Code:

redirectMsg($url, $msg=', $level);

El parámetro $url indica la dirección a la que será redirigido el usuario, $msg es el texto que se mostrará y $level puede ser 0 o 1 siendo 0 un mensaje informativo y 1 un mensaje de advertencia.

Esta función formatea un valor númerico a Kilobytes, Megabytes, etc. dependiendo del parámetro size que debe ser un valor indicado en bytes.

Code:

formatBytesSize(1048576);
// Retornará 1 MB

Muestra un mensaje de la misma manera que redirectMsg() pero sin redirigir al usuario.

PHP Code:

showMsg($msg, $level);

Uno de los cambios de EXM System, gracias al uso de PHP 5, es que en la gran mayoría de los casos no es necesario incluir los archivos que contienen nuestras clases en los módulos o de EXM System.

EXM System intentará cargar automáticamente las clases buscandolas en el directorio "class" de nuestro módulo, en el directorio "class" de EXM System, en el directorio "kernel" o en el directorio " rmcommon".

De modo que cuando llamamos, por ejemplo, a RMForm, EXM System intentará buscar en estos directorios el archivo "rmform.php" o "rmform.class.php" y si lo encuentra lo incluirá automáticamente y nuestra clase estará disponible, sin embargo, cuando los nombres de archivos no coincidan será necesario incluir el archivo explicitamente.

En EXM System la clase XoopsObject ha sido reemplazada por la clase EXMObject que ofrece una mayor funcionalidad que su predecesora.

La clase EXMObject contiene varios métodos que facilitan el manejo de los datos de un objeto, sobre todo si este se basa en una tabla de la base de datos por lo que es muy recomendable utilizarla. Sin embargo la clase XoopsObject esta disponible pero hereda todos los métodos y propiedades de EXMObject por lo que una clase que herede de XoopsObject lo hará también de EXMObject.

A continuación se presenta un ejemplo de sus funcionalidades:

PHP Code:

// Ejemplo de su uso en un objeto
class MyObject extends EXMObject{
 
	function __construct(){
		// Incializa la base de datos
		$this->db =& Database::getInstance();
		// Establece la tabla para el objeto
		$this->_dbtable = $this->db->prefix("mytable"); 
		// Establece un objeto como nuevo
		$this->setNew();
		// Inicializa las variables automáticamente desde la tabla
		$this->initVarsFromTable();
		// Asigna los valores a las variables desde la tabla
		if ($this->loadValues($id)){
			$this->unsetNew();
		}
	}
}

En EXM System cuentas con la clase RMForm a diferencia de Xoops que cuenta con XoopsForm y, si bien estas dos clases son muy parecidas, RMForm contiene métodos que no la hacen compatible al 100% con XoopsForm, además los elementos de formulario difieren aún mas de los elementos existentes en Xoops por lo que es necesario una reescritura del código que utilice XoopsForm.

RMForm ofrece muchas ventajas frente a XoopsForm incluyendo el gran número de campos de formulario con los que cuenta que son fáciles de utilizar y ofrecen una mejor funcionalidad que sus equivalentes (si existen) en Xoops.

Para mayor información sobre las propiedades y los elementos disponibles para los formularios te invitamos a leer la información sobre RMForm en Red México.

Esta guía estará en constante modificación de acuerdo a sus comentarios ya que estos nos permitirán mejorarla para ayudarles en su trabajo de adaptación de módulos Xoops a EXM System.

Además de esta información recuerda que nuestros foros están disponibles para cualqueir consulta o para solicitar ayuda acerca de estos temas.

Foro de ayuda para adaptar módulos a EXM System.

1. ↑ EXM System es compatible con PHP5 (PHP 5.2 o mayor).
2. ↑ En Red México hemos publicado la documentación de RMForm para desarrolladores.
3. ↑ El menejo de plantillas Smarty dentro del panel de control de los módulos permite generar código mas limpio, legible y por lo tanto mantenible.
4. ↑ $xoopsDB también esta disponible en el panel de control pero se recomienda el uso de $db pues en el futuro esta variable podría ser removida permanentemente.
5. ↑ $xoopsTpl aún esta disponible en la sección frontal del sitio pero se recomienda el uso de $tpl
6. ↑ El menu del módulo se especifica en el archivo xoops_version.php.
7. ↑ En Red México hemos publicado la documentación de RMForm para desarrolladores.
8. ↑ En Red México hemos publicado la documentación de RMForm para desarrolladores.