1. No category

DESARROLLO DE UN
MÓDULO PARA DOLIBARR
+3.2
INDICE DEL CONTENIDO
INTRODUCCIÓN ............................................................................................ 5
INTRODUCCIÓN ............................................................................. 5
CREAR UN DESCRIPTOR DE MÓDULO (OBLIGATORIO) ................................. 5
CREAR UN DESCRIPTOR DE MÓDULO.............................................. 5
CREAR SU DESCRIPTOR .................................................................. 6
PROBAR SU DESCRIPTOR ................................................................ 6
ARBOL DE UN MÓDULO ................................................................................. 7
ESTRUCTURA DE ARBOL DE UN MÓDULO ........................................ 7
CREAR TABLAS SQL Y LA CLASE PHP CON MÉTODOS DE ACCESO (OPCIONAL)
..................................................................................................................... 7
CREAR FICHEROS .SQL ................................................................... 8
PROBAR EL ARCHIVO .SQL ............................................................. 9
GENERAR LA CLASE PHP DE ACCESO (DAO) ................................. 10
VISUALIZACIÓN DE PESTAÑAS (OPCIONAL) .............................................. 10
AÑADIR O ELIMINAR PESTAÑAS EN LAS FICHAS ENTIDAD .......... 10
AÑADIR PESTAÑAS DE UNA FICHA ENTIDAD EN SU PROPIA
PÁGINA ........................................................................................ 13
CREAR PÁGINA PANTALLA PHP (OPCIONAL) .............................................. 16
CREAR UNA PÁGINA PANTALLA PHP ............................................ 16
REEMPLAZAR PARTES DE TEMPLATES DE PANTALLA (VERSIÓN
3.3+)............................................................................................ 17
ACCESO A LA BASE DE DATOS ...................................................... 18
DEFINICIÓN DE ESTILOS ............................................................. 20
UTILIZAR EL SELECTOR DE FECHAS DE DOLIBARR ....................... 21
DESARROLLO DE UN MÓDULO PARA DOLIBARR +3.2
2
DEFINIR LA PÁGINA DE CONFIGURACIÓN (OPCIONAL) ............................. 21
CREAR PÁGINA DE EDICIÓN DE CONFIGURACIÓN........................ 21
PROBAR LA PÁGINA ..................................................................... 22
DEFINIR ENTRADAS DE MENÚ (OPCIONAL) ................................................ 22
DEFINIR ENTRADAS DE MENÚ ...................................................... 22
PROBAR ENTRADAS DE MENÚ ...................................................... 25
DEFINIR PROPIOS PERMISOS (OPCIONAL) ................................................ 25
DEFINIR PROPIOS PERMISOS ...................................................... 25
DEFINIR PROPIOS PANELES (OPCIONAL) .................................................. 26
DEFINIR PROPIOS PANELES......................................................... 26
PROBAR LOS PANELES ................................................................. 27
DEFINIR LAS EXPORTACIONES (OPCIONALES) .......................................... 27
DEFINIR LA EXPORTACIÓN .......................................................... 27
PROBAR LA EXPORTACIÓN ........................................................... 28
DEFINIR ESTILOS CSS (OPCIONAL) ........................................................... 28
CREAR Y DECLARAR LA HOJA DE ESTILOS .................................... 28
PROBAR LA HOJA DE ESTILOS ...................................................... 29
DEFINIR FUNCIONES JAVASCRIPT (OPCIONAL) ......................................... 29
DEFINIR FUNCIONES JAVASCRIPT ............................................... 29
EJECUTAR CÓDIGO SOBRE UN EVENTO DOLIBARR (OPCIONAL) ................. 29
EJECUTAR CÓDIGO SOBRE UN EVENTO DOLIBARR ....................... 29
EJECUTAR CÓDIGO USANDO HOOKS EN DOLIBARR .................................... 33
EJECUTAR CÓDIGO USANDO HOOKS EN DOLIBARR ...................... 33
AÑADIR UN MÓDULO DE NUMERACIÓN (OPCIONAL) .................................. 37
AÑADIR UN MÓDULO DE NUMERACIÓN ........................................ 37
CREACIÓN DE UN TEMA .............................................................................. 38
DESARROLLO DE UN MÓDULO PARA DOLIBARR +3.2
3
CREACIÓN DE UN NUEVO TEMA .................................................... 38
DESARROLLO DE UN MÓDULO PARA DOLIBARR +3.2
4
INTRODUCCIÓN
INTRODUCCIÓN
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:
Añadir nuevas tablas a la base de datos.
Añadir sus propias entradas en los menús.
Añadir pantallas de edición/consulta de nuevas tablas.
Añadir o eliminar pestañas en las páginas de vista/edición de objetos (factura,
producto, pedido, evento, etc.)
Añadir exportaciones predefinidas a la función “Exportar”.
Añadir variables de substitución
Añadir nuevas cajas a la página de inicio.
Definir nuevos permisos.
Activar código automático sobre una acción particular de Dolibarr.
Insertar nuestro código mediante los hooks de Dolibarr
Añadir un módulo de numeración
Añadir un modelo de documento
Añadir un nuevo tema
etc. Todas estas operaciones sólo están disponibles a partir de la versión 3.2 de
Dolibarr.
CREAR UN DESCRIPTOR DE MÓDULO (OBLIGATORIO)
CREAR UN DESCRIPTOR DE MÓDULO
DESARROLLO DE UN MÓDULO PARA DOLIBARR +3.2
5
Cuándo: Obligatorio cada vez que se desarrolla una extensión, cualquiera que sea su
finalidad.
CREAR SU DESCRIPTOR
La primera fase es la de crear un fichero descriptor del módulo. Para ello:
•
Crear el directorio /htdocs/mimodulo/core/modules. Seguidamente ir al directorio
dev/skeletons y copiar el archivo modMyModule.class.php en el directorio
htdocs/monmodule/core/modules.
A continuación, modificar el contenido del archivo, reemplazando:
•
los "modMyModule" por un valor que corresponda a la finalidad de su módulo.
Este valor debe siempre comenzar por mod.
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.
•
•
•
$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")
Modificar eventualmente otras variables definidas por los desarrolladores (ver el
comentario en el código del esqueleto para ver su significado)
Crear el directorio /htdocs/mimodulo/
Ahora su fichero descriptor está configurado.
PROBAR SU DESCRIPTOR
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
DESARROLLO DE UN MÓDULO PARA DOLIBARR +3.2
6
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.
ARBOL DE UN MÓDULO
ESTRUCTURA DE ARBOL DE UN 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:
mimodulo/core/modules/ debe contener el archivo descriptor del módulo :
modMiModulo.class.php
mimodulo/core/triggers contiene los triggers usados
mimodulo/admin/ contiene las páginad de configuración del módulo
mimodulo/class/ contiene las clases PHP necesarias para el módulo
mimodulo/css contiene los archivos CSS necesarios para el módulo
mimodulo/img contiene las imagenes suministradas con el módulo
mimodulo/langs/xx_XX contiene los archivos de traducción para el idioma xx_XX
(como mínimo en_US)
mimodulo/lib contiene las bibliotecas necesarias para el módulo
mimodulo/sql contiene los archivos SQL usador para añadir las nuevas tablas o
índices necesarios para el módulo
mimodulo/themes/mitema si el módulo tiene su propio tema/skin
build/ puede contener todos los archivos usados para compilar o construir el
paquete de distribución
docs/ contiene todo lo que se refiera a documentación. También puede contener
los archivos de licencia
scripts/ contiene los archivos de scripts (comandos en línea).
test/ contiene los archivos de testeo unitario (datos, scripts y clases de testeo)
README.txt es un archivo que resume el módulo. La documentación más
detallada se emplazará en el directorio docs
CREAR TABLAS SQL Y LA CLASE PHP CON MÉTODOS DE ACCESO
(OPCIONAL)
DESARROLLO DE UN MÓDULO PARA DOLIBARR +3.2
7
CREAR FICHEROS .SQL
Si su 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.
Cree un subdirectorio sql en el directorio de su módulo (por ejemplo,
htdocs/mimodulo/sql), con el fin de colocar los scripts sql que va a crear.
Regla a respetar:
•
•
Agregue los archivos de orden de creación de sus tablas siguiendo el principio de
un fichero llx_mitabla.sql por tabla, eventualmente acompañado del archivo
llx_mitabla.key.sql' (ver los archivos existentes en install/mysql/tables, para
tomar ejemplo).
En términos de orden de gestión de datos, todos deben estar en un archivo
llamado data.sql situado en la misma carpeta /mimodulo/sql/.
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.
DESARROLLO DE UN MÓDULO PARA DOLIBARR +3.2
8
PROBAR EL ARCHIVO .SQL
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.
DESARROLLO DE UN MÓDULO PARA DOLIBARR +3.2
9
GENERAR LA CLASE PHP DE ACCESO (DAO)
Una vez que su/s tabla/s estén creadas en la base de datos, vaya al directorio
dev/skeletons, copie el archivo build_class_from_table.php en la 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.
Esto genera un archivo 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. Suprima justo el "out" del nombre
del archivo y pógalo en un subdirectorio de htdocs propio en su módulo (Por ejemplo
en htdocs/mimodulo).
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.
VISUALIZACIÓN DE PESTAÑAS (OPCIONAL)
AÑADIR O ELIMINAR PESTAÑAS EN LAS FICHAS ENTIDAD
Cuándo : Para añadir su propia pestaña en las pestañas estandard 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
DESARROLLO DE UN MÓDULO PARA DOLIBARR +3.2
10
'objecttype:+tabname2:Title2:@mymodule:/mymodule/mynewtab2.php?id=__ID__'
, // To add another new tab identified by code tabname2
'objecttype:-tabname');
remove an existing tab identified by code tabname
// To
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 ":"
•
Parte 1: El código de la entidad (objecttype) en la que debe aparecer la pestaña
siendo el valor de ella misma:
'thirdparty' para añadir una pestaña en la vista de tercero
'intervention' para añadir una pestaña en la vista de intervención
'order_supplier' para añadir una pestaña en la vista de pedido a proveedor
'invoice_supplier' para añadir una pestaña en la vista de factura de proveedor
'invoice' para añadir una pestaña en la vista de factura a cliente
'order' para añadir una pestaña en la vista de pedido de cliente
'product' para añadir una pestaña en la vista de producto
'stock' para añadir una pestaña en la vista de stock
'propal' para añadir una pestaña en la vista de presupesto a cliente
'member' para añadir una pestaña en la vista de miembro
'contract' para añadir una pestaña en la vista de contrato
'user' para añadir una pestaña en la vista de usuario
'group' para añadir una pestaña en la vista de grupo
'contact' para añadir una pestaña en la vista de contacto
'categories_x' para añadir una pestaña en la vista de categoría (reemplazar 'x'
por el típo de categoría (0=producto, 1=proveedor, 2=cliente, 3=miembro)
DESARROLLO DE UN MÓDULO PARA DOLIBARR +3.2
11
•
•
•
Parte 2: El título de la pestaña. Puede ser una etiqueta directa o mejor un código
de traducción de un archivo lang.
Parte 3: El nombre del archivo .lang (sin la extensión .lang) que contiene la
correspondencia entre el código de traducción y la etiqueta a mostrar. Si el
nombre empieza con @, Dolibarr buscará el archivo en el directorio lang del
propio módulo, es decir, htdocs/mimodulo/langs/code_CODE/mimodulo.lang, de
lo contrario Dolibarr buscará el archivo de en /langs/code_CODE/mimodulo.lang
Parte 4: La url de la página a mostrar cuando se haga click en las pestaña. La
cadena __ID__ será reemplazada automáticamente por el Id de la entidad
concerniente.
Para alimentar el contenido de la pestaña con los datos de la base de datos, vea el
capítulo siguiente.
DESARROLLO DE UN MÓDULO PARA DOLIBARR +3.2
12
AÑADIR PESTAÑAS DE UNA FICHA ENTIDAD EN SU PROPIA PÁGINA
Cuándo : Para mostrar las pestañas estandard de ficha entidad (producto, tercero,
etc.) en su propia pestaña de una entidad.
Hay que hacer lo siguiente :
1. Incluir los archivos que definen las funciones útiles dentro de sus
archivos
Para cada ficha entidad, hay que incluir dos archivos con la instrucción
require_once($url_fichier) ;
Aquí le mostramos la lista de estos archivos (DOL_DOCUMENT_ROOT correspond au
dossier dolibarr/htdocs/) :
•
Entidad tercero (thirdparty) :
DOL_DOCUMENT_ROOT/societe.class.php
DOL_DOCUMENT_ROOT/lib/company.lib.php
•
Entidad producto (product) :
DOL_DOCUMENT_ROOT/product.class.php
DOL_DOCUMENT_ROOT/lib/product.lib.php
•
Entidad factura (invoice) :
DOL_DOCUMENT_ROOT/facture.class.php
DESARROLLO DE UN MÓDULO PARA DOLIBARR +3.2
13
DOL_DOCUMENT_ROOT/lib/invoice.lib.php
2. Crear y cargar el objeto a mostrar en su pestaña
Crear el objeto de la clase deseada, y recuperar los datos del objeto a partir de la
base de datos. Para ello deberá utilizar las funciones fetch() de la clase
correspondiente, pasando el parámetro del indentificador del objeto que recupera
desde la url (ej : /mononglet.php?id=1).
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
Usar la función XXX_prepare_head($obj), donde XXX es le nombre de la entidad,
para crear una tabla que contiene las definiciones de las pestañas a mostrar. El
parámetro a pasar es el objeto del que desea mostrar las pestañas.
La tabla devuelta se compone de la siguiente manera :
$head
$head[$h]
afficher
// Tableau des onglets
// Élément décrivant un onglet. Il y aura autant de $h que d'onglets à
$head[$h][0] // Url de la page affichée quand on clique sur l'onglet
$head[$h][1] // Titre de l'ongLet
DESARROLLO DE UN MÓDULO PARA DOLIBARR +3.2
14
$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.
$active // Onglet actif (mettre le nom de l'onglet défini dans votre fichier de module,
ou un nom contenu dans $head[$h][2]). Cet onglet sera mis en surbrillance
$title // ?
$notab // Mettre ce paramètre à 1 permet de ne pas afficher de zone bleue en
dessous des onglets.
$picto // Nom de l'image à utiliser au début de la barre des onglet. Les choix suivant
sont possibles :
//
product
//
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.
DESARROLLO DE UN MÓDULO PARA DOLIBARR +3.2
15
Nota: Para más detalles, consulte la documentación Doxygen o directamente el
código de Dolibarr.
CREAR PÁGINA PANTALLA PHP (OPCIONAL)
CREAR UNA PÁGINA PANTALLA PHP
Debe crear a continuación pantallas PHP que se basen en los datos de sus tablas
utilizando los esqueletos como ejemplo del directorio dev/skeletons. (Para el
desarrollo de un script en línea de comandos, ver Desarrollo de scripts).
Para crear una nueva página de usuario, cree un subdirectorio de htdocs (si es que
no existe ya) propio en su módulo (En htdocs/mimodulo, por ejemplo), con el fin de
ubicar en él las páginas que va a crear.
Copie allí el archivo skeletons_page.php, que va a servir de punto de partida a su
página. Modifique el archivo 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
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:
•
•
•
•
$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, teclee su código para archivar la página.
DESARROLLO DE UN MÓDULO PARA DOLIBARR +3.2
16
REEMPLAZAR PARTES DE TEMPLATES DE PANTALLA (VERSIÓN 3.3+)
Algunas partes de la pantalla de Dolibarr están aisladas en archivos de plantilla.
Puede desarrollar un módulo para reemplazar una o más de estas plantillas con las
suyas.
DESARROLLO DE UN MÓDULO PARA DOLIBARR +3.2
17
ACCESO A LA BASE DE DATOS
Si necesita realizar modificaciones en su tabla de la base de datos, utilice la clase
generada más arriba.
Si de todos modos quiere acceder a las tablas sin objeto PHP dedicado, esto es
posible (por ejemplo para recuperar una lista de registros). En ese caso, piense 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);
DESARROLLO DE UN MÓDULO PARA DOLIBARR +3.2
18
if ($obj)
{
// You can use here results
print $obj->field1;
print $obj->field2;
}
$i++;
}
}
}
DESARROLLO DE UN MÓDULO PARA DOLIBARR +3.2
19
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”.
DESARROLLO DE UN MÓDULO PARA DOLIBARR +3.2
20
UTILIZAR EL SELECTOR DE FECHAS DE DOLIBARR
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);
DEFINIR LA PÁGINA DE CONFIGURACIÓN (OPCIONAL)
CREAR PÁGINA DE EDICIÓN DE CONFIGURACIÓN
Si su 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). 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_setupapage.php");
DESARROLLO DE UN MÓDULO PARA DOLIBARR +3.2
21
PROBAR LA PÁGINA
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.
DEFINIR ENTRADAS DE MENÚ (OPCIONAL)
DEFINIR ENTRADAS DE MENÚ
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
$r=0;
// Add here entries to declare new menus
// Example to declare the Top Menu entry:
$this->menu[$r]=array(
top menu
'fk_menu'=>0,
'type'=>'top',
// Put 0 if this is a
// This is a Top menu entry
'titre'=>'MyModule top menu',
'mainmenu'=>'mymodule',
'leftmenu'=>'mymodule',
'url'=>'/mymodule/pagetop.php',
DESARROLLO DE UN MÓDULO PARA DOLIBARR +3.2
22
'langs'=>'mylangfile',
// Lang file to use (without .lang)
by module. File must be in langs/code_CODE/ directory.
'position'=>100,
'enabled'=>'1',
// Define condition to show
or hide menu entry. Use '$conf->mymodule->enabled' if entry must be visible if
module is enabled.
'perms'=>'1',
// Use 'perms'=>'$user->rights>mymodule->level1->level2' if you want your menu with a permission rules
'target'=>'',
'user'=>2);
users, 1=external users, 2=both
// 0=Menu for internal
$r++;
// Example to declare a Left Menu entry:
$this->menu[$r]=array(
'fk_menu'=>'fk_mainmenu=xxx',
// Use
'fk_mainmenu=xxx' or 'fk_mainmenu=xxx,fk_leftmenu=yyy' where xxx is
mainmenucode and yyy is a leftmenucode
'type'=>'left',
// This is a Left menu entry
'titre'=>'MyModule left menu 1',
'mainmenu'=>'xxx',
'leftmenu'=>'mymodule',
'url'=>'/mymodule/pagelevel1.php',
'langs'=>'mylangfile',
// Lang file to use (without .lang)
by module. File must be in langs/code_CODE/ directory.
'position'=>100,
'enabled'=>'1',
// Define condition to show
or hide menu entry. Use '$conf->mymodule->enabled' if entry must be visible if
module is enabled.
'perms'=>'1',
// Use 'perms'=>'$user->rights>mymodule->level1->level2' if you want your menu with a permission rules
'target'=>'',
DESARROLLO DE UN MÓDULO PARA DOLIBARR +3.2
23
'user'=>2);
users,1=external users, 2=both
// 0=Menu for internal
$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.
DESARROLLO DE UN MÓDULO PARA DOLIBARR +3.2
24
PROBAR ENTRADAS DE MENÚ
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).
DEFINIR PROPIOS PERMISOS (OPCIONAL)
DEFINIR PROPIOS PERMISOS
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][3] = 1;
$this->rights[$r][4] = 'accion';
$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 $thisDESARROLLO DE UN MÓDULO PARA DOLIBARR +3.2
25
>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) ...
DEFINIR PROPIOS PANELES (OPCIONAL)
DEFINIR PROPIOS PANELES
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 una línea por cada archivo de panel 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 cree los archivos mabox0.php, mabox1.php... tomando como ejemplo
los paneles existentes (en el directorio htdocs/include/boxes)
DESARROLLO DE UN MÓDULO PARA DOLIBARR +3.2
26
PROBAR LOS PANELES
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.
DEFINIR LAS EXPORTACIONES (OPCIONALES)
DEFINIR LA EXPORTACIÓN
Para ello, descomente y modifique las tablas $this->export_xxx de su archivo
descriptor de módulo.
DESARROLLO DE UN MÓDULO PARA DOLIBARR +3.2
27
PROBAR LA EXPORTACIÓN
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.
DEFINIR ESTILOS CSS (OPCIONAL)
CREAR Y DECLARAR LA HOJA DE ESTILOS
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.
Una vez su hoja de estilos esté disponible, declárela en su archivo descriptor de
módulo modificando la propiedad $this->module_parts. 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'));
DESARROLLO DE UN MÓDULO PARA DOLIBARR +3.2
28
PROBAR LA HOJA DE ESTILOS
Desactivar y reactivar su módulo.
Ir la página de inicio de Dolibarr. Ver el código de la página HTML.
Debería ver en el encabezado HTML, una línea de declaración de su hoja de estilos.
DEFINIR FUNCIONES JAVASCRIPT (OPCIONAL)
DEFINIR FUNCIONES JAVASCRIPT
Cuando: Si en sus pantallas en PHP utiliza funciones de Javascript no disponibles en
estandard (archivo lib_head.js)
Si en sus pantallas en PHP utiliza funciones javascript, es necesario asegurarse de
que las funciones declaradas en un archivo javascript
htdocs/mimodulo/js/monmodule.js sea cargado en la cabecera del head html.
Para pedir a Dolibarr que gestione en la generación de la sección header la inclusión
de uno de sus archivos javascript, es necesario proporcionar como parámetro a la
función llxHeader(), al inicio de su página, la URL hacia el js a incluir.
Ejemplo para la página /htdocs/mimodulo/mapage.php :
require('../main.inc.php');
$morejs=array("/mimomulo/js/monmodule.js");
llxHeader('','Titulo','','','','',$morejs,'',0,0);
EJECUTAR CÓDIGO SOBRE UN EVENTO DOLIBARR (OPCIONAL)
EJECUTAR CÓDIGO SOBRE UN EVENTO DOLIBARR
DESARROLLO DE UN MÓDULO PARA DOLIBARR +3.2
29
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).
Interfaces Dolibarr hacia el exterior
Dolibarr proporciona dos mecanismos sencillos para poder actuar en una aplicación
externa en un evento interno de Dolibarr:
•
•
Los triggers - un mecanismo para activar su código cuando Dolibarr ejecute una
acción (creación de factura, edición de un usuario, eliminación de un pedido, etc.)
El sistema Hooks - un interfaz para integrar su código en un punto de entrada de
Dolibarr.
Interfaces del Exterior hacia Dolibarr
Existen 3 métodos para permitir que una aplicación exterior inserte datos en Dolibarr
(Para obtener información acerca del caso contrario y permitir a Dolibarr insertar
datos en el exterior, consulte la página Interfaces Dolibarr hacia el exterior).
Las tres técnicas posibles son las siguientes:
Inserción de datos directa en la base de datos
Esta solución requiere el conocimiento del modelo físico y los valores autorizados de
los campos. Es arriesgado y debe ser reescrito en caso de modificiación del formato
de la base de datos Dolibarr.
Ventajas: Se puede realizar en cualquier lenguaje.
DESARROLLO DE UN MÓDULO PARA DOLIBARR +3.2
30
Inconveniente: Esta técnica es muy desaconsejada. Al primer aumento de versión
Dolibarr, este método puede dejar de funcionar, siendo necesario reescribirlo.
Además, utilizando este método, se pasan por alto las reglas de negociado de
validación, creando un riesgo de corrupción de datos. Este método también necesita
conocer la base de datos Dolibarr.
Uso de clases PHP
Es posible utilizar objetos de negociado de Dolibarr (Los ficheros xxx.class.php).
Cada uno de estos ficheros ofrece una clase equipada con métodos para:
•
•
•
•
•
la recuperación de una entidad (el método fetch)
La inserción de una entidad (el método create o insert)
la actualización de una entidad (el método update)
la eliminación de una entidad (el método delete) si es aplicable al objeto
Otros métodos diversos propios de la entidad manipulada.
Esta técnica es preferible a la anterior.
Ventajas: Ofrece la ventaja de pasar a través de capas de negociado de validación
de datos. La interfaz del código no debería ser sobreescrita en caso de aumento de
versión de Dolibarr.
Inconvenientes: Sólo se utiliza en PHP. Su código debe de estar situado en el mismo
servidor que los archivos Dolibarr.
Web service:
Dolibarr dispone un servidor y un cliente de ejemplo de web services en la carpeta
htdocs/webservices.
El servidor utiliza la librería PHP Nusoap (sin necesidad de módulo PHP
suplementario) que ha sido modificada para trabajar tanto en PHP4 como en PHP5.
DESARROLLO DE UN MÓDULO PARA DOLIBARR +3.2
31
Puede enviar su consulta SOAP enviándola a la URL relativa
/webservices/server_xxx.php
xxx es:
•
•
•
•
•
"other"
"thirdparty"
"productorservice"
"invoice"
"supplier_invoice"
Por ejemplo, en la demo en línea de Dolibar, envíe su consulta a
http://demo.dolibarr.org/webservices/server_other.php
Sólo unos pocos servicios están disponibles. Puede obtener una lista completa de los
servicios prestados llamando a la URL sin parámetros POST.
Por ejemplo, para ver todos los webservices suministrados con la versión de demo,
llame simplemente a la URL siguiente sin parámetros:
http://demo.dolibarr.org/webservices/server_other.php
Para obtener el fichero WSDL que describe los contratos webservices, puede llamar
a:
http://demo.dolibarr.org/webservices/server_other.php?wsdl
•
Cliente de web services Dolibarr
DESARROLLO DE UN MÓDULO PARA DOLIBARR +3.2
32
Tenga en cuenta que se encuentra disponible un ejemplo de código PHP client que
realiza la llamada de web services solicitando la URL /webservices/server.php Por
ejemplo, en la demo en línea, llamar a
http://demo.dolibarr.org/webservices/demo_wsclient_other.php
•
Listado de Services Web
La lista de servicios disponibles se puede consultar en la página /webservices/. Por
ejemplo, en el servidor Dolibarr de demostración, esta es la URL:
http://demo.dolibarr.org/webservices/
Actualmente esta lista es muy corta, pero será enriquezida en las versiones futuras
...
EJECUTAR CÓDIGO USANDO HOOKS EN DOLIBARR
EJECUTAR CÓDIGO USANDO HOOKS EN 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).
El sistema Hooks
Hooks es una funcionalidad de desarrollo (con Dolibarr 3.2) que permite a los
desarrolladores agregar código personalizado en el código del núcleo de Dolibarr sin
necesidad de parchear Dolibarr. Al contrario que los triggers (otra funcionalidad para
interactuar con el código de Dolibarr) que están vinculados a una acción de
negociado, los hooks pueden producirse en cualquier lugar y en cualquier momento,
son un punto de entrada en el programa.
DESARROLLO DE UN MÓDULO PARA DOLIBARR +3.2
33
Hooks trabaja por contexto (es decir por módulo, ej: "productcard" para
productos, "invoicecard" para facturas, etc.). Es fácil de encontrar, solo hay que
burcar por "initHooks("
Hooks son funciones que pueden ser sobrecargadas por las suyas propias. Usted
es el que decide si su código se añade al código estandar de Dolibarr o si reemplaza
al código de Dolibarr. Puede encontrar funciones sobrecargables buscando por
"executeHooks("
Implementación
Para usar un hook (sobrecarga de una función), debe de haber definido un módulo
antes (vea la wiki para ello), y entonces tiene que hacer 2 cosas:
1- Añadir su módulo a los hooks del contexto que desee. Esto significa que cuando
este contexto (módulo) va a suceder, el módulo será llamado. Para ello edite su
/htdocs/sumodulo/includes/modSuModulo.class.php y edite la variable $this>module_parts con algo como esto:
$this->module_parts = array(
'hooks' => array('hookcontext1','hookcontext2') // Set here all hooks context
managed by module
);
IMPORTANTE: Tenga cuidado: No olvide DESACTIVAR y luego ACTIVAR el módulo en
el panel de administración para aceptar los nuevos valores de las constantes, ya que
estas constantes solo se añaden a la base de datos cuando se activa el módulo.
2- Sobrecargar un hook (una función) con la suya propia.
Cree un archivo /htdocs/sumodulo/class/actions_sumodulo.class.php y luego escriba
algo como esto:
DESARROLLO DE UN MÓDULO PARA DOLIBARR +3.2
34
class ActionsYourModuleName
{
/** Overloading the doActions function : replacing the parent's function with the
one below
* @param
parameters meta datas of the hook (context, etc...)
* @param
object
the object you want to process (an invoice if you
are in invoice module, a propale in propale's module, etc...)
* @param
null
* @return
action
current action (if set). Generally create or edit or
void
*/
function doActions($parameters, $object, $action)
{
print_r($parameters);
echo "action: ".$action;
print_r($object);
if (in_array('somecontext',explode(':',$parameters['context'])))
{
// do something only for the context 'somecontext'
}
}
}
donde
DESARROLLO DE UN MÓDULO PARA DOLIBARR +3.2
35
$parameters es un array de meta-datos acerca de los datos contenidos en el hook
(ej: el contexto, siempre accesible mediante $parameters['context']).
$object es el objeto con el que va a trabajar. Ej: el producto si se encuentra en el
contexto productcard.
$action es la acción si se ha enviado alguna (generalmente "create", "edit" o
"view").
Listado de Hooks disponibles
¿Cómo encontrar hooks disponibles? Realice una búsqueda de "executeHooks(" y le
será fácil encontrar las llamadas a los métodos Hook.
afterLogin
afterPDFCreation
createFrom
doActions
printLeftBlock
printSearchForm
printTopRightMenu
printObjectLine
formAddObject: Add a product into an element
formObjectOptions: called everytime fields associated to the main object are
printed or inputted (eg: creation form, datasheet, edit form, etc..).
formConfirm
createDictionaryFieldlist
editDictionaryFieldlist
viewDictionaryFieldlist
...
DESARROLLO DE UN MÓDULO PARA DOLIBARR +3.2
36
AÑADIR UN MÓDULO DE NUMERACIÓN (OPCIONAL)
AÑADIR UN MÓDULO DE NUMERACIÓN
Cuándo: Si quiere añadir una regla de numeración no cubierta por los módulos por
defecto.
Para cada entidad creada en la aplicación, Dolibarr le asigna una referencia. Con el
fin de adaptar la referencia a cualquier uso, Dolibarr utiliza módulos para definir la
regla de generación de esta referencia. Los módulos se suministran como estándar,
por lo tanto, algunos son genéricos y se utilizan para definir la máscara de
numeración (x número de caracteres, con o sin prefijo, incluyendo la fecha o no,
etc), pudiendo satisfacer la mayoría de las necesidades. Sin embargo, aún hay casos
en los que el módulo estándar incluido no responde a la necesidad. En este caso es
necesario para desarrollar su propio módulo de numeración. .
Crear un nuevo módulo de numeración
Por ejemplo, partiremos del principio que crearemos un nuevo módulo de
numeración de facturas al que llamaremos 'terrebis' y que se basa en el módulo
incluido como estándar 'terre':
copiar-pegar htdocs/includes/modules/facture/terre/terre.modules.php en
htdocs/includes/modules/facture/terrebis/terrebis.modules.php. Puede utilizar el
nombre que desee en lugar de terrebis, siempre que no esté ya en uso y que
contenga solamente caracteres alfabéticos.
editar el nuevo fichero para realizar las siguiente modificaciones en el código :
1. Renombrar el nombre de la clase para reemplazar el nombre de clase por el
nombre escogido (conservar las mismas convenciones).
2. Modificar el código del método info() para devolver una descripción de su módulo.
3. Modificar el código del método getExemple() para devolver un ejemplo de
referencia devuelto por el módulo.
DESARROLLO DE UN MÓDULO PARA DOLIBARR +3.2
37
4. Modificar el código del método canBeActivated() para realizar solo un "return
true;"
5. Modificar el código del método getNextValue() para devolver el siguiente número
de referencia.
En el código de esta función, puede utilizar los parámetros $objsoc ó $facture que
contienen la información de los terceros implicados en la generación y el objeto que
participa en la generación (Los nombres de estas variables pueden ser diferentes en
función de la naturaleza de la entbjetidad gestionada por el módulo). Puede utilizar
además los objetos $langs, $conf y $db, a condición de declarrarlos mediante la línea
global $langs, $conf, $db;
Estos objetos contienen: $langs: la información del idioma del usuario $conf: la
configuración de Dolibarr $db: el objeto de conexión a la base de datos que permite
realizar las consultas SQL.
6. Guardar: el modelo 'terrebis' está disponible en la lista de modelos de facturas de
Dolibarr
Testear el módulo
Testee este módulo activándolo desde la página de configuración del módulo.
Compruebe que las columnas de descripción, ejemplos y valor siguiente, se obtienen
informaciones coherentes (devueltas respectivamente por las funciones info(),
getExample() y getNextValue() ).
CREACIÓN DE UN TEMA
CREACIÓN DE UN NUEVO TEMA
Para crear un tema nuevo, ir a la carpeta 'htdocs/theme/' y copiar, por ejemplo, toda
la carpeta 'dolibarr' hacia una nueva carpeta al que daremos por nombre el nombre
de nuestro tema.
DESARROLLO DE UN MÓDULO PARA DOLIBARR +3.2
38
En esta carpeta cambiar el nombre del fichero .css por el mismo que el de la carpeta.
Modificar el fichero AUTHOR con la informción que le concierne.
Modificar el CSS, así como las imágenes contenidas en la carpeta img para
personalizar su tema.
El nombre del tema aparecerá automáticamente en la lista de temas utilizables en la
página Configuración - Interface donde podremos activarlo por defecto, o en
Usuarios y grupos - Pestaña Interface usuario para activarlo para un usuario en
concreto.
Workcomputer.png
Difusión de su tema
Cuando haya creado un tema nuevo, puede realizar un package para su distribución
mediante el script build/makepack-dolibarrtheme.pl
Obtendrá un fichero .tgz que podrá enviar al área de descargas de Dolibarr (Sección
contrib).
DESARROLLO DE UN MÓDULO PARA DOLIBARR +3.2
39