Desarrollo de un módulo

2009-03-21T12:04:23Z

Athomix:

Para crear un nuevo módulo hay distintas fases a seguir. Este tutorial tiene como meta describir cada una de estas fases con el fin de ayudar a comprender las posibilidades de Dolibarr, como por ejemplo añadir una o varias de las siguientes funcionalidades:
* Agregar nuevas tablas a la base de datos.
* Agregar tus propias entradas en los menús.
* Agregar pantallas de embargo/consulta de nuevas tablas.
* Añadir exportaciones predefinidas a la función “Exportar”.
* Agregar nuevas cajas a la página de inicio.
* Definir nuevos permisos.
* Activar código automático sobre una acción particular de Dolibarr.

etc. Todas estas operaciones sólo están disponibles a partir de la versión 2.4 de Dolibarr.

== Crear un descriptor de Módulo (obligatorio) ==
'''Cuándo''': Obligatorio cada vez que se desarrolla una extensión, cualquiera que sea su finalidad.

=== Crear tu descriptor ===
La primera fase es la de crear un fichero descriptor del módulo. Para ello, ve al directorio '''dev/skeletons''' y copia el fichero "modMyModule.class.php" en el directorio '''htdocs/includes/modules'''. A continuación, modifica el contenido de este fichero con el fin de reemplazar:
* los "modMyModule" por un valor que corresponda a la finalidad de tu módulo. Este valor debe siempre comenzar por mod.
* $this->numero = 10000 por un número de módulo que esté libre (Para saber qué números ya están siendo utilizados, vaya a la página "Inicio-> Info sistema-> Dolibarr-> Módulos")
* $this->const_name = 'MAIN_MODULE_MYMODULE' por $this->const_name = 'MAIN_MODULE_XXX', donde XXX se corresponde con el valor elegido para reemplazar MYMODULE. El valor elegido debe ir en mayúsculas.
* $dir = DOL_DOCUMENT_ROOT.'/mysql/tables/mymodule/'; por $dir = DOL_DOCUMENT_ROOT.'/mysql/tables/xxxxxxxx/'; donde xxxxxxxx representa el nombre de tu módulo (sin espacios).
* Modificar eventualmente otras variables definidas por los desarrolladores (ver el comentario en el código del esqueleto para ver su significado)

Ahora tu fichero descriptor está configurado.

=== Probar tu descriptor ===
Ejecuta Dolibarr y ve a la página "Configuration > Module". Debería aparecer una nueva línea con tu nuevo módulo y la posibilidad de activarlo o no (echa un vistazo a todas las pestañas de cada categoría para encontrarlo). Es el valor $this->special el que determina en qué pestaña se encuentra tu módulo.

== Crear tus tablas SQL y la clase PHP de los métodos de acceso1 (opcional) ==
'''Cuándo:''' Si tu módulo necesita gestionar sus propios datos.

===Crear tus ficheros .sql===
Si tu módulo de verdad requiere administrar datos que no existen en la base de datos en la versión estándar de Dolibarr, será necesario definir ciertas tablas SQL para registrar esos datos.

Los ficheros propios de tu módulo deben estar ubicados en un directorio localizable.

Crea un subdirectorio sql en el directorio de tu módulo (por ejemplo, htdocs/mimodulo/sql), con el fin de color los scripts sql que vas a crear. A continuación, en la función load_tables de tu fichero descriptor, modifica la línea

$dir = DOL_DOCUMENT_ROOT.'/mymodule/sql/';
por
$dir = DOL_DOCUMENT_ROOT.'/mimodulo/sql/';

''Regla a respetar:'' Agrega los ficheros de orden de creación de tus tablas al principio de un fichero por tabla (ver los ficheros existentes en ''mysql/tables'', por ejemplo). Los ficheros deben ser operativos para la base de datos mysql. Nota: No hace falta mantener los ficheros de las otras bases de datos. Son leídos y convertidos en tiempo real por el driver de la base de datos.

