Desarrollo de un módulo: Difference between revisions

{{TemplateDocDesarrollo}}

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:

etc.

Los capítulos siguientes describen las acciones a realizar para crear un módulo Dolibarr. Los primeros capítulos son obligatorios cualquiera que sea la vocación de los módulos, los siguientes dependerán de lo que deba hacer el módulo

'''Cuándo''': Obligatorio cada vez que se desarrolla una extensión, cualquiera que sea su finalidad.

La primera fase es la de crear un fichero descriptor del módulo. Para ello:

A continuación, modificar el contenido del archivo, reemplazando:

ATENCIÓN: El MiModulo debe estar compuesto por una serie de caracteres, siendo los únicos permitidos [A-Za-z_] con longuitud max de MyModule de 12 caracteres.

Ahora su fichero descriptor está configurado.

Ejecute Dolibarr y vaya a la página "Configuración > Módulo". Debería aparecer una nueva línea con su nuevo módulo y la posibilidad de activarlo o no (eche 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 su módulo.

Crear un directorio 'mimodulo' que contendrá los archivos del módulo. Este directorio debe de estar en el directorio '''htdocs''' y contendrá los siguientes subdirectorios:

{{TemplateModuleTreeSimple}}

'''Cuándo:''' Si su módulo necesita gestionar sus propios datos.

Revisa que en el descriptor de archivo (mymodule/core/modules/mymodule.class.php) la línea

$this->_load_tables('/mymodule/sql/');

esté descomentada y correctamente configurada.

''Regla a respetar:''  

Ejemplo de contenido de un fichero data.sql

  delete from llx_const where name='MYMODULE_IT_WORKS' and entity='__ENTITY__';

  insert into llx_const (name, value, type, note, visible, entity) values ('MYMODULE_IT_WORKS','1','chaine','A constant vor my module',1,'__ENTITY__');

Las órdenes SQL de los archivos deben de ser operacionales para la base de datos '''mysql'''.

Nota: Los archivos de otras bases de datos no se mantienen. Se leen y se convierten al vuelo por el driver de la base de datos.

Una vez que los archivos estén listos, puede 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í, verifique sus scripts o consulte los logs Dolibarr.

Una vez que sus tablas estén creadas en la base de datos, vaya al directorio '''dev/skeletons''', copie el archivo '''build_class_from_table.php''' en el directorio sql/ de su módulo module, y ejecute el script

  php build_class_from_table.php nombretabla

Nota: Si el comando no funciona, intente con php-cli en lugar de php.

Un archivo '''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.

'''Cuándo''' : Para añadir su propia pestaña en las pestañas estándar de una ficha entidad (factura, pedido, presupuesto, miembro...)

Para ello, vaya al archivo descriptor del módulo creado anteriormente y modifique la tabla $this->tabs:

// Array to add new pages in new tabs or remove existing one

$this->tabs = array('objecttype:+tabname1:Title1:@mymodule:/mymodule/mynewtab1.php?id=__ID__',  // To add a new tab identified by code tabname1

                             'objecttype:+tabname2:Title2:@mymodule:/mymodule/mynewtab2.php?id=__ID__',  // To add another new tab identified by code tabname2

                             'objecttype:-tabname');                                                    // To remove an existing tab identified by code tabname

La tabla debe contener una lista de cadena, cada cadena representa una nueva pestaña.

El formato de la cadena se compone de 4 partes separadas por ":"

{{TemplateModuleTabs-es}}

Para alimentar el contenido de la pestaña con los datos de la base de datos, vea el capítulo siguiente.

'''Cuándo''' : Para mostrar las pestañas estándar de ficha entidad (producto, tercero, etc.) en su propia pestaña de una entidad.

Para cada ficha entidad, hay que incluir dos archivos con la instrucción

Aquí le mostramos la lista de estos archivos (DOL_DOCUMENT_ROOT correspondiente al directorio '''dolibarr/htdocs/''') :

'''2. Crear y cargar el objeto a mostrar en su pestaña'''

''Ejemplo :''

$id=$_GET["id"];

$product = new Product($db) ;

$result = $product->fetch($id) ; //Tester $result pour vérifier que l'accès à la base s'est bien passé

'''3. Recuperar la lista de pestañas correspondientes a la entidad seleccionada'''

La tabla devuelta se compone de la siguiente manera :

$head        // Tableau des onglets

$head[$h]    // Élément décrivant un onglet. Il y aura autant de $h que d'onglets à afficher

$head[$h][1] // Titre de l'ongLet

$head[$h][2] // Code de l'onglet, à utiliser pour choisir quel onglet sera 'actif' (voir paragraphe suivant)

''Ejemplo :''

$head = product_prepare_head($product, $user) ; //le paramètre $user n'est pas présent sur certaines fonctions

'''4. Mostrar las pestañas en su pestaña'''

Use la función dol_fiche_head() que muestra las pestañas contenidas en la tabla $head devuelta por XX_prepare_head().

dol_fiche_head($links, $active='0', $title='', $notab=0, $picto='')

$links  // Tableau des onglets, appelé $head plus haut.

//            service

//            company

Esta función muestra las pestañas deseadas y abre un elemento ''< div class="" >'' que corresponde a la zona azul bajo las pestañas (si el parámetro $notab = 0). Para cerrar la zona azul, simplemente cierre el elemento ''< /div >'' en el código PHP.

Para más detalles, consulte la [http://www.dolibarr.fr/doxygen/ documentación Doxygen] o directamente el código de Dolibarr.

'''Cuándo:''' Si su módulo consiste en añadir funcionalidades que necesitan nuevas pantallas.

Debe crear a continuación pantallas PHP que se basen en los datos de sus tablas utilizando los esqueletos como ejemplo del directorio '''modulebuilder'''. (Para el desarrollo de un script en línea de comandos, ver [[Desarrollo de scripts]]).

Copie allí el archivo '''myobject_page.php''', que va a servir de punto de partida a su página. Modifique el archivo para que la ruta relativa de

// Load Dolibarr environment

$res=0;

if (! $res && file_exists("../../../main.inc.php")) $res=@include("../../../main.inc.php");

if (! $res) die("Include of main fails");

sea la correcta, en función de la profundidad del directorio en el que se encuentra el archivo (quitando o añadiendo "../"). Es en el "main" donde se carga el entorno técnico y las habilitaciones. Los objetos variables se posicionan ahora:

''Ejemplo :''

dol_include_once('/mimodulo/class/miclass.class.php', 'MiClass');

''Ejemplo :''

require_once DOL_DOCUMENT_ROOT.'/core/class/doli.class.php';

Si necesita realizar modificaciones en su tabla de la base de datos, utilice la clase generada más arriba.

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)

         }

  }

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

Por ejemplo:

Si quiere, puede beneficiarse del selector de fechas en las pantallas Dolibarr. Para ello, utilice la siguiente línea:

  $form=new Form($db);

  $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:

  $mydate = dol_mktime(12, 0 , 0, $_POST['mykeymonth'], $_POST['mykeyday'], $_POST['mykeyyear']);

  print strftime('%A %d %B %Y', $mydate);

'''Cuándo:''' Si su módulo ofrece varias opciones parametrizables.

Si su módulo ofrece varias opciones parametrizables, es necesario crear una página PHP para editar las opciones (que serán guardadas en la [[Table llx_const|tabla '''llx_const''']]). Cree 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 le muestre el método para leer o guardar en la base de datos su opción. Coloque esta página de configuración también en el directorio '''/admin'''. A continuación, en el descriptor del módulo, modifique 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_setuppage.php");

Vaya 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ía poder modificar estas opciones y verlas en la base de datos.

'''Cuándo:''' Si ha creado páginas PHP, es necesario que estas pantallas sean accesibles desde el menú Dolibarr.

Para ello, hace falta definir en el archivo descriptor de menú de tabla this->menu, que declara los menús.

Esta tabla contiene todas las entradas que aparecerán en los menús una vez que el módulo sea activado. Los archivos 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

He aquí un ejemplo de declaración de entradas de menú en el fichero descriptor:

// Main menu entries

$this->menu = array(); // List of menus to add

'user'=>2); // 0=Menu for internal users,1=external users, 2=both

$r++;

Para condicionar el acceso al menú segun los permisos, modificar la propiedad '''perms''' de la tabla. Ver el capítulo sobre permisos, un poco más abajo, para saber como realizar los permisos.

Desactive y reactive su módulo bajo Dolibarr. Las entradas del menú deberían aparecer después de hacerlo (si la condición 'enabled' está activada).

'''Cuándo:''' Si quiere añadir nuevos permisos.

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

  $this->rights_class = 'mimodulo';

A continuación, rellene la tabla $this->rights con tantas entradas como permisos diferentes vaya a definir:

  $this->rights[$r][0] = 10001;

  $this->rights[$r][1] = 'Texto por defecto de mi permiso';

  $this->rights[$r][5] = 'subaccion';

  $r++;

En $this->rights[$r][0], introduzca 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], introduzca 1 si este permiso se atribuye por defecto a los usuarios según son creados. En $this->rights[$r][1] introduzca un texto por defecto -que será mostrado si no se encuentra traducción para su permiso en el archivo '''admin.lang'''). En $this->rights[$r][4] y $this->rights[$r][5], introduzca una cadena de acción y subacción sin espacios. Después puede probar si un usuario tiene los permisos bien, introduciendo la siguiente secuencia en el código PHP:

  if ($user->rights->mimodulo->accion->subaccion) ...

'''Cuándo:''' Si su módulo tiene uno o varios paneles.

Para ello, modifique las tablas $this->boxes del archivo descriptor de módulo. Es suficiente con añadir 2 líneas por cada archivo de panel que se encuentre en el directorio '''htdocs/mimodulo/core/boxes'''.

Ejemplo:

$this->boxes[0]['file']='mabox0.php@mimodulo'

$this->boxes[0]['note']='Mi panel 0'

$this->boxes[n]['file']='maboxn.php@mimodulo'

$this->boxes[n]['note']='Mi panel n'

A continuación cree los archivos '''htdocs/mimodulo/core/boxes/mabox0.php''', '''htdocs/mimodulo/core/boxes/mabox1.php'''...  tomando como ejemplo los paneles existentes (en el directorio htdocs/core/boxes)

Vaya al menú '''Inico – Configuración – Paneles'''. Sus paneles deben aparecer en la lista de paneles activables. Actívelos, vaya a la página de bienvenida y verifique que se muestran correctamente.

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

Para ello, descomente y modifique las tablas $this->export_xxx  de su archivo descriptor de módulo.

Vaya al menú "Herramientas > Exportar" de Dolibarr. Su exportación debería aparecer en la lista de exportaciones predefinidas disponibles (si su módulo ha sido activado correctamente). Deberían aparecer, para que pudiera elegirlos, los campos que definió en la fase anterior en las tablas correspondientes. Seleccione algunos campos y pruebe a generar un archivo de exportación.

'''Cuándo:''' Si en sus pantallas PHP utiliza clases de estilos distintas a las de los temas de Dolibarr (no recomendado).

Esta funcionalidad todavía no es operativa en la versión 2.4., a pesar de estar ya descrita.

Crear un archivo de estilos llamada '''mimodulo.css''' o '''mimodule.css.php''' y guardarla en el directorio '''''mimodulo''''' dentro de '''htdocs'''. Solo puede haber un archivo css propio a cada módulo.

Recordamos que es mejor usar los estilos ya existentes en Dolibarr (el archivo css usado por Dolibarr es el archivo '''themes/nomtheme/''nombretema''.css.php'''.  

El valor a indicar debe ser la ruta URL relativa de su archivo css.

Por ejemplo

$this->module_parts = array('css' => array('/mimodulo/css/mimodulo.css.php'));

Desactivar y reactivar su módulo.

Debería ver en el encabezado HTML, una línea de declaración de su hoja de estilos.

'''Cuando''': Si en sus pantallas en PHP utiliza funciones de Javascript no disponibles en estandard (archivo lib_head.js)

Ejemplo para la página /htdocs/mimodulo/mapage.php :

require('../main.inc.php');

$morejs=array("/mimomulo/js/monmodule.js");

llxHeader('','Titulo','','','','',$morejs,'',0,0);  

'''Cuándo:''' Si quiere 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 archivo '''disparador (triggers)'''.

Véase también [[Interfaces Dolibarr hacia el exterior]] e [[Interfaces del Exterior hacia Dolibarr]]

'''Cuándo''': Cuando desee cambiar o añadir otro tipo de código en un evento de negociado (véase lel capítulo anterior para esto).

Véase la página [[El sistema Hooks]].

'''Cuándo''': Si quiere añadir una regla de numeración no cubierta por los módulos por defecto.

Véase la página [[Crear un módulo de numeración]].

'''Cuándo''': Si quiere añadir un nuevo modelo de documento.

La documentación relativa a la generación de documentos desde los modelos se encuentra disponible en la página [[Crear un modelo de documento PDF]] o [[Crear un modelo de documento ODT]].

'''Cuándo''': Si quiere un interface con colores personalizados.

Véase la página [[Temas]].

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".

Este proceso debe ser usado para fabricar un paquete con el fin de enviarlo a la tienda oficial http://www.dolistore.com.

También puede usarlo para distribuir fácilmente su módulo vía su propio método de distribución.

Teclee en este archivo la lista de nombres de los nuevos archivos que ha creado para su módulo (descriptor de módulo, nuevos ficheros sql de tablas, páginas php, imágenes, etc...)

  perl makepack-dolibarrmodule.pl

El script le pide el nombre de su módulo, su versión mayor y menor. Se va a crear un fichero '''mimodulo.zip''', que incluirá su módulo listo para ser liberado.

  tar -xvf monmodule.zip