=== Probar tu fichero .sql ===
Una vez que los ficheros estén listos, puedes volver a Dolibarr para desactivar el módulo, eliminar las tablas de la base de datos y reactivar el módulo. Las tablas deben ser recreadas por la activación del módulo. Si no es así, verifica tus scripts o consulta los logs Dolibarr.

=== Generar la clase PHP de acceso ===
Una vez que tu/s tabla/s estén creadas en la base de datos, ve al directorio '''dev/skeletons''' y ejecuta el script
php build_class_from_table.php nombretabla
Nota: Si el comando no funciona, intenta con php-cli en lugar de php.

Esto genera un fichero '''out.nombretabla.class.php''' que contiene la clase de gestión de la tabla “nombretabla”. En esta clase se encuentran los métodos CRUD (Create/Read/Update/Delete) ya operativos para hacer un ''insert'', un ''fetch'' (''select''), un ''update'', y un ''delete'' de una línea de la tabla. Suprime justo el "out" del nombre del fichero y ponlo en un subdirectorio de '''htdocs''' propio en tu módulo (Por ejemplo en '''htdocs/mimodulo''').

Un fichero '''out.nombretabla_script.php''' se genera igualmente y contiene un ejemplo de código para utilizar la clase para cada uno de los cuatro métodos CRUD.

== Crear tus páginas pantalla PHP (opcional)==
'''Cuándo:''' Si tu módulo consiste en añadir funcionalidades que necesitan nuevas pantallas.

===Crear una página pantalla PHP===
Debes crear a continuación pantallas PHP que se basen en los datos de tus tablas utilizando los esqueletos como ejemplo del directorio '''dev/skeletons'''. (Para el desarrollo de un script en línea de comandos, ver [[Desarrollar script]]).

Para crear una nueva página de usuario, crea un subdirectorio de '''htdocs''' (si es que no existe ya) propio en tu módulo (En '''htdocs/mimodulo''', por ejemplo), con el fin de ubicar en él las páginas que vas a crear.

Copia allí el fichero '''skeletons_page.php''', que va a servir de punto de partida a tu pagina, y copia también el fichero '''pre.inc.php'''. Modifica el fichero '''pre.inc.php''' para que la ruta relativa de
include("../../main.inc.php)";

sea la correcta, en función de la profundidad del directorio en el que se encuentra el fichero pre.inc.php (quitando o añadiendo "../"). Es en el "main" donde se carga el entorno técnico y las habilitaciones. Los objetos variables se posicionan ahora:
* $user – El objeto que contiene las características del usuario y sus derechos.
* $conf – El objeto que contiene la configuración de Dolibarr.
* $db – El objeto que contiene el gestor de conexión abierto a la base de datos.
* $langs – El objeto que contiene el idioma del usuario.

A continuación, teclea tu código para archivar la página.

=== Acceso a la base de datos ===
Si necesitas realizar modificaciones en tu tabla de la base de datos, utiliza la clase generada más arriba.

Si de todos modos quieres acceder a las tablas sin objeto PHP dedicado, esto es posible (por ejemplo para recuperar una lista de registros). En ese caso, piensa en seguir estos ejemplos.

Para un ''insert'', ''update'' o ''delete'':
$db->begin(); // Debut transaction
$db->query("Ma requete insert, update ou delete");
$db->commit(); // Valide
o $db->rollback() // Annule

Para una lectura:
$resql=$db->query("Ma requete select");
if ($resql)
{
$num = $db->num_rows($resql);
$i = 0;
if ($num)
{
while ($i < $num)
{
$obj = $db->fetch_object($resql);
if ($obj)
{
// You can use here results
print $obj->field1;
print $obj->field2;
}
$i++;
}
}
}

=== Definición de estilos ===
Para que el aspecto de la página guarde coherencia con el tema Dolibarr, es necesario utilizar los estilos CSS de Dolibarr.

Por ejemplo:

* class="liste_titre"1 en las etiquetas tr y td para una línea de título de tabla.
* class=”pair” o class=”impair” en las etiquetas tr y td de las líneas de datos de la tabla.
* class=”flat” en todos los campos en los que se teclea (input, select, textarea...)
* class=”button” en los objetos de tipo input type=”submit”.

=== Utilizar el selector de datos de Dolibarr ===
Si quieres, puedes beneficiarte del selector de datos en las pantallas Dolibarr. Para ello, utiliza la siguiente línea:
$form=new Form($db);
print $form->select_date('','mykey',0,0,0,"myform");

La cadena "mikey" identifica el campo fecha. Hace falta introducir un valor diferente en caso de que haya varios campos. La cadena "myform" es el nombre del campo "FORM" (en el formulario, name="myform" de la página html). La visualización de un selector de fecha debe por tanto estar integrada en un formulario html.

Para recuperar el valor, a la herencia de POST, el comando es:
$datefacture = dolibarr_mktime(12, 0 , 0, $_POST['mykeymonth'], $_POST['mykeyday'], $_POST['mykeyyear']);
print strftime('%A %d %B %Y', $datefacture);

== Definir tu página de configuración (opcional) ==
'''Cuándo:''' Si tu módulo ofrece varias opciones parametrizables.

===Crear tu página de edición de configuración===
Si tu módulo ofrece varias opciones parametrizacles, es necesario crear una página PHP para editar las opciones (que serán guardadas en la tabla '''llx_const'''). Crea una página PHP llamada '''mimodulo_setuppage.php''', que registre las opciones posibles y las ponga al día. Es necesario tomar como ejemplo una página de '''/admin''' que te muestre el método para leer o guardar en la base de datos tu opción. Coloca esta página de configuración también en el directorio '''/admin'''. A continuación, en el descriptor del módulo, modifica la variable para indicar el nombre de esta página PHP (no es necesario modificar la ruta, ya que la página estará forzosamente en el directorio '''/admin''').
$this->config_page_url = array("monmodule_setupapage.php");

=== Probar tu página ===
Ve a la página '''Configuración > módulo'''. Debería aparecer un icono que permite acceder a la página de configuración, y deberías poder modificar estas opciones y verlas en la base de datos.

== Definir tus entradas de menú (opcional) ==
'''Cuándo:''' Si has creado páginas PHP, es necesario que estas pantallas sean accesibles desde el menú Dolibarr.

=== Definir tus entradas ===
Para ello, hace falta definir en el fichero descriptor de menú de tabla
$this->menu

Esta tabla contiene todas las entradas que aparecerán en los menús una vez que el módulo sea activado. Los ficheros de descriptor de módulo contienen un ejemplo de cómo se declara el menú superior, así como las entradas correspondientes en el menú de la derecha.

=== Probar tus entradas de menú ===
Desactiva y reactiva tu módulo bajo Dolibarr. Las entradas del menú deberían aparecer después de hacerlo.

== Definir tus propios permisos (opcional) ==
'''Cuándo:''' Si quieres añadir nuevos permisos.

La definición de permisos que gestionará tu módulo se hace en el fichero descriptor creado en la primera fase. Modifica la línea $this->rights_class = 'facture' para que diga:
$this->rights_class = 'mimodulo'

A continuación, rellena la tabla $this->rights con tantas entradas como permisos diferentes vayas a definir:
$this->rights[$r][0] = 10001;
$this->rights[$r][1] = 'Texto por defecto de mi permiso';
$this->rights[$r][3] = 1;
$this->rights[$r][4] = 'accion';
$this->rights[$r][5] = 'subaccion';
$r++;

En $this->rights[$r][0], introduce un id de permiso que no haya sido ocupado ya (para saber qué id están siendo ya utilizadas, ver el menú '''Información del Sistema''' en una instalación de Dolibarr que esté funcionando. En $this->rights[$r][3], introduce 1 si este permiso se atribuye por defecto a los usuarios según son creados. En $this->rights[$r][1] introduce un texto por defecto -que será mostrado si no se encuentra traducción para tu permiso en el fichero '''admin.lang'''). En $this->rights[$r][4] y $this->rights[$r][5], introduce una cadena de acción y subacción sin espacios. Después puedes probar si un usuario tiene los permisos bien, introduciendo la siguiente secuencia en el código PHP:
if ($user->rights->mimodulo->accion->subaccion) ...

== Definir tus propias cajas (opcional) ==
'''Cuándo:''' Si tu módulo tiene una o varias cajas.

=== Define tus cajas ===
Para ello, modifica las tablas $this->boxes del fichero descriptor de módulo. Es suficiente con añadir una línea por cada fichero de caja que se encuentre en el directorio '''htdocs/includes/boxes'''.

Ejemplo:
this->boxes[0][1]='mabox0.php'
this->boxes[1][1]='mabox1.php'
this->boxes[2][1]='mabox2.php'
...
this->boxes[n][1]='maboxn.php'

A continuación crea los ficheros mabox0.php, mabox1.php... tomando como ejemplo las cajas existentes (en el directorio htdocs/include/boxes)

=== Prueba tus cajas en Dolibarr ===
Ve al menú '''Bienvenida – Configuración – Caja'''. Tus cajas deben aparecer en la lista de cajas activables. Actívalas, ve a la página de bienvenida y verifica que se muestran correctamente.

== Definir tus propias exportaciones (opcional) ==
'''Cuándo:''' Si tu módulo incorpora exportaciones predefinidas de datos (tanto para sus propias tablas o para otras tablas existentes de otros módulos de Dolibarr)

=== Definir la exportación ===
Para ello, descomenta y modifica las tablas $this->export_xxx de tu fichero descriptor de módulo.

=== Probar la exportación ===
Ve al menú "Herramientas > Exportar" de Dolibarr. Tu exportación debería aparecer en la lista de exportaciones predefinidas disponibles (si tu módulo ha sido activado correctamente). Deberían aparecer, para que pudieras elegirlos, los campos que definiste en la fase anterior en las tablas correspondientes. Elige algunos campos y prueba a generar un fichero de exportación.

== Definir tus estilos CSS (opcional) ==
'''Cuándo:''' Si en tus pantallas PHP utilizas clases de estilos distintas a las de los temas de Dolibarr.
Esta funcionalidad todavía no es operativa en la versión 2.4., a pesar de estar ya descrita.

== Definir tus funciones Javascript (opcional) ==
Esta funcionalidad ya no existe.

== Ejecutar código sobre un evento Dolibarr (opcional)==
'''Cuándo:''' Si quieres que se ejecuten acciones particulares al activar ciertas acciones estandar de Dolibarr (por ejemplo, si deseáramos actualizar una tabla de mi módulo cada vez que se crea una factura en Dolibarr), hará falta crear un fichero '''disparador (triggers)'''.
Véase también [[Interfaces Dolibarr hacia el exterior]] e [[Interfaces Dolibarr hacia Dolibarr]]

== Crear un paquete para liberar e instalar tu módulo ==

* Ve al directorio '''/build''' y copia el fichero '''makepack-dolibarrmodules.conf''' como '''makepack-mimodulo.conf'''. Cuidado: este directorio puede no ser suministrado en los paquetes de versión estables. Si es el caso, puedes bajarte la última snapshot CVS en la sección de Downloads del sitio de Dolibarr con el nombre “Development Version”1 (toma en este caso todos los directorios que sean autónomos e independientes de la versión).

Teclea en este archivo la lista de nombres de los nuevos ficheros que has creado para tu módulo (descriptor de módulo, nuevos ficherossql de tablas, páginas php, imágenes, etc...)
* Lanza el script vía Perl (necesitas la versión 5.0. o superiores de Perl)
perl makepack-dolibarrmodule.pl

El script te pide el nombre de tu módulo, su versión más reciente y la más antigua. Se va a crear un fichero '''mimodulo.tgz''', que incluirá tu módulo listo para ser desplegado.
* La persona que reciba tu módulo deberá ubicar el fichero en el directorio raíz de Dolibarr y ejecutar el comando:
tar -xvf monmodule.tgz

== Algunas reglas de código ==
Las reglas de código a seguir se definen en la [[Documentación Desarrolladores| Documentación para desarrolladores]], concretamente en la sección "Lenguaje" del capítulo de "Información General".

Dolibarr ERP CRM Wiki - User contributions [en]

Desarrollo de un módulo