Dolibarr ERP CRM Wiki - User contributions [en]

Module Timesheet

2021-10-10T10:18:53Z

Delcroip: update change log an doc link

[[Category:Complementary modules]]
[[Category:timesheet]]
{{TemplateDocDevEn}}
{{TemplateDocUser}}
<seo metak="timesheet, Dolibarr, interface, project, task, report, approval" />

=Informations=
[[File:Warning.png]] This module is an external module. It provide another view of the native feature to enter timesheet available in [[Module Projects]] among other features

[https://dolibarr-timesheet.readthedocs.io/en/latest/ Documentation: https://dolibarr-timesheet.readthedocs.io/en/latest/]

{{TemplateModuleInfo
|modulename=timesheet
|editor=delcroip
|webbuy={{LinkToPluginDownloadDoliStore|keyword=timesheet}}
|status=stable
|prerequisites=projects
|minversion=3.5.0
|maxversion=6.0
|note=Latest Module version: 2.0.1
}}

=Features=

- Timesheet interface for all the user task per week
- Generate report on user and on project per month
- favourties to show only some project/task by a simple click on a start icon next to the task name
- Approval of the timesheets per the N+1
- Approval of the timesheets per project manager
- Generate project invoice from timesheet data

[[File:timesheet_timeentry.jpg]]

=Change logs=
https://github.com/delcroip/dolibarr_project_timesheet/blob/master/htdocs/timesheet/ChangeLog.md

FAQ Migrate my Mysql database to PostgreSQL

2019-01-15T10:41:12Z

Delcroip:

[[Category:FAQ EN]]

= Prerequisite=
Your Dolibarr version must be at least version 3.2.0.
If not, first upgrade your Dolibarr keeping MySq. Once upgrade is ok, you must clean database from old tables by running following request on your Mysql database:
<source lang="sql">
DROP TABLE llx_c_methode_commande_fournisseur;
DROP TABLE llx_c_source;
DROP TABLE llx_cond_reglement;
DROP TABLE llx_expedition_methode;
DROP TABLE llx_product_fournisseur;
ALTER TABLE llx_product_fournisseur_price DROP COLUMN fk_product_fournisseur;
</source>

=Process=

===Export Mysql===
* Go onto page '''Setup - Tools - Backup'''.
* Choose export method "'''MySql dump'''".
* Choose export compatibility "'''POSTGRESQL'''".
* Uncheck "'''Structure'''".
* Check "'''Name columns'''".
* Uncheck "'''Use extended INSERT'''".
* Choose "'''No LOCK command around INSERT'''".
* Into '''Compression''' area, choose "'''Compress None'''"
* Then click on "'''Build backup'''".
* Go into directory of your Dolibarr data files (directory is defined into "'''Setup - System information - Dolibarr - All parameters'''" on line "'''Root directory for data files'''"). Go into subdirectory '''admin/backup'''. You will find the dump of database you just build with previous step. Copy this file into /tmp directory.

===Create a PostGreSQL database===
* Rename your '''conf.php''' file of Dolibarr into conf.php.mysql (file should be into '''/etc/dolibarr''' or '''htdocs/conf''')
* Create an empty file '''conf.php''' to replace the renamed one, with read and write permission for everybody.
* Run Dolibarr. Because the conf.php file is empty, the install process will be suggested instead of logon page. Choose first installation and provide all informations of your postgresql database as data source. Run process until the end. About administrator account asked at end, choose same than the one existing into your MySql sessions.
* Connect. You are now into an empty new instance of Dolibarr without old data.
* Enable all modules that were enabled into old database (enable is enough to create modules specific tables, that's all what we want: having same structure than old database).
* If you added "complementary fields" for some element, you must also defined them into this new instance (again, to have same fields into database than previous instance).
* We will load old data at next step.
Note: If you experience problem, you can go back to your Mysql database by restoring files renamed previsously into its original name '''conf.php'''.

=== Import dump file ===
* Modify postgresql configuration to accept syntax from mysql file by setting the directive escape_string_warning to off into file '''postgresql.conf'''
<source lang="ini">
escape_string_warning = off
</source>
Restart postgresql.
* Disable all constraint checks to allow import. For this, connect to database and run the procedure provided by Dolibarr installation:
<source lang="sql">
psql -h name_or_ip_of_postgresql_server -d name_database_postgresql -U login_database_mysql
> select dol_util_triggerall(false);
CTRL+D
</source>
* Modify the generated export dump file to set escape characters with correct value for postgres:
<source lang="bash">
cd /tmp
sed -e "s/\\\'/\'\'/g" mysqldump_mydatabase_version_date.sql > mysqldump_readyforpgsql.sql
</source>
* After conversion of file, import it into your empty postgresql database:
<source lang="bash">
psql -h name_or_ip_of_postgresql_server -d name_database_postgresql -U login_database_mysql -f mysqldump_readyforpgsql.sql >resimport.log 2>&1
</source>
Take a look at output log file resimport.log. If target structure was correctly matching mysql structure (no less tables nor fields), you should get no error.
If you have error, please report them onto dolibarr forum.
Note that you can run this import several time if you fixed error manually to your structure. It is safe because all dolibarr tables are protected by a "unique key". So if you do so, you will just get "duplicate record" errors, that you can ignore. Take care only on others.
* Once import is finished, you must enable constraint check and update all sequences to match imported data.
<source lang="sql">
psql -h name_or_ip_of_postgresql_server -d name_database_postgresql -U login_database_mysql
> select dol_util_triggerall(true);
> select dol_util_rebuild_sequences();
CTRL+D
</source>
You can also restore the postgresql.conf file to its initial value.
<source lang="ini">
escape_string_warning = on
</source>

===Modify your Dolibarr setup file===
* Open with a file editor, the file conf/conf.php that you can find into your Dolibarr root installation.
* Modify lines to make program files to point to the new database
<source lang="ini">
$dolibarr_main_db_host='name_or_ip_of_postgresql_server';
$dolibarr_main_db_port='port_of_postgresql_server';
$dolibarr_main_db_name='name_database_postgresql';
$dolibarr_main_db_user='login_database_postgresql';
$dolibarr_main_db_pass='password_database_postgresql';
$dolibarr_main_db_type='pgsql';
</source>

===Test===
You should now have an application 100% working with all its data.
Old MySql database can be closed.

FAQ Migrate my Mysql database to PostgreSQL

2019-01-14T20:09:42Z

Delcroip:

List of modules id

2018-11-04T20:26:54Z

Delcroip: /* ID > 500000 */

[[Category:Core]]
{{TemplateDocDevEn}}
{{TemplateDocDevEs}}
{{TemplateDocDevFr}}

{{Flag en}} This page list all reserved modules numbers / ID. If you build or want to build your own modules (like this [[:Category:Complementary_modules|complementary module]]), you should take an ID range here.

{{Flag fr}} Cette page recense tous les numéros / ID réservés de modules. Si vous avez réalisé ou voulez réaliser vos propres modules (comme les [[:Category:Modules complémentaires|modules complémentaires suivant]]), vous devriez prendre une plage d'ID ici.

{{Flag sp}} Esta página contiene un listado de todos los id reservados para los módulos. Si ha creado o quiere realizar sus propios módulos, (como estos [[:Category:Módulos_complementarios|módulos complementarios]]), deberá reservarse un rango de ID aquí.

= ID 0 - 99999 =
{{Flag en}} Reserved for Dolibarr's internal modules.

{{Flag fr}} Réservé aux modules internes de Dolibarr.

{{Flag sp}} Reservado a los módulos internos de Dolibarr.

= ID 100000 - 499999 =
{{Flag en}} Reserved area for editors in need for an ID range. You can edit this page to add your own range (limited to 1000 values per editor)

{{Flag fr}} Zone réservé aux éditeurs qui ont besoin d'une plage d'ID spécifiques. Vous pouvez modifier cette page pour réserver votre plage (limité à 1000 valeurs par éditeur)

{{Flag sp}} Área reservada para los partners que necesiten un rango de ID. Puede modificar esta página para reservar su rango (limitado a 1000 valores por editor)

* ID 100000 - 100999: OpenThink (http://www.openthink.be)
* ID 101000 - 101999: NLTechno (https://www.nltechno.com)
* ID 102000 - 102999: Tiaris (http://www.tiaris.fr)
* ID 103000 - 103999: Open-concept.pro (http://www.open-concept.pro)
* ID 104000 - 104999: ATM Consulting (http://www.atm-consulting.fr)
* ID 105000 - 105999: GPC.solutions
* ID 106000 - 106999: PHPASSO
* ID 107000 - 107999: TecLib (http://www.teclib.com) / Auguria (http://www.auguria.net)
* ID 108000 - 108999: ETHICWEB
* ID 109000 - 109999: Aplose (http://www.aplose.fr)
* ID 110000 - 110999: Librethic (https://librethic.io)
* ID 111000 - 111999: Asset IT (www.assetit.ch)
* ID 112000 - 112999: Aarboard AG (www.aarboard.ch)
* ID 113000 - 113999: Asilib - Alexandre Spangaro
* ID 114000 - 114999: Iceleaf OÜ
* ID 115000 - 115999: 2A2C Conseil - Cyril ZEKSER
* ID 116000 - 116999: Wolftec GmbH
* ID 117000 - 117999: Oscim (http://www.oscim.fr)
* ID 118000 - 118999: Oarces Web (dev.oarces.com)
* ID 119000 - 119999: Manuel Berrocal - Absolacom
* ID 120000 - 120999: Régis Houssin (http://www.inodbox.com)
* ID 121000 - 121999: Oscss - Shop
* ID 122000 - 122999: MrSof - la Nation du Web
* ID 123000 - 123999: Bruno Généré (webiseasy.org)
* ID 124000 - 124999: backbone internet service (www.backbone.co.at)
* ID 125000 - 125999: ProgSI (www.progsi.ma)
* ID 126000 - 126999: Catalanet
* ID 127000 - 127999: Virgilio Filho pt-BR Brasil (@dolibarr.br)
* ID 128000 - 128999: Nicolas Frappé France (www.sospc.info)
* ID 129000 - 129999: Adeo-Informatique
* ID 130000 - 130999: Technicks ICT (http://www.technicks.eu)
* ID 131000 - 131999: Joan Louis (itaca.fr)
* ID 132000 - 132999: Jean-Marie Arsac (https://azimut.fr)
* ID 133000 - 133999: Oriel Systems Ltd, UK. (www.orielsystems.com)
* ID 135000 - 135999: Net-Logic (http://netlogic.fr)
* ID 140000 - 140999: Altairis
* ID 150000 - 150999: Jeffinfo
* ID 160000 - 160999: Charles-François BENKE (http://www.patas-monkey.com)
* ID 162000 - 162999: Jacques Rébiscoul
* ID 163000 - 163999: Open-DSI (https://www.open-dsi.fr)
* ID 170000 - 170999: TRIDENT CONSULTING LTD (www.tridentdxb.com)
* ID 171000 - 171999: LVSInformatique (www.lvsinformatique.com)
* ID 180000 - 180999: Triangle Ingénierie
* ID 190000 - 190999: Diciannove (http://19.coop)
* ID 199000 - 199999: RFMS
* ID 200000 - 200999: Noxiome
* ID 201000 - 201999: Sasa Ostrouska (saxa)
* ID 202000 - 202999: Z-Application
* ID 203000 - 203099: Elidee - elidee.com
* ID 203100 - 203999: Garcia MICHEL (soamichel.fr)
* ID 204000 - 204999: Ari Elbaz elarifr - accedinfo.com
* ID 205000 - 205999: Kreiz IT
* ID 206000 - 206999: GBINFO (www.gbinfo.fr)
* ID 300000 - 300999: AtooNet (http://www.atoo-net.com)
* ID 400000 - 400999: 2byte.es (http://www.2byte.es)
* ID 401000 - 401999: B&D Informática
* ID 402000 - 402999: Marcos García de La Fuente (marcosgdf)
* ID 403000 - 403999: Sergibyte (http://www.sergibyte.com)
* ID 404000 - 404999: Aikhan
* ID 405000 - 405999: AIME (http://www.aime.mx)
* ID 409000 - 409999: LliureTIC (www.lliuretic.cat)
* ID 420000 - 420099: BBS Concept
* ID 420100 - 420199: LeMousticProduction (www.lemousticproduction.info) -< module DoliRH
* ID 420200 - 421199: VatCheck (www.abnc.be)
* ID 422200 - 422999: Artaban (http://artaban.fr)
* ID 423000 - 423050: cyberesprit
* ID 423051 - 423099: R.Bossard
* ID 424000 - 424999: A3sys - Mon-Dolibarr (http://www.mon-dolibarr.fr)
* ID 425000 - 425999: Sébastien SERRE Thivinfo (www.thivinfo.com)
* ID 426000 - 426099: Arkesis-Solution
* ID 426100 - 426149: GetLandy (www.getlandy.com)
* ID 426150 - 426649: OOB Software
* ID 426650 - 426849: Soft-Task Serviços e Sistemas (www.soft-task.com.br)
* ID 426850 - 427000: Bruno Caldas (https://github.com/BCaldas)
* ID 427001 - 427999: Kevin GUERRIER (alias xcl.saian)
* ID 428000 - 428099: af83
* ID 429000 - 429999: induslab
* ID 430000 - 430099: Mixity sprl (www.mixity.be)
* ID 430100 - 430199: sgiraud
* ID 430200 - 430299: Merlion TI (www.merlion-si.com.br)
* ID 430300 - 431299: Libre Expert (www.libre-expert.com)
* ID 431300 - 431399: ptibogxiv (www.ptibogxiv.net)
* ID 431400 - 431499: Befox (www.befox.fr)
* ID 431500 - 431599: rue Béjo (www.ruebejo.fr)
* ID 431600 - 431699: Avizzeo (www.avizzeo.com)
* ID 431700 - 432199: Multisistemas (www.multisistemas.com.sv)
* ID 432200 - 432399: Burbuja - Chile (www.burbuja.cl)
* ID 432400 - 433399: INOVEA CONSEIL (https://www.inovea-conseil.com)
* ID 433400 - 434399: Rachid HRICH - Maroc (HricH ServiceS.)
* ID 434400 - 435399: Lance Bleakley - LanceIT (www.lanceit.net)
* ID 436400 - 437399: Mohamed AHERDANE - Morocco - IT Consultant ( www.wave.ma )
* ID 438400 - 439399: Tetras Libre - France - Développement logiciels libres (www.tetras-libre.fr)
* ID 439400 - 440399: Dolibarr-pro - France - Développement Dolibarr (www.dolibarr-pro.com)
* ID 440400 - 441399: Quidlab Co., Ltd - Thailand - ( www.quidlab.com )
* ID 441400 - 442399: Ide@log - France - (https://www.idealog-info.net) - Laurent Leblanc
* ID 442400 - 443399: Valerio Bianchi (www.valeriobianchi.com)
* ID 443400 - 444399: delassalle - France - (www.delassalle.fr) - Joseph Delassalle
* ID 444400 - 445399: Webartis - Maroc - (www.webartis.net) - François Dry
* ID 445400 - 445499: SCOP Au-delà des nuages - France
* ID 446000 - 446999: iouston (http://www.iouston.com) - France - Julien Marchand
* ID 447000 - 447999: rSanjoSEO - Rafael San José Tovar (www.rsanjoseo.com) - Spain
* ID 448000 - 448999: Code 42 (www.code42.fr)
* ID 449000 - 449999: TakePOS (www.takepos.com)
* ID 450000 - 450999: Pierre ARDOIN
* ID 451000 - 451999: Éditeur depordi.fr
* ID 452000 - 452999: Dylan NAKONG
* ID 453000 - 453999: Menahd Ouchenir - France - menahd-ouchenir.com
* ID 454000 - 454999: Withheld - Canada
* ID 455000 - 455999: Gaëtan MAISON - Info Libre @ Dom - France (www.infolibreadom.com)
* ID 456000 - 456999: Laurent LEBLEU - B.L.C. - Blue Line Company - Lille - France (www.bluelinecompany.fr/dolibarr)

= ID > 500000 =
*861000 - 861999: Patrick Delcroix

{{Flag en}} If you don't already have reserved ids and need some, please don't use hazardous number and use a number higher than 500000, but it is better to ask a wiki account, and reserve your own range by editing the 100000 - 499999 range (1000 ids maximum per partner).

{{Flag fr}} Si vous n'avez pas de numéros réservés et en avez besoin, n'utilisez pas de chiffres au hasard et utilisez une valeur supérieure à 500000, toutefois, il est préférable d'obtenir un compte wiki, et réserver vous-même votre plage en ajoutant votre entrée dans la zone 100000 - 499999 (pas plus de 1000 numéros par partenaire).

{{Flag sp}} Si no dispone de número reservado y necesita, no use cifras redondeadas y usa un valor superior a 500000. Si tiene una cuenta wiki, puede reservarse usted mismo sus id añadiendo su entrada en la zona 100000 - 499999 (no más de 1000 id por partner).

Generic website infrastructure setup

2018-10-21T12:24:05Z

Delcroip:

{{TemplateDocDevEn}}
This pages aims to provide links toward other reliable sources, to understand the different topics it's important to understand the principle that internet use.

1. Internet is an IP network, meaning that to reach every server an IP is required

2. When a name is used to reach a server, this name need to be translated to an IP by a Domain name server (DNS)

3. Your network use a private range of IP address therefore can't be reached from internet without a specific configuration

=Domain, Domain name server (DNS) and DynDNS=
Wikipedia[https://fr.wikipedia.org/wiki/Domain_Name_System]:
A DNS is important when you want to reach your server from internet because you don't want to learn your IP by heart, you'd rather buy a domain like mycompany.org and use it to reach your server. When you type "www.mydomain.com" in a browser, your computer will call the default DNS; if this DNS doesn't know the IP attached to mycompany.org it will check with other DNS until it gets the answer, sometime www.mycompany.org can refers to another domain like datacenter1.mycompany.org. In this the case, the DNS will look for the IP attached to datacenter1.mycompany.org.

When you own a domain, you also own all the sub-domain like www.mycompany.org, erp.mycompany.org, yyy.xxx.mycompany.org ...; you can map this domain and its sub.domain to either an IP or another domain, usually with the company that sold you the domain. Here the main type that you will have to configure on the domain vendor portal:
# "CNAME" record: used to map to another domain
# "A" record: use to map an IP v4
# "AAAA" record: use to map an IP v6
# In case you don't own a fixed IP, you can use a Dynamic DNS[https://en.wikipedia.org/wiki/Dynamic_DNS] service: there is a daemon running on your network that will keep updating your IP in the DNS (usually the internet modem/gateway have this function). Often you will have to configure a dynamic DNS username and password on your domain vendor portal.

Here the example for OVH: https://docs.ovh.com/gb/en/domains/web_hosting_how_to_edit_my_dns_zone/

=Port Forwarding, DMZ and Reverse Proxy=
Once your Domain/subdomain refers to your IP address, Internet requests will arrive to your internet gateway, but you'll need to setup port forwarding[https://en.wikipedia.org/wiki/Port_forwarding] in order to forward those requests toward your web server.

The default internet port are 80 for http and 443 for https, once the portforwarding is configured for those port (80 & 443), it'll affect all the web traffics coming on this port. A simple port forwarding will work if you have a single web server (could host several websites) but if you have multiple web servers you may have to forward your traffic to a reverse proxy[https://en.wikipedia.org/wiki/Reverse_proxy] that will be able to redirect the traffic based on the domain/subdomain or/and url.

If you want to be sure that internet traffic can't reach the other device on your network (LAN), you can place the reverse proxy in a DMZ[https://en.wikipedia.org/wiki/DMZ_(computing)] with firewall rules that allow only the traffic from internet to the reverse proxy and from the reverse proxy to specific IP on your local LAN (ie. your servers) but the firewall will block all other traffic coming from internet. For such setup there is an open source security appliance called pfSense that is able to do the firewall and the reverse proxy (with the module called HAProxy), pfSense can be installed on an old PC or deployed on a virtual machine.

=Virtual host=
Virtual host [https://en.wikipedia.org/wiki/Virtual_hosting] is a method which aims to define with a configuration file of the web server (e.g Apache) a domain/Url called by the user's browser to access to your application; for example a virtual host configuration can be setup for:
# www.mycompnay.org, the configuration file will define where to look for the pages like /usr/share/mangento/myshop ;
# cloud.mycompany.org, the configuration file can define a reverse proxy to redirect the traffic to http://localhost:8888 in order to show the nextcloud pages;
# dolibarr.mycompany.og, the configuration file could be the one to access your Dolibarr [https://github.com/Dolibarr/dolibarr/blob/develop/build/debian/apache/dolibarr.conf].

=SSL encryption=
The SSL encryption enable the encrypt the traffic between the user web browser and the server so even if someone is able to intercept the traffic he won't be able to see you passwords, website content ... the SSL encryption is configured at the virtual host level
# '''Certificat generation with Openssl (selfsigned)'''
<source lang="bash">
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 3650
</source>

You can also add -nodes if you don't want to protect your private key with a passphrase, otherwise it will prompt you for "at least a 4 character" password. The days parameter (3650) you can replace with any number to affect expiration date. It will then prompt you for things like "Country Name" but you can just hit enter and accept defaults.

Add -subj '/CN=localhost' to suppress questions about the contents of the certificate (replace localhost with your desired domain)

Self-signed certs are not validated with any third party unless you import them to the browsers previously. If you need more security, you should use a certificate signed by a trusted CA like let's encrypt (free), globalsign, Norton ...

# '''Certificat generation with Let's encrypt'''
As mentionned above self signed certificate will generate an error on browser unless the the certificate in "imported" on the computer, if not done by the systeml admin it gives an unprofessional experience for the user ( most browser message will say something like site dangerous/unsecure)

Let's encrypt is a free trusted certificate authority (aka CA) for most of the browsers meaning if let's encrypt says that your certificates are valide then most of the browser will trust your certicifacts and instead of a warning they will show a green lock on the address bar = the website is secure.

# '''Configuration of the virtual host'''
# '''Let's encrypt certificate renewal'''

=Advanced setup=
# '''virtualisation'''
# '''LXC container'''
# '''Docker'''
# '''pfSense'''

Generic website infrastructure setup

2018-10-21T12:16:14Z

Delcroip:

{{TemplateDocDevEn}}
This pages aims to provide links toward other reliable sources, to understand the different topics it's important to understand the principle that internet use.

1. Internet is an IP network, meaning that to reach every server an IP is required

2. When a name is used to reach a server, this name need to be translated to an IP by a Domain name server (DNS)

3. Your network use a private range of IP address therefore can't be reached from internet without a specific configuration

=Domain, Domain name server (DNS) and DynDNS=
Wikipedia[https://fr.wikipedia.org/wiki/Domain_Name_System]:
A DNS is important when you want to reach your server from internet because you don't want to learn your IP by heart, you'd rather buy a domain like mycompany.org and use it to reach your server. When you type "www.mydomain.com" in a browser, your computer will call the default DNS; if this DNS doesn't know the IP attached to mycompany.org it will check with other DNS until it gets the answer, sometime www.mycompany.org can refers to another domain like datacenter1.mycompany.org. In this the case, the DNS will look for the IP attached to datacenter1.mycompany.org.

When you own a domain, you also own all the sub-domain like www.mycompany.org, erp.mycompany.org, yyy.xxx.mycompany.org ...; you can map this domain and its sub.domain to either an IP or another domain, usually with the company that sold you the domain. Here the main type that you will have to configure on the domain vendor portal:
# "CNAME" record: used to map to another domain
# "A" record: use to map an IP v4
# "AAAA" record: use to map an IP v6
# In case you don't own a fixed IP, you can use a Dynamic DNS[https://en.wikipedia.org/wiki/Dynamic_DNS] service: there is a daemon running on your network that will keep updating your IP in the DNS (usually the internet modem/gateway have this function). Often you will have to configure a dynamic DNS username and password on your domain vendor portal.

Here the example for OVH: https://docs.ovh.com/gb/en/domains/web_hosting_how_to_edit_my_dns_zone/

=Port Forwarding, DMZ and Reverse Proxy=
Once your Domain/subdomain refers to your IP address, Internet requests will arrive to your internet gateway, but you'll need to setup port forwarding[https://en.wikipedia.org/wiki/Port_forwarding] in order to forward those requests toward your web server.

The default internet port are 80 for http and 443 for https, once the portforwarding is configured for those port (80 & 443), it'll affect all the web traffics coming on this port. A simple port forwarding will work if you have a single web server (could host several websites) but if you have multiple web servers you may have to forward your traffic to a reverse proxy[https://en.wikipedia.org/wiki/Reverse_proxy] that will be able to redirect the traffic based on the domain/subdomain or/and url.

If you want to be sure that internet traffic can't reach the other device on your network (LAN), you can place the reverse proxy in a DMZ[https://en.wikipedia.org/wiki/DMZ_(computing)] with firewall rules that allow only the traffic from internet to the reverse proxy and from the reverse proxy to specific IP on your local LAN (ie. your servers) but the firewall will block all other traffic coming from internet. For such setup there is an open source security appliance called pfSense that is able to do the firewall and the reverse proxy (with the module called HAProxy), pfSense can be installed on an old PC or deployed on a virtual machine.

=Virtual host=
Virtual host [https://en.wikipedia.org/wiki/Virtual_hosting] is a method which aims to define with a configuration file of the web server (e.g Apache) a domain/Url called by the user's browser to access to your application; for example a virtual host configuration can be setup for:
# www.mycompnay.org, the configuration file will define where to look for the pages like /usr/share/mangento/myshop ;
# cloud.mycompany.org, the configuration file can define a reverse proxy to redirect the traffic to http://localhost:8888 in order to show the nextcloud pages;
# dolibarr.mycompany.og, the configuration file could be the one to access your Dolibarr [https://github.com/Dolibarr/dolibarr/blob/develop/build/debian/apache/dolibarr.conf].

=SSL encryption=
The SSL encryption enable the encrypt the traffic between the user web browser and the server so even if someone is able to intercept the traffic he won't be able to see you passwords, website content ... the SSL encryption is configured at the virtual host level
# '''Certificat generation with Openssl (selfsigned)'''
<source lang="bash">
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 3650
</source>

You can also add -nodes if you don't want to protect your private key with a passphrase, otherwise it will prompt you for "at least a 4 character" password. The days parameter (3650) you can replace with any number to affect expiration date. It will then prompt you for things like "Country Name" but you can just hit enter and accept defaults.

Add -subj '/CN=localhost' to suppress questions about the contents of the certificate (replace localhost with your desired domain)

Self-signed certs are not validated with any third party unless you import them to the browsers previously. If you need more security, you should use a certificate signed by a trusted CA like let's encrypt (free), globalsign, Norton ...

# '''Certificat generation with Let's encrypt'''
# '''Configuration of the virtual host'''
# '''Let's encrypt certificate renewal'''

=Advanced setup=
# '''virtualisation'''
# '''LXC container'''
# '''Docker'''
# '''pfSense'''

Generic website infrastructure setup

2018-10-09T18:47:42Z

Delcroip:

This pages aims to provide links toward other reliable sources, to understand the different topics it's important to understand the principle that internet use.

1. Internet is an IP network, meaning that to reach every server an IP is required

2. When a name is used to reach a server, this name need to be translated to an IP by a Domain name server (DNS)

3. Your network use a private range of IP address therefore can't be reached from internet without a specific configuration

=Domain, Domain name server (DNS) and DynDNS=
Wikipedia[https://fr.wikipedia.org/wiki/Domain_Name_System]:
A DNS is important when you want to reach your server from internet because you don't want to learn your IP by heart, you'd rather buy a domain like mycompany.org and use it to reach your server. When you type "www.mydomain.com" in a browser, your computer will call the default DNS; if this DNS doesn't know the IP attached to mycompany.org it will check with other DNS until it gets the answer, sometime www.mycompany.org can refers to another domain like datacenter1.mycompany.org, if it the case the DNS will look for the IP attached to datacenter1.mycompany.org.

When you own a domain, you also own all the sub-domain like www.mycompany.org, erp.mycompany.org, yyy.xxx.mycompany.org ...; you can map this domain and its sub.domain to either an IP or another domain usually with the company that sold you the domain, here the main type that you will have to configure on the domain vendor portal:
# "CNAME" record: used to map to another domain
# "A" record: use to map an IP v4
# "AAAA" record: use to map an IP v6
# In case you don't own a fixed IP you can use a Dynamic DNS[https://en.wikipedia.org/wiki/Dynamic_DNS] service: there is a daemon runing on your network that will keep updating your IP in the DNS (usually the internet modem/gateway have this funciton). Often you will have to configure a dynamic DNS username and password on your domain vendor portal.

Here the example for OVH: https://docs.ovh.com/gb/en/domains/web_hosting_how_to_edit_my_dns_zone/

=Port Forwarding, DMZ and Reverse Proxy=
Once your Domain/subdomain refers to your IP address, Internet requests will arrive to your internet gateway but you'll need to setup port forwarding[https://en.wikipedia.org/wiki/Port_forwarding] in order to forward those requests toward your web server.

The default internet port are 80 for http and 443 for https, once the portforwarding is configured for those port (80 & 443) it'll affect all the web traffics coming on this port. A simple port forwarding will work if you have a single web server (could host serveral websites) but if you have multiple web servers you may have to forward your traffic to a reverse proxy[https://en.wikipedia.org/wiki/Reverse_proxy] that will be able to redirect the traffic based on the domain/subdomain or/and url.

If you want to be sure that internet traffic can't reach the other device on your network (LAN), you can place the reverse proxy in a DMZ[https://en.wikipedia.org/wiki/DMZ_(computing)] with firewall rules that allow only the traffic from internet to the reverse proxy and from the reverse proxy to specific IP on your local LAN (ie. your servers) but the firewall will block all other traffic coming from internet. For such setup there is an open source security appliance called pfSense that is able to do the firewall and the reverse proxy (with the module called HAProxy), pfSense can be installed on an old Pc or deployed on a virtual machine.

=Virtual host=
Virtual host [https://en.wikipedia.org/wiki/Virtual_hosting] is a configuration file that aim to define a configuration of the web server (e.g Apache) based on the domain/Url called by the user's browser; for instance a virtual host configuration can be setup for
# www.mycompnay.org, the configuration file will define where to look for the pages like /usr/share/mangento/myshop
# cloud.mycompany.org, the configuration file can define a reverse proxy to redirect the traffic to http://localhost:8888 in order to show the nextcloud pages
# dolibarr.mycompny.og, the configuration file could be the one of Dolibarr [https://github.com/Dolibarr/dolibarr/blob/develop/build/debian/apache/dolibarr.conf]

=SSL encryption=
The SSL encryption enable the encrypt the traffic between the user web browser and the server so even if someone is able to intercept the traffic he won't be able to see you passwords, website content ... the SSL encryption is configured at the virtual host level
# Certificat generation with Openssl (selfsigned)
# Certificat generation with Let's encrypt
# Configuration of the virtual host
# Let's encrypt certificate renewal

=Advanced setup=
# virtualisation
# LXC container
# Docker
# pfSense

Generic website infrastructure setup

2018-10-09T18:45:08Z

Delcroip:

This pages aims to provide links toward other reliable sources, to understand the different topics it's important to understand the principle that internet use.

1. Internet is an IP network, meaning that to reach every server an IP is required

2. When a name is used to reach a server, this name need to be translated to an IP by a Domain name server (DNS)

3. Your network use a private range of IP address therefore can't be reached from internet without a specific configuration

=Domain, Domain name server (DNS) and DynDNS=
Wikipedia[https://fr.wikipedia.org/wiki/Domain_Name_System]:
A DNS is important when you want to reach your server from internet because you don't want to learn your IP by heart, you'd rather buy a domain like mycompany.org and use it to reach your server. When you type "www.mydomain.com" in a browser, your computer will call the default DNS; if this DNS doesn't know the IP attached to mycompany.org it will check with other DNS until it gets the answer, sometime www.mycompany.org can refers to another domain like datacenter1.mycompany.org, if it the case the DNS will look for the IP attached to datacenter1.mycompany.org.

When you own a domain, you also own all the sub-domain like www.mycompany.org, erp.mycompany.org, yyy.xxx.mycompany.org ...; you can map this domain and its sub.domain to either an IP or another domain usually with the company that sold you the domain, here the main type that you will have to configure on the domain vendor portal:
# "CNAME" record: used to map to another domain
# "A" record: use to map an IP v4
# "AAAA" record: use to map an IP v6
# In case you don't own a fixed IP you can use a Dynamic DNS[https://en.wikipedia.org/wiki/Dynamic_DNS] service: there is a daemon runing on your network that will keep updating your IP in the DNS (usually the internet modem/gateway have this funciton). Often you will have to configure a dynamic DNS username and password on your domain vendor portal.

Here the example for OVH: https://docs.ovh.com/gb/en/domains/web_hosting_how_to_edit_my_dns_zone/

=Port Forwarding, DMZ and Reverse Proxy=
Once your Domain/subdomain refers to your IP address, Internet requests will arrive to your internet gateway but you'll need to setup port forwarding[https://en.wikipedia.org/wiki/Port_forwarding] in order to forward those requests toward your web server.

The default internet port are 80 for http and 443 for https, once the portforwarding is configured for those port (80 & 443) it'll affect all the web traffics coming on this port. A simple port forwarding will work if you have a single web server (could host serveral websites) but if you have multiple web servers you may have to forward your traffic to a reverse proxy[https://en.wikipedia.org/wiki/Reverse_proxy] that will be able to redirect the traffic based on the domain/subdomain or/and url.

If you want to be sure that internet traffic can reach the other device on your network (LAN), you can place the reverse proxy in a DMZ[https://en.wikipedia.org/wiki/DMZ_(computing)] with firewall rule that allow only the traffic from internet to the reverse proxy and from the reverse proxy to the local LAN (ie. your servers) but the firewall will block all other traffic coming from internet. For such setup there is an open source security appliance called pfSense that is able to do the firewall and the reverse proxy (with the module called HAProxy), pfSense can be installed on an old Pc or deployed on a virtual machine

=Virtual host=
Virtual host [https://en.wikipedia.org/wiki/Virtual_hosting] is a configuration file that aim to define a configuration of the web server (e.g Apache) based on the domain/Url called by the user's browser; for instance a virtual host configuration can be setup for
# www.mycompnay.org, the configuration file will define where to look for the pages like /usr/share/mangento/myshop
# cloud.mycompany.org, the configuration file can define a reverse proxy to redirect the traffic to http://localhost:8888 in order to show the nextcloud pages
# dolibarr.mycompny.og, the configuration file could be the one of Dolibarr [https://github.com/Dolibarr/dolibarr/blob/develop/build/debian/apache/dolibarr.conf]

=SSL encryption=
The SSL encryption enable the encrypt the traffic between the user web browser and the server so even if someone is able to intercept the traffic he won't be able to see you passwords, website content ... the SSL encryption is configured at the virtual host level
# Certificat generation with Openssl (selfsigned)
# Certificat generation with Let's encrypt
# Configuration of the virtual host
# Let's encrypt certificate renewal

=Advanced setup=
# virtualisation
# LXC container
# Docker
# pfSense

Generic website infrastructure setup

2018-10-08T18:52:52Z

Delcroip:

Créer un modèle de document PDF

2018-08-16T08:01:30Z

Delcroip: /* Créer le nouveau modèle */

{{TemplateDocDev}}
Ce document décrit comment créer son propre modèle de génération de document PDF afin de personnaliser ses documents (propales, factures, etc...)
Il se base sur les propositions commerciales comme exemple mais s'applique à tout type de document.

Pour savoir comment générer un modèle de document ODT, voir la page [[Créer un modèle de document ODT]].
Créer un modèle PDF requiert des connaissances en programmation PHP mais pas la création de modèles ODT.

= Prérequis =
* Dolibarr: 3.0+
* Connaissance en PHP

= Trouver le modèle existant le plus proche =
Dans Dolibarr, tester les modèles existants en allant dans la configuration du module puis en consultant l'aperçu en cliquant le picto "Aperçu" en fin de ligne du modèle. Consulter chacun des modèles disponibles.

Parmi ceux existant, noter le modèle le plus proche de vos besoins. Dans cet exemple, c'est le modèle azur (correspondant au fichier pdf_propale_azur.modules.php).

Pour info, tous les modèles sont dans '''htdocs/core/modules''' puis le sous-répertoire propale pour les propositions commerciales, facture pour les factures, commandes pour les commandes, etc...

= Créer le nouveau modèle =
Par sécurité, on conservera les modèles d'origine. Pour l'exemple, on part du principe qu'on crée un nouveau module de proposition commerciale qu'on nommera 'masocietebleu' et qui s'inspire du module 'azur':
* Copier-coller pdf_propale_azur.modules.php
* Renommer la copie en pdf_propale_masocietebleu.modules.php
* L'éditer et faire les modifs suivantes dans le code:
# Renommer 'Class pdf_propale_azur { ' en 'Class pdf_propale_masocietebleu { '
# Pour les anciennes versions de dolibarr (dans les nouvelles __construct($db) n'a pas besoin d'être renommé,)Renommer 'Function pdf_propale_azur($db=0)' en 'Function pdf_propale_masocietebleu($db=0)'
# Renommer la variable $this->name pour refléter le nouveau nom. Par exemple pour le modèle 'azur', changer la ligne '$this->name = "azur";' en '$this->name = "masocietebleu";'.
# Sauvegarder : le modèle 'masocietebleu' est disponible dans la liste des modèles de propales de Dolibarr
* Tester ce modèle (Voir chapitre précédent) avant d'aller plus loin...
* Ajouter dans la table llx_document_model le nouveau modéle que vous venez de créer

= Personnaliser votre nouveau modèle =
Personnaliser le modèle créé.
Toujours dans pdf_propale_masocietebleu.modules.php, chercher la fonction 'Function _pagehead(&$pdf, $fac)'. C'est elle qui gère l'affichage de l'entête.

== Librairie de manipulation de PDF ==
La librairie utilisée pour la création de documents en PDF se nomme TCPDF et peut être trouvée dans htdocs/includes/tcpdf/tcpdf.class.php. C'est également dans cette classe que l'on trouve les nombreuses méthodes utilisées pour générer les différents éléments des documents.

Les modèles eux-même instancient la classe FPDF et utilisent ensuite ses méthodes, combinées avec les données d'une facture, d'une commande ou d'autres types de données.

On retrouve généralement les appels suivants dans les scripts de création de documents:
* $pdf->SetFont() - ''Désigne la fonte à utiliser pour le texte qui suivra''
* $pdf->SetXY() - ''Désigne le point de départ pour dessiner le prochain texte en coordonnées X,Y qui sont exprimées en millimètres de la page''
* $pdf->MultiCell() - ''Dessine une boîte pouvant contenir du texte, et dont on doit d'abord donner la largeur et la hauteur - très utilisée''
* $pdf->GetY() - ''Renvoie la position courante en Y''
* $pdf->SetDrawColor() - ''Désigne la couleur à utiliser pour le prochain texte à écrire - généralement noir (0,0,0) ou blanc (255,255,255)''
* $pdf->Rect() - ''Dessine un rectangle dont le coin supérieur gauche est au point indiqué par les deux premiers paramètres et le coin inférieur droit utilise les deux derniers paramètres en mode relatif aux deux premiers''

== Structure des scripts ==
Les scripts de génération des documents PDF, au moment du développement de la version 2.2, disposent des méthodes suivantes (prenant pour exemple le modèle "crabe") au sein de la classe du nom du modèle:
* pdf_crabe() - ''Constructeur de l'objet pdf''
* write_pdf_file() - ''Méthode générale pour la génération du fichier. Cette méthode appelle toute les suivantes après avoir initialisé quelques variables''
* _pagehead() - ''Méthode de dessin de l'en-tête du document, incluant généralement le logo, le titre du document (et la date) ainsi que les cadres de l'émetteur et du destinataire du document''
* _tableau() - ''Méthode de dessin du tableau de détails (produits, services, etc)''
* _tableau_info() - ''Méthode de dessin du tableau reprenant une liste d'informations sur la facture''
* _tableau_tot() - ''Méthode de dessin du tableau des totaux''
* _tableau_versement() - ''Méthode de dessin du tableau des règles de versement''
* _pagefoot() - ''Méthode de dessin du pied de page''

== Example de personnalisation ==
=== Insertion d'un logo ===
* Ajouter l'instruction:
<source lang="php">
$pdf->Image('\www\htdocs\dolibarr\document\societe\logo.jpg', 10, 5, 60.00);
</source>
Avec dans l'exemple: 10=abscisse, 5=ordonnée, 60=largeur logo
* Si le logo se trouve par dessous ou dessus du text existant, supprimer le texte existant en commentant le code qui affiche l'information ou en modifiant sa position.

=== Insertion d'une signature ou autre en bas de page facture ===
* ouvrir le modèle à modifier crabe ou oursin (dans htdocs/core/modules/facture/)
* insérer (pour ma part ligne 618 juste avant // Show payment mode CHQ)
<source lang="php">
$pdf->Image('http://localhost/dolibarr/doc/images/signature.jpg',120,250,74);
</source>
l'image (largeur 74mm) est affichée colonne de droite juste avant le pied de page.
* copier l'image dans le répertoire. il semble qu'une image png avec transparence pose problème.
* générer le pdf, la signature apparaît.

=== Insertion de texte ===
Principales fonctions utilisées
<source lang="php">
$pdf->setX(float a); // fixe la position x courante
$pdf->setY(float b); // fixe la position y courante
$pdf->setXY(float a,float b); // fixe les positions x et y courantes
$pdf->SetTextColor(0,0,200); // fixe la couleur du texte
$pdf->SetFont('Arial','B',14); // fixe la police, le type ( 'B' pour gras, 'I' pour italique, '' pour normal,...)
$pdf->MultiCell(60, 8, 'Mon texte", 0, 'L'); // imprime 'Mon texte' avec saut de ligne
</source>
Rappel: l'origine des fonctions setXY est le coin supérieur gauche de la page

== Pour plus d'infos ==

* http://www.fpdf.org/?lang=fr
* Liste des méthodes: tcpdf.org/doc/code/classTCPDF.html
* Modèle facture poid [http://www.dolistore.com/lang-fr/crm-gestion-relation-client/208-Facture-avec-poids.html]. Module proposant un modéle de facture crabe avec une colonne poids en plus

= Activer son modèle dans Dolibarr =
Dans la fonction d'initialisation du module ajoutez votre modèle:

<source lang="php">
sql=array("INSERT INTO ".MAIN_DB_PREFIX."document_model (nom, type, entity) VALUES(".$MODELNAME.",".$MODEL_TARGET_MODULE.",".$conf->entity." )");
</source>

avant

<source lang="php"> return $this->_init($sql,$option);</source>

Puis

Dans Accueil => Configuration => Modules =>
* activer votre module qui doit apparaitre
* éventuellement le mettre en modèle proposé par défaut.

Créer un modèle de document PDF

2018-08-16T08:00:53Z

Delcroip: /* Créer le nouveau modèle */

{{TemplateDocDev}}
Ce document décrit comment créer son propre modèle de génération de document PDF afin de personnaliser ses documents (propales, factures, etc...)
Il se base sur les propositions commerciales comme exemple mais s'applique à tout type de document.

Pour savoir comment générer un modèle de document ODT, voir la page [[Créer un modèle de document ODT]].
Créer un modèle PDF requiert des connaissances en programmation PHP mais pas la création de modèles ODT.

= Prérequis =
* Dolibarr: 3.0+
* Connaissance en PHP

= Trouver le modèle existant le plus proche =
Dans Dolibarr, tester les modèles existants en allant dans la configuration du module puis en consultant l'aperçu en cliquant le picto "Aperçu" en fin de ligne du modèle. Consulter chacun des modèles disponibles.

Parmi ceux existant, noter le modèle le plus proche de vos besoins. Dans cet exemple, c'est le modèle azur (correspondant au fichier pdf_propale_azur.modules.php).

Pour info, tous les modèles sont dans '''htdocs/core/modules''' puis le sous-répertoire propale pour les propositions commerciales, facture pour les factures, commandes pour les commandes, etc...

= Créer le nouveau modèle =
Par sécurité, on conservera les modèles d'origine. Pour l'exemple, on part du principe qu'on crée un nouveau module de proposition commerciale qu'on nommera 'masocietebleu' et qui s'inspire du module 'azur':
* Copier-coller pdf_propale_azur.modules.php
* Renommer la copie en pdf_propale_masocietebleu.modules.php
* L'éditer et faire les modifs suivantes dans le code:
# Pour les anciennes versions de dolibarr (dans les nouvelles __construct($db) n'a pas besoin d'être renomé ), Renommer 'Class pdf_propale_azur { ' en 'Class pdf_propale_masocietebleu { '
# Renommer 'Function pdf_propale_azur($db=0)' en 'Function pdf_propale_masocietebleu($db=0)'
# Renommer la variable $this->name pour refléter le nouveau nom. Par exemple pour le modèle 'azur', changer la ligne '$this->name = "azur";' en '$this->name = "masocietebleu";'.
# Sauvegarder : le modèle 'masocietebleu' est disponible dans la liste des modèles de propales de Dolibarr
* Tester ce modèle (Voir chapitre précédent) avant d'aller plus loin...
* Ajouter dans la table llx_document_model le nouveau modéle que vous venez de créer

= Personnaliser votre nouveau modèle =
Personnaliser le modèle créé.
Toujours dans pdf_propale_masocietebleu.modules.php, chercher la fonction 'Function _pagehead(&$pdf, $fac)'. C'est elle qui gère l'affichage de l'entête.

== Librairie de manipulation de PDF ==
La librairie utilisée pour la création de documents en PDF se nomme TCPDF et peut être trouvée dans htdocs/includes/tcpdf/tcpdf.class.php. C'est également dans cette classe que l'on trouve les nombreuses méthodes utilisées pour générer les différents éléments des documents.

Les modèles eux-même instancient la classe FPDF et utilisent ensuite ses méthodes, combinées avec les données d'une facture, d'une commande ou d'autres types de données.

On retrouve généralement les appels suivants dans les scripts de création de documents:
* $pdf->SetFont() - ''Désigne la fonte à utiliser pour le texte qui suivra''
* $pdf->SetXY() - ''Désigne le point de départ pour dessiner le prochain texte en coordonnées X,Y qui sont exprimées en millimètres de la page''
* $pdf->MultiCell() - ''Dessine une boîte pouvant contenir du texte, et dont on doit d'abord donner la largeur et la hauteur - très utilisée''
* $pdf->GetY() - ''Renvoie la position courante en Y''
* $pdf->SetDrawColor() - ''Désigne la couleur à utiliser pour le prochain texte à écrire - généralement noir (0,0,0) ou blanc (255,255,255)''
* $pdf->Rect() - ''Dessine un rectangle dont le coin supérieur gauche est au point indiqué par les deux premiers paramètres et le coin inférieur droit utilise les deux derniers paramètres en mode relatif aux deux premiers''

== Structure des scripts ==
Les scripts de génération des documents PDF, au moment du développement de la version 2.2, disposent des méthodes suivantes (prenant pour exemple le modèle "crabe") au sein de la classe du nom du modèle:
* pdf_crabe() - ''Constructeur de l'objet pdf''
* write_pdf_file() - ''Méthode générale pour la génération du fichier. Cette méthode appelle toute les suivantes après avoir initialisé quelques variables''
* _pagehead() - ''Méthode de dessin de l'en-tête du document, incluant généralement le logo, le titre du document (et la date) ainsi que les cadres de l'émetteur et du destinataire du document''
* _tableau() - ''Méthode de dessin du tableau de détails (produits, services, etc)''
* _tableau_info() - ''Méthode de dessin du tableau reprenant une liste d'informations sur la facture''
* _tableau_tot() - ''Méthode de dessin du tableau des totaux''
* _tableau_versement() - ''Méthode de dessin du tableau des règles de versement''
* _pagefoot() - ''Méthode de dessin du pied de page''

== Example de personnalisation ==
=== Insertion d'un logo ===
* Ajouter l'instruction:
<source lang="php">
$pdf->Image('\www\htdocs\dolibarr\document\societe\logo.jpg', 10, 5, 60.00);
</source>
Avec dans l'exemple: 10=abscisse, 5=ordonnée, 60=largeur logo
* Si le logo se trouve par dessous ou dessus du text existant, supprimer le texte existant en commentant le code qui affiche l'information ou en modifiant sa position.

=== Insertion d'une signature ou autre en bas de page facture ===
* ouvrir le modèle à modifier crabe ou oursin (dans htdocs/core/modules/facture/)
* insérer (pour ma part ligne 618 juste avant // Show payment mode CHQ)
<source lang="php">
$pdf->Image('http://localhost/dolibarr/doc/images/signature.jpg',120,250,74);
</source>
l'image (largeur 74mm) est affichée colonne de droite juste avant le pied de page.
* copier l'image dans le répertoire. il semble qu'une image png avec transparence pose problème.
* générer le pdf, la signature apparaît.

=== Insertion de texte ===
Principales fonctions utilisées
<source lang="php">
$pdf->setX(float a); // fixe la position x courante
$pdf->setY(float b); // fixe la position y courante
$pdf->setXY(float a,float b); // fixe les positions x et y courantes
$pdf->SetTextColor(0,0,200); // fixe la couleur du texte
$pdf->SetFont('Arial','B',14); // fixe la police, le type ( 'B' pour gras, 'I' pour italique, '' pour normal,...)
$pdf->MultiCell(60, 8, 'Mon texte", 0, 'L'); // imprime 'Mon texte' avec saut de ligne
</source>
Rappel: l'origine des fonctions setXY est le coin supérieur gauche de la page

== Pour plus d'infos ==

* http://www.fpdf.org/?lang=fr
* Liste des méthodes: tcpdf.org/doc/code/classTCPDF.html
* Modèle facture poid [http://www.dolistore.com/lang-fr/crm-gestion-relation-client/208-Facture-avec-poids.html]. Module proposant un modéle de facture crabe avec une colonne poids en plus

= Activer son modèle dans Dolibarr =
Dans la fonction d'initialisation du module ajoutez votre modèle:

<source lang="php">
sql=array("INSERT INTO ".MAIN_DB_PREFIX."document_model (nom, type, entity) VALUES(".$MODELNAME.",".$MODEL_TARGET_MODULE.",".$conf->entity." )");
</source>

avant

<source lang="php"> return $this->_init($sql,$option);</source>

Puis

Dans Accueil => Configuration => Modules =>
* activer votre module qui doit apparaitre
* éventuellement le mettre en modèle proposé par défaut.

Module development

2018-05-19T12:30:33Z

Delcroip:

[[Category:Core]]
{{TemplateDocDevEn}}

To create a new module/addon for Dolibarr, there is several steps. This tutorial will describe you each of them to build a module to extend Dolibarr features, like one or several of the following :
* Add new tables in database
* Add your own menu entries
* Add new screens to edit new tables
* Add or remove tabs on object view (invoice, product, order, event, ...)
* Add predefined exports for the internal export tool
* Add new information boxes in the home page
* Add new substitutions variables
* Define new permissions
* Execute code automatically triggered by a particular Dolibarr action
* Insert your code inside Dolibarr hooks positions
* Add your numbering module
* Add a new document template
* Add a new skin
etc...
All those operations are possible with version 3.2 or more of Dolibarr.

Following chapters presents how to do all of this manually with an easy way. For experienced developers, a method to do this using MDA generation is also on the work. See last chapter for this.

=Module creation witht the module builder=
From Dolibarr 7.0.0 it is possible create the main pages of yout module with the module builder, to activate it you must set the MAIN_FEATURES_LEVEL to 2 ( Setup / Other ) and then clic on the bug near the print button (top right)

=Example of Template External Module=
A good model to start development of external module can be found here : [https://github.com/Dolibarr/dolibarr/tree/develop/htdocs/modulebuilder/template GitHub Dolibarr Module Modèle]

=Create your module =
== Create a Module descriptor for your Module (required) ==
'''When it is required''': Required as soon as an addon is developed, whatever its goal is (except for adding a skin).

'''Since Dolibarr 6.0, you should use the ModuleBuilder module provided as standard module'''

=== Create your module descriptor ===
The first step is to create a file descriptor for the module.
* Create directory '''/htdocs/''mymodule''/core/modules'''. Then copy the file modMyModule.class.php from the directory dev/skeletons into this directory '''htdocs/''mymodule''/core/modules'''. Change the name of the file modMyModule.class.php to the name corresponding to the purpose of your module. Name of the file must start with initial 'mod' and end with .class.php (for example if you want to give the name 'NewName' to this file, then the name should be 'modNewName.class.php').
Next modify the contents of this file as follows:
* Replace all "modMyModule" with a value which corresponds to the purpose of your module. This value must always start with 'mod' and contain only alpha characters (again, if the name given to the file was 'NewName', then replace all "modMyModule" with "modNewName").
* Change the number in: $this->numero = 100000 by a number that designates your module id. To avoid conflicts with other modules, you can consult the page that lists already reserved id numbers: [[List of modules id|List of modules id]].
* Modify any other variables defined in the constructor (see comment in the code skeleton for their meaning).
Your file descriptor for your module is ready. See next step to activate it.

=== Test your descriptor ===

Launch Dolibarr and go to page '''Setup->module'''?
If you set the property version in the module description you should see a new line with your new module and the possibility to activate it or not. If you set the property version to "develop" or "experiental", to see your module, you must first go into '''Setup-Others''' and set MAIN_FEATURES_LEVEL to 1 to see "experimental" modules or 2 to see "development" modules.

== Tree of path for new module files (required) ==
This is how your files must be organized when building a new module (the zip file must also match this rule).
Note: Only second line is mandatory.

{{TemplateModuleTreeSimple}}

== Create your SQL tables and the PHP DAO class (optional) ==
'''When''': If your module needs to manage data of its own

=== Create your .sql file ===
If your module is designed to manage data of its own, which are not available in the standard version of Dolibarr, it is necessary to define SQL tables to store the data.

Scripts for creating tables and load data for your own module must be placed in a directory: Create a subdirectory called "sql" into directory of your module (eg htdocs/mymodule/sql) to put the sql scripts that you will create.

Then check into your descriptor file, into function '''init''' that the line

<source lang="php">$this->_load_tables('/mymodule/sql/');</source>

is not commented.

''Rules to follow:''
* Add the files about creating tables commands on the principle of a file '''llx_matable.sql''' per table, with a possibly file '''llx_matable.key.sql''' (see existing files in '''install/mysql/tables''' for examples).

* To manage data, you must create a file called '''data.sql''' inside directory '''/mymodule/sql/''' that contains SQL command to add/edit/delete data.
* Don't use the double quote for strings (eg 'chaine' not "chaine") because the double quote have a specific meaning in PostGreSQL
Example of content of a file data.sql
<source lang="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__');
</source>

Files must be operational for the database mysql. Rem: The files of other databases are not maintained. They will be read and converted on the fly by the driver of the other database.

=== Test your .sql files ===

Once the files ready, you can return to Dolibarr to disable the module, drop those tables in database and reactivate the module. The tables should be recreated by the activation of the module. If this is not the case, check your scripts by passing them by hand, or check the Dolibarr logs.

=== Generate the PHP DAO class ===
Once you have created your tables into the database, move to the dev/skeletons directory and run the script

<source lang="bash">php build_class_from_table.php tablename modulename</source>
Note: If the command does not work, try to use php-cli php instead.

This will generate a file '''out.tablename.class.php''' that contains the class to manage table tablename.
In this class, you can find the CRUD methods (Create / Read / Update / Delete) already working to do an insert, a fetch (select), an update, a delete of a row in table.
Remove just the "out" from the file name and put the file in a subdirectory of '''htdocs''' specific to your module (in htdocs/mymodule for example).

A file '''out.tablename_script.php''' has been generated and contains a sample code to use the class for each of the 4 CRUD methods.

'''Since Dolibarr 6.0, the file dev/skeletons/build_class_from_table.php is no more provided. To build a class from a table you should use the ModuleBuilder modules provided as standard module.'''

== The tab management (optional) ==

=== Add or remove your own tabs on object sheets ===
'''When''': To add a tab on an object (invoices, orders, proposals, member ...)

To do this go into the file descriptor of module previously created and edit the $this->tabs array:

<source lang="php">
// Array to add new pages in new tabs or remove existing one
$this->tabs = array('objecttype:+tabname1:Title1:mylangfile@mymodule:$user->rights->mymodule->read:/mymodule/mypagetab1.php?id=__ID__' // To add a new tab identified by code tabname1
'objecttype:+tabname2:Title2:mylangfile@mymodule:$user->rights->mymodule->read:/mymodule/mypagetab2.php?id=__ID__', // To add a new tab identified by code tabname2
'objecttype:-tabname'); // To remove an existing tab identified by code tabname
</source>

The table should contain a list of strings, each string representing a new tab.
The format of the string consisting of 5 parts separated by ":"
* Part 1: The element type (objecttype) where the tab should appear is a value from the following:
{{TemplateModuleTabs}}
* Part 2: A code to identify tab to add (start with +) or to remove (start with -)
* Part 3: The title of the tab. This can be a hard read or better code translation in a file lang.
* Part 4: The name of the file "*.lang" which contains correspondence between the code translation and language to display. If this name is followed with @mymodule, Dolibarr will search translation file "*.lang" within the module, so htdocs/mymodule/langs/code_CODE/mylangfile.lang, otherwise Dolibarr will look for file htdocs/langs/code_CODE/mylangfile.lang
* Part 5: A condition to test if tab must be visible. Put 1 to be always visible.
* Part 6: The url of the page to display when you click on the tab. The __ID__ string will be replaced automatically by the Id of the element concerned.

To feed the contents of the tab with data from the database, see the next chapter.

=== Show tabs navigation into your own pages ===
'''When''': To show all standard tabs of an object (produit, tiers, etc.) on your page.

You must follow these steps :

'''1. Include files you need into your file'''

For each object type, there are two files to include with line
<source lang="php">require_once($url_fichier) ;</source>

This is example of files to include (DOL_DOCUMENT_ROOT is often dolibarr/htdocs/) :
* Object thirdparty (thirdparty) :
** DOL_DOCUMENT_ROOT/societe/class/societe.class.php
** DOL_DOCUMENT_ROOT/core/lib/company.lib.php
* Object product (product) :
** DOL_DOCUMENT_ROOT/product/class/product.class.php
** DOL_DOCUMENT_ROOT/core/lib/product.lib.php
* Object invoice (invoice) :
** DOL_DOCUMENT_ROOT/compta/facture/class/facture.class.php
** DOL_DOCUMENT_ROOT/core/lib/invoice.lib.php
...

'''2. Create and load the object to show into your tab'''

Create instance of object of the correct class and load object from database by using the fetch method of object en providing to this method the id you get from url (ie : /mytab.php?id=1).

''Example :''
<source lang="php">
$id=GETPOST('id','int');
$ref=GETPOST('ref','alpha');
$product = new Product($db) ;
$result = $product->fetch($id,$ref) ; // Test $result to check the database read is ok
</source>

'''3. Get list of all tabs to show for your object type'''

Use fonction XXX_prepare_head($obj), where XXX is name of object. This will return an array with all definition of tab entries to show. Parameter to put into this method is the instance of object you want tabs.

The resulting array has the following structure
<source lang="php">
$head // Array of tabs
$head[$h] // Element to describe one tab.
$head[$h][0] // Url of page to show when you click on tab
$head[$h][1] // Title of tab
$head[$h][2] // Code name to identify the tab
</source>

''Example :''
<source lang="php">
$head = product_prepare_head($product, $user) ; // parameter $user is present for some function anly
</source>

'''4. show tabs into your page'''

Use function dol_fiche_head() to show all tabs defined into array $head returned by XX_prepare_head().

<source lang="php">
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 // Title to show (shown into a special tab that you can't click)
//$notab
//$picto // Name of image to show into title. Possible values are:
// product
// service
// company
</source>

This function will show required tabs and open an html element ''< div class="" >'' that correspond to the area under the tabs. To close area of a tab, just use ''< /div >'' into your PHP page.

== Create or modify PHP screens (optional) ==
'''When''': If the purpose of your module is to add features that require new or modified screens.

=== Create a new PHP screen ===
You must then create your PHP pages that will show/edit data from tables using the skeleton templates provided as an example in the directory '''modulebuilder/myobject_page.php''' (For the development of a script from the command line, see [[Script development]]).

To create a new user screen, create a subdirectory of '''htdocs''' (if not already done) for your module (in '''htdocs/mymodule''' for example) to store the pages you will create.

Copy, into that directory, the file '''myobject_page.phpp''' that will serve as a starting point for your page file.
Edit the file to have a correct relative path to the main.inc.php file.
<source lang="php">
// Load Dolibarr environment
$res=0;
// Try main.inc.php into web root known defined into CONTEXT_DOCUMENT_ROOT (not always defined)
if (! $res && ! empty($_SERVER["CONTEXT_DOCUMENT_ROOT"])) $res=@include($_SERVER["CONTEXT_DOCUMENT_ROOT"]."/main.inc.php");
// Try main.inc.php into web root detected using web root caluclated from SCRIPT_FILENAME
$tmp=empty($_SERVER['SCRIPT_FILENAME'])?'':$_SERVER['SCRIPT_FILENAME'];$tmp2=realpath(__FILE__); $i=strlen($tmp)-1; $j=strlen($tmp2)-1;
while($i > 0 && $j > 0 && isset($tmp[$i]) && isset($tmp2[$j]) && $tmp[$i]==$tmp2[$j]) { $i--; $j--; }
if (! $res && $i > 0 && file_exists(substr($tmp, 0, ($i+1))."/main.inc.php")) $res=@include(substr($tmp, 0, ($i+1))."/main.inc.php");
if (! $res && $i > 0 && file_exists(dirname(substr($tmp, 0, ($i+1)))."/main.inc.php")) $res=@include(dirname(substr($tmp, 0, ($i+1)))."/main.inc.php");
// Try main.inc.php using relative path
if (! $res && file_exists("../main.inc.php")) $res=@include("../main.inc.php");
if (! $res && file_exists("../../main.inc.php")) $res=@include("../../main.inc.php");
if (! $res && file_exists("../../../main.inc.php")) $res=@include("../../../main.inc.php");
if (! $res) die("Include of main fails");
</source>
Note that you may add more "../" depending on the depth of the file relative to your module directory tree.
The modules developed for all version of Dolibarr after the 3.2 should be able to be moved in a different folder than "htdocs", like "htdocs/custom", without having to modify the source code of the module, that's why we make several includes, so this rule must be applied by all modules.

It's in the main.inc.php file that is loaded technical environment variables and permissions. The following variables are objects positioned in this file:

* $user Objet that contains the characteristics of the user + his permissions.
* $conf Objet that contains Dolibarr configuration.
* $db Objet that contains an opened connection handler to the database.
* $langs Objet that contains the user's language.

Then enter your code to display the page.

* To include a class or library dedicated to the module is done using a Dolibarr function (and not using directly include_once):
''Example :''
<source lang="php">
dol_include_once('/mymodule/class/myclass.class.php', 'MyClass');
</source>

* To include classes provided with Dolibarr, use the following syntax:
''Example :''
<source lang="php">
require_once DOL_DOCUMENT_ROOT.'/core/class/doli.class.php';
</source>

=== Add some fields into existing forms ===
You may want to provide a module that add more fields into forms (input and view) of some elements.

A heavy solution (but not so bad) may be to replace all pages used to create element (this means disable the "New element" menu entry and adding yours, and disable tab that show element to replace with a tab that is your own full page (copied/pasted from original) to do same than original page but modified to add your fields and stored added data into your own table). Go to menu [[#Define your entries in menu (optional)]] and [[#The tab management (optional)]] if this solution suits you (this solution is more powerfull since you can change everything you want into page).

We will describe here another solution, that works only to "add fields" at end of existing fields, using the element "category" as an example but you can convert this tutorial for invoice, proposal ...
* First thing is to add a table, owned by your module, to store value of new fields. This table will have only one column called "rowid" (will contains same value than field rowid of element table) + one column for each new field you want to add. Then create a class with CRUD (Create/Read/Update/Delete) methods for this new table. For this two tasks, go back to previous chapter [[#Create your SQL tables and the PHP DAO class]].
* Next step is to add a hook into your module to add the new fields into the form. See chapter [[Hooks_system#Implement_the_Hook]] for generic documentation to use hooks.
If you follow this tutorial, to be able to add fields into category forms, you must do:
{{ToComplete}}

=== Replace parts of screen that are templated (version 3.3+) ===
Some parts of Dolibarr screen are isolated into native PHP template files.
You can develop a module to overwrite such templates with yours.
{{ToComplete}}

=== Add/replace part of fields supported by hooks ===
See chapter [[Hooks_system#Implement_the_Hook]] to know how to use Dolibarr existing hooks to add/replace code at Dolibarr hooks place.

=== Database access ===
If you need to edit some data in database inside you own table, use the PHP class generated before.

If you to make access to tables with no dedicated PHP class available, this is always possible (for example if you want to get a list of records with a particular join or filter). In this case, this is a code samples to follow:

To make an insert, update or delete:

<source lang="php">
$db->begin(); // Start transaction
$db->query("My SQL request insert, update or delete");
$db->commit(); // Validate transaction
or $db->rollback() // Cancel transaction
</source>

To read:

<source lang="php">
$resql=$db->query("My select request");
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++;
}
}
}
</source>

=== Define style of your pages ===
To have the look of your own pages to match the Dolibarr theme, it is necessary to use the Dolibarr CSS styles.

You can use for example:

* class="'''liste_titre'''" on tags ''tr'' and ''td'' for the head row of a table.
* class="'''pair'''" or class="'''impair'''" on tags ''tr'' and ''td'' of other rows of a table.
* class="'''flat'''" on all input fields (''input, select, textarea''...).
* class="'''button'''" on HTML fields with type ''input type="submit"''.

=== Use the Dolibarr date picker ===
If you want to use the Dolibarr date selector (with its calendar popup) into your pages, use the following line:
<source lang="php">
$form=new Form($db);
$form->select_date('','mykey',0,0,0,"myform");
</source>
The string mykey will identify the date selector in the form. You must use different values if you use several date selectors in same page.
The string myform is the name of the FORM in which the selector is included (value found in the form name="myform" in HTML page).
This means a date selector must be included necessarily into an html FORM.

To get value after the POST of your form, the command is:
<source lang="php">
$mydate = dol_mktime(12, 0 , 0, $_POST['mykeymonth'], $_POST['mykeyday'], $_POST['mykeyyear']);
print strftime('%A %d %B %Y', $mydate);
</source>

== Add your own setup page (optional) ==
'''When''': If your module needs parameters, which are to be provided by the user, for proper setting up of the module.

=== Create your page to edit parameters ===
If your module needs several parameters to be setup, you must create a page to edit options (these options will be saved in the [[Table llx_const|table '''llx_const''']]).
Create a page named '''mymodule_setuppage.php''' that shows a form for possible options to update them into the above mentioned table.
It is necessary to take an example from a page of the directory '''/admin''' that will show you the way to read/save your parameters.
Put this PHP page into the directory '''/admin''' of your module (e.g. mymodule/admin/mymodule_setuppage.php).

=== Modify the descriptor file of your module ===
Then, within the descriptor file of your module, modify the variable '''config_page_url''' to set name of this PHP page.
If the page is in the directory '''admin/''', then the path is not required, e.g. like this:
<source lang="php">
$this->config_page_url = array("mymodule_setuppage.php");
</source>
If the page is in the directory '''mymodule/admin/''', then like this:
<source lang="php">
$this->config_page_url = array("mymodule_setuppage.php@mymodule");
</source>

=== Test your page ===
Go into page '''Home->Setup->Modules''', you should see a picture at the end of the line of your module to reach your setup page. Click on it, you should be able to view/edit parameters from your page.

== Define your entries in menu (optional) ==
'''When''': If you have created PHP pages, it is necessary that those pages can be reached from menu entries in Dolibarr menu.

=== Define your menu entries ===
For this, you must define into the module descriptor, the array this->menu that declare all menus added by your module.
This array contains entries that will appear once your module is activated.
The example module descriptor file '''modMyModule.class.php''' contains an example to declare a top menu and also its left menu entries.

This is the example of code to declare your own menu entries in a module descriptor file:
<source lang="php">
// 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( 'fk_menu'=>0, // Put 0 if this is a top menu
'type'=>'top', // This is a Top menu entry
'titre'=>'MyModule top menu',
'mainmenu'=>'mymodule',
'leftmenu'=>'mymodule',
'url'=>'/mymodule/pagetop.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'=>'',
'user'=>2); // 0=Menu for internal users, 1=external users, 2=both
$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 of parent menu
'type'=>'left', // This is a Left menu entry
'titre'=>'MyModule left menu 1',
'mainmenu'=>'xxx',
'leftmenu'=>'yyy',
'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'=>'',
'user'=>2); // 0=Menu for internal users,1=external users, 2=both
$r++;
</source>

To show menu or not depending on a permission, modify property '''perms''' in array. See chapter on permissions later to see how to add permissions.

=== Test your menu entries ===
Disable and reenable your module under Dolibarr module setup page, menus entries must appear (if property 'enabled' is declaration array is ok).

== Add your own permissions (optional) ==
'''When''': If you want to add new permissions.

The way to define permissions that will manage your module is done inside the module descriptor created previously.
Modify line
<source lang="php">
$this->rights_class = 'mymodule'
</source>
with correct value for mymodule.

Then you must fill the array $this->rights with as many entries than different permissions you need to manage.

<source lang="php">
$this->rights[$r][0] = 10001;
$this->rights[$r][1] = 'Label by default of permission';
$this->rights[$r][3] = 1;
$this->rights[$r][4] = 'action';
$this->rights[$r][5] = 'subaction';
$r++;
</source>

Into $this->rights[$r][0], put a permission id not already used (See into menu '''System info''' on a working installation of Dolibarr to know list of id already used by standard modules.
Into $this->rights[$r][3], put 1 if this permission must be granted automatically by default to any new created user.
Into $this->rights[$r][1], put a label by default for permission (This label will be used if no translation can be found into the file '''admin.lang''').
Into $this->rights[$r][4] and $this->rights[$r][5], put an action and subaction string without spaces. You will be able to test if a user has the permission in your PHP source code with the sequence:

<source lang="php">
if ($user->rights->mymodule->action->subaction) ...
</source>

== Define you own box (optional) ==
'''When''': If your module need to provide one or several new boxes to show on home page.

=== Define your box ===
For this, modify the array $this->boxes into the module descriptor file.
All you have to do is to add 2 lines for each box file you will create into directory '''htdocs/mymodule/core/boxes'''

''Example:''
<source lang="php">
$this->boxes[0]['file']='mybox0.php@mymodule'
$this->boxes[0]['note']='My box 0'
...
$this->boxes[n]['file']='myboxn.php@mymodule'
$this->boxes[n]['note']='My box n'
</source>

Then create files '''htdocs/mymodule/core/boxes/mybox0.php''', '''htdocs/mymodule/core/boxes/mybox1.php'''... by copying an example from an existing box file (found into directory '''htdocs/core/boxes''').

=== Test if your box is detected by Dolibarr ===
Disable and enabled module.

Go into menu '''Home - Setup - Boxes'''.

Your boxes must appear in the list of boxes you can activated. Activate the box and go on home page to see if the box is showing correctly.

== Define your own export (optional) ==
'''When''': If your module provide new predefined database export profiles (for its own tables or for already existing tables of another module).

=== Define export ===
For this uncomment and modify arrays $this->export_xxx in your module descriptor file.

=== Test your export ===
Go into menu Tools -> Export. Your export will appear in the list of available predefined exports (if your module is enabled).
Choose it, you must see list of all possible fields defined in the export arrays.
Choose on field and try to build an export file. If ok, try again with all fields.

== Define your CSS styles (optional) ==
'''When''': If in your PHP pages, you use class styles that are not defined inside Dolibarr themes CSS (not recommanded).

=== Create and declare your style sheet ===
Create a style sheet CSS named '''mymodule.css''' or '''mymodule.css.php''' and put it into directory '''htdocs/mymodule'''. You can have only one CSS file per module.
Remember it's better to use existing styles already available by default into Dolibarr (The CSS file used by Dolibarr is file '''themes/mytheme/''themename''.css.php'''. Create your own CSS file only if you need absolutely to add not already existing styles.

Once your style sheet is ready, declare it into your module descriptor file by modifying the property '''$this->modules_parts'''.
Value to put here must be a relative URL to your CSS file.
For example
<source lang="php">
$this->module_parts = array('css' => array('/mymodule/css/mymodule.css.php'));
</source>

=== Test your style sheet ===
Disable and enable your module.

Go on home page (index.php). Show the HTML source of the page.

You should see into the HTML header, a line that declare your style sheet.

== Add your Javascript functions (optional) ==
'''When''': If in your PHP pages, you use javascript functions not available in Dolibarr (in file lib_head.js)

If you need to use your own javascript functions inside your PHP pages, it is necessary to have your functions, defined into your javascript file '''htdocs/mymodule/js/mymodule.js''', included into the HTML HEAD section.
To ask Dolibarr that forge this header to include your own javascript file, you must just provide it to the llxHeader() function called by your page.

Example for page /htdocs/mymodule/mypage.php :
<source lang="php">
$morejs=array("/mymodule/js/mymodule.js");
llxHeader('','Titre','','','','',$morejs,'',0,0);
</source>

== Run your own code on any Dolibarr event (optional) ==
'''When''': If you want to execute your own code once a common Dolibarr event has occurred (example: I want to update a table in my module when an invoice is created into Dolibarr), you must create a '''triggers'''.

See also [[Interfaces_Dolibarr_toward_foreign_systems]]
and [[Interfaces_from_foreign_systems_toward_Dolibarr]]

== Insert your code inside Dolibarr hooks positions (optional) ==
'''When''': When you want to add code or replace Dolibarr code into another situation than a business event (See previous chapter for adding code during a business event).

See page [[Hooks_system]].

== Add your own numbering rules ==
'''When''': When you need a new rule for generated ref of elements that is not covered by existing rules.

See page [[Create numbering module]].

== Add your document template (optional) ==
'''When''': When you want to personalized your own generated PDF or ODT documents.

Note: To add this feature you don't need to create a module descriptor.

Documentation to add your own template is available on page [[Create_a_PDF_document_template]] or [[Create_an_ODT_document_template]].

== Add your skin (optional) ==
'''When''': When you want to personalized your colors/fonts/images.

Note: To add this feature you don't need to create a module descriptor.

To add your own skin, read page [[Skins]].

=Some coding rules and predefined functions =
The coding rules to be followed are defined in the [[Developer documentation]], under section "General Information - Language and standards development".

A lot of predefined features for developers are also available and described into page [[Developer documentation]] under section "Technical components of Dolibarr".

=Using MDA =
A method to generate a functional module from a UML model has been developed. More information on the page [[UML2Dolibarr - Build a module using MDA]].

=Create a package to distribute and install your module =
This process must be used to generate a package to submit it on the http://www.dolistore.com market place.
But you can use it to have a package easy to distribute on your on network.

* Go into the directory '''/build''' and copy the file '''makepack-dolibarrmodules.conf''' into '''makepack-mymodule.conf'''. Warning, this directory may not be provided in some packages of stable versions. If so, it can be retrieved from the snapshot available for download on the Dolibarr website in area "Development version" (taken in this case the whole build directory which is autonomous and independent directory).

Edit this file to add list of file names for all new files you created for your module (module descriptor, new sql tables files, php page, images, etc...)

* Run the script via Perl (need the Perl version 5.0 or later):
<source lang="bash">
perl makepack-dolibarrmodule.pl
</source>
The script asks you the name of your module, its major and minor version. A file '''mymodule.zip ''' will then be manufactured containing your module ready to be deployed.

* The person who receives your module must then place the file in the root directory of a Dolibarr installation and perform the command:
<source lang="bash">
tar -xvf mymodule.zip
</source>

* If you want your module to be public, you can submit it (the zip file) on Dolibarr market place web site: {{LinkToPluginDownload}} (you must create an account first and be logged to use the link "Submit a module/product").
** If your module was build correctly, file will be validated later.
** If quality is enough and license permits it, code might be added inside main Dolibarr sources (except if you disagree for that).

= Enabling/activation condition of external module on DoliStore =

See [[Module_Dolistore_Validation_Rules|Validation Rules]]

Créer un modèle de document PDF

2018-05-06T09:50:38Z

Delcroip: /* Activer son modèle dans Dolibarr */

{{TemplateDocDev}}
Ce document décrit comment créer son propre modèle de génération de document PDF afin de personnaliser ses documents (propales, factures, etc...)
Il se base sur les propositions commerciales comme exemple mais s'applique à tout type de document.

Pour savoir comment générer un modèle de document ODT, voir la page [[Créer un modèle de document ODT]].
Créer un modèle PDF requiert des connaissances en programmation PHP mais pas la création de modèles ODT.

= Prérequis =
* Dolibarr: 3.0+
* Connaissance en PHP

= Trouver le modèle existant le plus proche =
Dans Dolibarr, tester les modèles existants en allant dans la configuration du module puis en consultant l'aperçu en cliquant le picto "Aperçu" en fin de ligne du modèle. Consulter chacun des modèles disponibles.

Parmi ceux existant, noter le modèle le plus proche de vos besoins. Dans cet exemple, c'est le modèle azur (correspondant au fichier pdf_propale_azur.modules.php).

Pour info, tous les modèles sont dans '''htdocs/core/modules''' puis le sous-répertoire propale pour les propositions commerciales, facture pour les factures, commandes pour les commandes, etc...

= Créer le nouveau modèle =
Par sécurité, on conservera les modèles d'origine. Pour l'exemple, on part du principe qu'on crée un nouveau module de proposition commerciale qu'on nommera 'masocietebleu' et qui s'inspire du module 'azur':
* Copier-coller pdf_propale_azur.modules.php
* Renommer la copie en pdf_propale_masocietebleu.modules.php
* L'éditer et faire les modifs suivantes dans le code:
# Renommer 'Class pdf_propale_azur { ' en 'Class pdf_propale_masocietebleu { '
# Renommer 'Function pdf_propale_azur($db=0)' en 'Function pdf_propale_masocietebleu($db=0)'
# Renommer la variable $this->name pour refléter le nouveau nom. Par exemple pour le modèle 'azur', changer la ligne '$this->name = "azur";' en '$this->name = "masocietebleu";'.
# Sauvegarder : le modèle 'masocietebleu' est disponible dans la liste des modèles de propales de Dolibarr
* Tester ce modèle (Voir chapitre précédent) avant d'aller plus loin...
* Ajouter dans la table llx_document_model le nouveau modéle que vous venez de créer

= Personnaliser votre nouveau modèle =
Personnaliser le modèle créé.
Toujours dans pdf_propale_masocietebleu.modules.php, chercher la fonction 'Function _pagehead(&$pdf, $fac)'. C'est elle qui gère l'affichage de l'entête.

== Librairie de manipulation de PDF ==
La librairie utilisée pour la création de documents en PDF se nomme TCPDF et peut être trouvée dans htdocs/includes/tcpdf/tcpdf.class.php. C'est également dans cette classe que l'on trouve les nombreuses méthodes utilisées pour générer les différents éléments des documents.

Les modèles eux-même instancient la classe FPDF et utilisent ensuite ses méthodes, combinées avec les données d'une facture, d'une commande ou d'autres types de données.

On retrouve généralement les appels suivants dans les scripts de création de documents:
* $pdf->SetFont() - ''Désigne la fonte à utiliser pour le texte qui suivra''
* $pdf->SetXY() - ''Désigne le point de départ pour dessiner le prochain texte en coordonnées X,Y qui sont exprimées en millimètres de la page''
* $pdf->MultiCell() - ''Dessine une boîte pouvant contenir du texte, et dont on doit d'abord donner la largeur et la hauteur - très utilisée''
* $pdf->GetY() - ''Renvoie la position courante en Y''
* $pdf->SetDrawColor() - ''Désigne la couleur à utiliser pour le prochain texte à écrire - généralement noir (0,0,0) ou blanc (255,255,255)''
* $pdf->Rect() - ''Dessine un rectangle dont le coin supérieur gauche est au point indiqué par les deux premiers paramètres et le coin inférieur droit utilise les deux derniers paramètres en mode relatif aux deux premiers''

== Structure des scripts ==
Les scripts de génération des documents PDF, au moment du développement de la version 2.2, disposent des méthodes suivantes (prenant pour exemple le modèle "crabe") au sein de la classe du nom du modèle:
* pdf_crabe() - ''Constructeur de l'objet pdf''
* write_pdf_file() - ''Méthode générale pour la génération du fichier. Cette méthode appelle toute les suivantes après avoir initialisé quelques variables''
* _pagehead() - ''Méthode de dessin de l'en-tête du document, incluant généralement le logo, le titre du document (et la date) ainsi que les cadres de l'émetteur et du destinataire du document''
* _tableau() - ''Méthode de dessin du tableau de détails (produits, services, etc)''
* _tableau_info() - ''Méthode de dessin du tableau reprenant une liste d'informations sur la facture''
* _tableau_tot() - ''Méthode de dessin du tableau des totaux''
* _tableau_versement() - ''Méthode de dessin du tableau des règles de versement''
* _pagefoot() - ''Méthode de dessin du pied de page''

== Example de personnalisation ==
=== Insertion d'un logo ===
* Ajouter l'instruction:
<source lang="php">
$pdf->Image('\www\htdocs\dolibarr\document\societe\logo.jpg', 10, 5, 60.00);
</source>
Avec dans l'exemple: 10=abscisse, 5=ordonnée, 60=largeur logo
* Si le logo se trouve par dessous ou dessus du text existant, supprimer le texte existant en commentant le code qui affiche l'information ou en modifiant sa position.

=== Insertion d'une signature ou autre en bas de page facture ===
* ouvrir le modèle à modifier crabe ou oursin (dans htdocs/core/modules/facture/)
* insérer (pour ma part ligne 618 juste avant // Show payment mode CHQ)
<source lang="php">
$pdf->Image('http://localhost/dolibarr/doc/images/signature.jpg',120,250,74);
</source>
l'image (largeur 74mm) est affichée colonne de droite juste avant le pied de page.
* copier l'image dans le répertoire. il semble qu'une image png avec transparence pose problème.
* générer le pdf, la signature apparaît.

=== Insertion de texte ===
Principales fonctions utilisées
<source lang="php">
$pdf->setX(float a); // fixe la position x courante
$pdf->setY(float b); // fixe la position y courante
$pdf->setXY(float a,float b); // fixe les positions x et y courantes
$pdf->SetTextColor(0,0,200); // fixe la couleur du texte
$pdf->SetFont('Arial','B',14); // fixe la police, le type ( 'B' pour gras, 'I' pour italique, '' pour normal,...)
$pdf->MultiCell(60, 8, 'Mon texte", 0, 'L'); // imprime 'Mon texte' avec saut de ligne
</source>
Rappel: l'origine des fonctions setXY est le coin supérieur gauche de la page

== Pour plus d'infos ==

* http://www.fpdf.org/?lang=fr
* Liste des méthodes: tcpdf.org/doc/code/classTCPDF.html
* Modèle facture poid [http://www.dolistore.com/lang-fr/crm-gestion-relation-client/208-Facture-avec-poids.html]. Module proposant un modéle de facture crabe avec une colonne poids en plus

= Activer son modèle dans Dolibarr =
Dans la fonction d'initialisation du module ajoutez votre modèle:

<source lang="php">
sql=array("INSERT INTO ".MAIN_DB_PREFIX."document_model (nom, type, entity) VALUES(".$MODELNAME.",".$MODEL_TARGET_MODULE.",".$conf->entity." )");
</source>

avant

<source lang="php"> return $this->_init($sql,$option);</source>

Puis

Dans Accueil => Configuration => Modules =>
* activer votre module qui doit apparaitre
* éventuellement le mettre en modèle proposé par défaut.

Créer un modèle de document PDF

2018-05-06T09:49:32Z

Delcroip: /* Activer son modèle dans Dolibarr */

{{TemplateDocDev}}
Ce document décrit comment créer son propre modèle de génération de document PDF afin de personnaliser ses documents (propales, factures, etc...)
Il se base sur les propositions commerciales comme exemple mais s'applique à tout type de document.

Pour savoir comment générer un modèle de document ODT, voir la page [[Créer un modèle de document ODT]].
Créer un modèle PDF requiert des connaissances en programmation PHP mais pas la création de modèles ODT.

= Prérequis =
* Dolibarr: 3.0+
* Connaissance en PHP

= Trouver le modèle existant le plus proche =
Dans Dolibarr, tester les modèles existants en allant dans la configuration du module puis en consultant l'aperçu en cliquant le picto "Aperçu" en fin de ligne du modèle. Consulter chacun des modèles disponibles.

Parmi ceux existant, noter le modèle le plus proche de vos besoins. Dans cet exemple, c'est le modèle azur (correspondant au fichier pdf_propale_azur.modules.php).

Pour info, tous les modèles sont dans '''htdocs/core/modules''' puis le sous-répertoire propale pour les propositions commerciales, facture pour les factures, commandes pour les commandes, etc...

= Créer le nouveau modèle =
Par sécurité, on conservera les modèles d'origine. Pour l'exemple, on part du principe qu'on crée un nouveau module de proposition commerciale qu'on nommera 'masocietebleu' et qui s'inspire du module 'azur':
* Copier-coller pdf_propale_azur.modules.php
* Renommer la copie en pdf_propale_masocietebleu.modules.php
* L'éditer et faire les modifs suivantes dans le code:
# Renommer 'Class pdf_propale_azur { ' en 'Class pdf_propale_masocietebleu { '
# Renommer 'Function pdf_propale_azur($db=0)' en 'Function pdf_propale_masocietebleu($db=0)'
# Renommer la variable $this->name pour refléter le nouveau nom. Par exemple pour le modèle 'azur', changer la ligne '$this->name = "azur";' en '$this->name = "masocietebleu";'.
# Sauvegarder : le modèle 'masocietebleu' est disponible dans la liste des modèles de propales de Dolibarr
* Tester ce modèle (Voir chapitre précédent) avant d'aller plus loin...
* Ajouter dans la table llx_document_model le nouveau modéle que vous venez de créer

= Personnaliser votre nouveau modèle =
Personnaliser le modèle créé.
Toujours dans pdf_propale_masocietebleu.modules.php, chercher la fonction 'Function _pagehead(&$pdf, $fac)'. C'est elle qui gère l'affichage de l'entête.

== Librairie de manipulation de PDF ==
La librairie utilisée pour la création de documents en PDF se nomme TCPDF et peut être trouvée dans htdocs/includes/tcpdf/tcpdf.class.php. C'est également dans cette classe que l'on trouve les nombreuses méthodes utilisées pour générer les différents éléments des documents.

Les modèles eux-même instancient la classe FPDF et utilisent ensuite ses méthodes, combinées avec les données d'une facture, d'une commande ou d'autres types de données.

On retrouve généralement les appels suivants dans les scripts de création de documents:
* $pdf->SetFont() - ''Désigne la fonte à utiliser pour le texte qui suivra''
* $pdf->SetXY() - ''Désigne le point de départ pour dessiner le prochain texte en coordonnées X,Y qui sont exprimées en millimètres de la page''
* $pdf->MultiCell() - ''Dessine une boîte pouvant contenir du texte, et dont on doit d'abord donner la largeur et la hauteur - très utilisée''
* $pdf->GetY() - ''Renvoie la position courante en Y''
* $pdf->SetDrawColor() - ''Désigne la couleur à utiliser pour le prochain texte à écrire - généralement noir (0,0,0) ou blanc (255,255,255)''
* $pdf->Rect() - ''Dessine un rectangle dont le coin supérieur gauche est au point indiqué par les deux premiers paramètres et le coin inférieur droit utilise les deux derniers paramètres en mode relatif aux deux premiers''

== Structure des scripts ==
Les scripts de génération des documents PDF, au moment du développement de la version 2.2, disposent des méthodes suivantes (prenant pour exemple le modèle "crabe") au sein de la classe du nom du modèle:
* pdf_crabe() - ''Constructeur de l'objet pdf''
* write_pdf_file() - ''Méthode générale pour la génération du fichier. Cette méthode appelle toute les suivantes après avoir initialisé quelques variables''
* _pagehead() - ''Méthode de dessin de l'en-tête du document, incluant généralement le logo, le titre du document (et la date) ainsi que les cadres de l'émetteur et du destinataire du document''
* _tableau() - ''Méthode de dessin du tableau de détails (produits, services, etc)''
* _tableau_info() - ''Méthode de dessin du tableau reprenant une liste d'informations sur la facture''
* _tableau_tot() - ''Méthode de dessin du tableau des totaux''
* _tableau_versement() - ''Méthode de dessin du tableau des règles de versement''
* _pagefoot() - ''Méthode de dessin du pied de page''

== Example de personnalisation ==
=== Insertion d'un logo ===
* Ajouter l'instruction:
<source lang="php">
$pdf->Image('\www\htdocs\dolibarr\document\societe\logo.jpg', 10, 5, 60.00);
</source>
Avec dans l'exemple: 10=abscisse, 5=ordonnée, 60=largeur logo
* Si le logo se trouve par dessous ou dessus du text existant, supprimer le texte existant en commentant le code qui affiche l'information ou en modifiant sa position.

=== Insertion d'une signature ou autre en bas de page facture ===
* ouvrir le modèle à modifier crabe ou oursin (dans htdocs/core/modules/facture/)
* insérer (pour ma part ligne 618 juste avant // Show payment mode CHQ)
<source lang="php">
$pdf->Image('http://localhost/dolibarr/doc/images/signature.jpg',120,250,74);
</source>
l'image (largeur 74mm) est affichée colonne de droite juste avant le pied de page.
* copier l'image dans le répertoire. il semble qu'une image png avec transparence pose problème.
* générer le pdf, la signature apparaît.

=== Insertion de texte ===
Principales fonctions utilisées
<source lang="php">
$pdf->setX(float a); // fixe la position x courante
$pdf->setY(float b); // fixe la position y courante
$pdf->setXY(float a,float b); // fixe les positions x et y courantes
$pdf->SetTextColor(0,0,200); // fixe la couleur du texte
$pdf->SetFont('Arial','B',14); // fixe la police, le type ( 'B' pour gras, 'I' pour italique, '' pour normal,...)
$pdf->MultiCell(60, 8, 'Mon texte", 0, 'L'); // imprime 'Mon texte' avec saut de ligne
</source>
Rappel: l'origine des fonctions setXY est le coin supérieur gauche de la page

== Pour plus d'infos ==

* http://www.fpdf.org/?lang=fr
* Liste des méthodes: tcpdf.org/doc/code/classTCPDF.html
* Modèle facture poid [http://www.dolistore.com/lang-fr/crm-gestion-relation-client/208-Facture-avec-poids.html]. Module proposant un modéle de facture crabe avec une colonne poids en plus

= Activer son modèle dans Dolibarr =
Dans la fonction d'initialisation du module ajoutez votre modèle:

<code>
sql=array("INSERT INTO ".MAIN_DB_PREFIX."document_model (nom, type, entity) VALUES(".$MODELNAME.",".$MODEL_TARGET_MODULE.",".$conf->entity." )");
</code>

avant

<code> return $this->_init($sql,$option);</code>

Puis

Dans Accueil => Configuration => Modules =>
* activer votre module qui doit apparaitre
* éventuellement le mettre en modèle proposé par défaut.

Module development

2018-02-12T12:24:02Z

Delcroip: /* Create your .sql file */

[[Category:Core]]
{{TemplateDocDevEn}}

To create a new module/addon for Dolibarr, there is several steps. This tutorial will describe you each of them to build a module to extend Dolibarr features, like one or several of the following :
* Add new tables in database
* Add your own menu entries
* Add new screens to edit new tables
* Add or remove tabs on object view (invoice, product, order, event, ...)
* Add predefined exports for the internal export tool
* Add new information boxes in the home page
* Add new substitutions variables
* Define new permissions
* Execute code automatically triggered by a particular Dolibarr action
* Insert your code inside Dolibarr hooks positions
* Add your numbering module
* Add a new document template
* Add a new skin
etc...
All those operations are possible with version 3.2 or more of Dolibarr.

Following chapters presents how to do all of this manually with an easy way. For experienced developers, a method to do this using MDA generation is also on the work. See last chapter for this.

=Example of Template External Module=
A good model to start development of external module can be found here : [https://github.com/Dolibarr/dolibarr/tree/develop/htdocs/modulebuilder/template GitHub Dolibarr Module Modèle]

=Create your module =
== Create a Module descriptor for your Module (required) ==
'''When it is required''': Required as soon as an addon is developed, whatever its goal is (except for adding a skin).

'''Since Dolibarr 6.0, you should use the ModuleBuilder module provided as standard module'''

=== Create your module descriptor ===
The first step is to create a file descriptor for the module.
* Create directory '''/htdocs/''mymodule''/core/modules'''. Then copy the file modMyModule.class.php from the directory dev/skeletons into this directory '''htdocs/''mymodule''/core/modules'''. Change the name of the file modMyModule.class.php to the name corresponding to the purpose of your module. Name of the file must start with initial 'mod' and end with .class.php (for example if you want to give the name 'NewName' to this file, then the name should be 'modNewName.class.php').
Next modify the contents of this file as follows:
* Replace all "modMyModule" with a value which corresponds to the purpose of your module. This value must always start with 'mod' and contain only alpha characters (again, if the name given to the file was 'NewName', then replace all "modMyModule" with "modNewName").
* Change the number in: $this->numero = 100000 by a number that designates your module id. To avoid conflicts with other modules, you can consult the page that lists already reserved id numbers: [[List of modules id|List of modules id]].
* Modify any other variables defined in the constructor (see comment in the code skeleton for their meaning).
Your file descriptor for your module is ready. See next step to activate it.

=== Test your descriptor ===

Launch Dolibarr and go to page '''Setup->module'''?
If you set the property version in the module description you should see a new line with your new module and the possibility to activate it or not. If you set the property version to "develop" or "experiental", to see your module, you must first go into '''Setup-Others''' and set MAIN_FEATURES_LEVEL to 1 to see "experimental" modules or 2 to see "development" modules.

== Tree of path for new module files (required) ==
This is how your files must be organized when building a new module (the zip file must also match this rule).
Note: Only second line is mandatory.

{{TemplateModuleTreeSimple}}

== Create your SQL tables and the PHP DAO class (optional) ==
'''When''': If your module needs to manage data of its own

=== Create your .sql file ===
If your module is designed to manage data of its own, which are not available in the standard version of Dolibarr, it is necessary to define SQL tables to store the data.

Scripts for creating tables and load data for your own module must be placed in a directory: Create a subdirectory called "sql" into directory of your module (eg htdocs/mymodule/sql) to put the sql scripts that you will create.

Then check into your descriptor file, into function '''init''' that the line

<source lang="php">$this->_load_tables('/mymodule/sql/');</source>

is not commented.

''Rules to follow:''
* Add the files about creating tables commands on the principle of a file '''llx_matable.sql''' per table, with a possibly file '''llx_matable.key.sql''' (see existing files in '''install/mysql/tables''' for examples).

* To manage data, you must create a file called '''data.sql''' inside directory '''/mymodule/sql/''' that contains SQL command to add/edit/delete data.
* Don't use the double quote for strings (eg 'chaine' not "chaine") because the double quote have a specific meaning in PostGreSQL
Example of content of a file data.sql
<source lang="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__');
</source>

Files must be operational for the database mysql. Rem: The files of other databases are not maintained. They will be read and converted on the fly by the driver of the other database.

=== Test your .sql files ===

Once the files ready, you can return to Dolibarr to disable the module, drop those tables in database and reactivate the module. The tables should be recreated by the activation of the module. If this is not the case, check your scripts by passing them by hand, or check the Dolibarr logs.

=== Generate the PHP DAO class ===
Once you have created your tables into the database, move to the dev/skeletons directory and run the script

<source lang="bash">php build_class_from_table.php tablename modulename</source>
Note: If the command does not work, try to use php-cli php instead.

This will generate a file '''out.tablename.class.php''' that contains the class to manage table tablename.
In this class, you can find the CRUD methods (Create / Read / Update / Delete) already working to do an insert, a fetch (select), an update, a delete of a row in table.
Remove just the "out" from the file name and put the file in a subdirectory of '''htdocs''' specific to your module (in htdocs/mymodule for example).

A file '''out.tablename_script.php''' has been generated and contains a sample code to use the class for each of the 4 CRUD methods.

'''Since Dolibarr 6.0, the file dev/skeletons/build_class_from_table.php is no more provided. To build a class from a table you should use the ModuleBuilder modules provided as standard module.'''

== The tab management (optional) ==

=== Add or remove your own tabs on object sheets ===
'''When''': To add a tab on an object (invoices, orders, proposals, member ...)

To do this go into the file descriptor of module previously created and edit the $this->tabs array:

<source lang="php">
// Array to add new pages in new tabs or remove existing one
$this->tabs = array('objecttype:+tabname1:Title1:mylangfile@mymodule:$user->rights->mymodule->read:/mymodule/mypagetab1.php?id=__ID__' // To add a new tab identified by code tabname1
'objecttype:+tabname2:Title2:mylangfile@mymodule:$user->rights->mymodule->read:/mymodule/mypagetab2.php?id=__ID__', // To add a new tab identified by code tabname2
'objecttype:-tabname'); // To remove an existing tab identified by code tabname
</source>

The table should contain a list of strings, each string representing a new tab.
The format of the string consisting of 5 parts separated by ":"
* Part 1: The element type (objecttype) where the tab should appear is a value from the following:
{{TemplateModuleTabs}}
* Part 2: A code to identify tab to add (start with +) or to remove (start with -)
* Part 3: The title of the tab. This can be a hard read or better code translation in a file lang.
* Part 4: The name of the file "*.lang" which contains correspondence between the code translation and language to display. If this name is followed with @mymodule, Dolibarr will search translation file "*.lang" within the module, so htdocs/mymodule/langs/code_CODE/mylangfile.lang, otherwise Dolibarr will look for file htdocs/langs/code_CODE/mylangfile.lang
* Part 5: A condition to test if tab must be visible. Put 1 to be always visible.
* Part 6: The url of the page to display when you click on the tab. The __ID__ string will be replaced automatically by the Id of the element concerned.

To feed the contents of the tab with data from the database, see the next chapter.

=== Show tabs navigation into your own pages ===
'''When''': To show all standard tabs of an object (produit, tiers, etc.) on your page.

You must follow these steps :

'''1. Include files you need into your file'''

For each object type, there are two files to include with line
<source lang="php">require_once($url_fichier) ;</source>

This is example of files to include (DOL_DOCUMENT_ROOT is often dolibarr/htdocs/) :
* Object thirdparty (thirdparty) :
** DOL_DOCUMENT_ROOT/societe/class/societe.class.php
** DOL_DOCUMENT_ROOT/core/lib/company.lib.php
* Object product (product) :
** DOL_DOCUMENT_ROOT/product/class/product.class.php
** DOL_DOCUMENT_ROOT/core/lib/product.lib.php
* Object invoice (invoice) :
** DOL_DOCUMENT_ROOT/compta/facture/class/facture.class.php
** DOL_DOCUMENT_ROOT/core/lib/invoice.lib.php
...

'''2. Create and load the object to show into your tab'''

Create instance of object of the correct class and load object from database by using the fetch method of object en providing to this method the id you get from url (ie : /mytab.php?id=1).

''Example :''
<source lang="php">
$id=GETPOST('id','int');
$ref=GETPOST('ref','alpha');
$product = new Product($db) ;
$result = $product->fetch($id,$ref) ; // Test $result to check the database read is ok
</source>

'''3. Get list of all tabs to show for your object type'''

Use fonction XXX_prepare_head($obj), where XXX is name of object. This will return an array with all definition of tab entries to show. Parameter to put into this method is the instance of object you want tabs.

The resulting array has the following structure
<source lang="php">
$head // Array of tabs
$head[$h] // Element to describe one tab.
$head[$h][0] // Url of page to show when you click on tab
$head[$h][1] // Title of tab
$head[$h][2] // Code name to identify the tab
</source>

''Example :''
<source lang="php">
$head = product_prepare_head($product, $user) ; // parameter $user is present for some function anly
</source>

'''4. show tabs into your page'''

Use function dol_fiche_head() to show all tabs defined into array $head returned by XX_prepare_head().

<source lang="php">
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 // Title to show (shown into a special tab that you can't click)
//$notab
//$picto // Name of image to show into title. Possible values are:
// product
// service
// company
</source>

This function will show required tabs and open an html element ''< div class="" >'' that correspond to the area under the tabs. To close area of a tab, just use ''< /div >'' into your PHP page.

== Create or modify PHP screens (optional) ==
'''When''': If the purpose of your module is to add features that require new or modified screens.

=== Create a new PHP screen ===
You must then create your PHP pages that will show/edit data from tables using the skeleton templates provided as an example in the directory '''modulebuilder/myobject_page.php''' (For the development of a script from the command line, see [[Script development]]).

To create a new user screen, create a subdirectory of '''htdocs''' (if not already done) for your module (in '''htdocs/mymodule''' for example) to store the pages you will create.

Copy, into that directory, the file '''myobject_page.phpp''' that will serve as a starting point for your page file.
Edit the file to have a correct relative path to the main.inc.php file.
<source lang="php">
// Load Dolibarr environment
$res=0;
// Try main.inc.php into web root known defined into CONTEXT_DOCUMENT_ROOT (not always defined)
if (! $res && ! empty($_SERVER["CONTEXT_DOCUMENT_ROOT"])) $res=@include($_SERVER["CONTEXT_DOCUMENT_ROOT"]."/main.inc.php");
// Try main.inc.php into web root detected using web root caluclated from SCRIPT_FILENAME
$tmp=empty($_SERVER['SCRIPT_FILENAME'])?'':$_SERVER['SCRIPT_FILENAME'];$tmp2=realpath(__FILE__); $i=strlen($tmp)-1; $j=strlen($tmp2)-1;
while($i > 0 && $j > 0 && isset($tmp[$i]) && isset($tmp2[$j]) && $tmp[$i]==$tmp2[$j]) { $i--; $j--; }
if (! $res && $i > 0 && file_exists(substr($tmp, 0, ($i+1))."/main.inc.php")) $res=@include(substr($tmp, 0, ($i+1))."/main.inc.php");
if (! $res && $i > 0 && file_exists(dirname(substr($tmp, 0, ($i+1)))."/main.inc.php")) $res=@include(dirname(substr($tmp, 0, ($i+1)))."/main.inc.php");
// Try main.inc.php using relative path
if (! $res && file_exists("../main.inc.php")) $res=@include("../main.inc.php");
if (! $res && file_exists("../../main.inc.php")) $res=@include("../../main.inc.php");
if (! $res && file_exists("../../../main.inc.php")) $res=@include("../../../main.inc.php");
if (! $res) die("Include of main fails");
</source>
Note that you may add more "../" depending on the depth of the file relative to your module directory tree.
The modules developed for all version of Dolibarr after the 3.2 should be able to be moved in a different folder than "htdocs", like "htdocs/custom", without having to modify the source code of the module, that's why we make several includes, so this rule must be applied by all modules.

It's in the main.inc.php file that is loaded technical environment variables and permissions. The following variables are objects positioned in this file:

* $user Objet that contains the characteristics of the user + his permissions.
* $conf Objet that contains Dolibarr configuration.
* $db Objet that contains an opened connection handler to the database.
* $langs Objet that contains the user's language.

Then enter your code to display the page.

* To include a class or library dedicated to the module is done using a Dolibarr function (and not using directly include_once):
''Example :''
<source lang="php">
dol_include_once('/mymodule/class/myclass.class.php', 'MyClass');
</source>

* To include classes provided with Dolibarr, use the following syntax:
''Example :''
<source lang="php">
require_once DOL_DOCUMENT_ROOT.'/core/class/doli.class.php';
</source>

=== Add some fields into existing forms ===
You may want to provide a module that add more fields into forms (input and view) of some elements.

A heavy solution (but not so bad) may be to replace all pages used to create element (this means disable the "New element" menu entry and adding yours, and disable tab that show element to replace with a tab that is your own full page (copied/pasted from original) to do same than original page but modified to add your fields and stored added data into your own table). Go to menu [[#Define your entries in menu (optional)]] and [[#The tab management (optional)]] if this solution suits you (this solution is more powerfull since you can change everything you want into page).

We will describe here another solution, that works only to "add fields" at end of existing fields, using the element "category" as an example but you can convert this tutorial for invoice, proposal ...
* First thing is to add a table, owned by your module, to store value of new fields. This table will have only one column called "rowid" (will contains same value than field rowid of element table) + one column for each new field you want to add. Then create a class with CRUD (Create/Read/Update/Delete) methods for this new table. For this two tasks, go back to previous chapter [[#Create your SQL tables and the PHP DAO class]].
* Next step is to add a hook into your module to add the new fields into the form. See chapter [[Hooks_system#Implement_the_Hook]] for generic documentation to use hooks.
If you follow this tutorial, to be able to add fields into category forms, you must do:
{{ToComplete}}

=== Replace parts of screen that are templated (version 3.3+) ===
Some parts of Dolibarr screen are isolated into native PHP template files.
You can develop a module to overwrite such templates with yours.
{{ToComplete}}

=== Add/replace part of fields supported by hooks ===
See chapter [[Hooks_system#Implement_the_Hook]] to know how to use Dolibarr existing hooks to add/replace code at Dolibarr hooks place.

=== Database access ===
If you need to edit some data in database inside you own table, use the PHP class generated before.

If you to make access to tables with no dedicated PHP class available, this is always possible (for example if you want to get a list of records with a particular join or filter). In this case, this is a code samples to follow:

To make an insert, update or delete:

<source lang="php">
$db->begin(); // Start transaction
$db->query("My SQL request insert, update or delete");
$db->commit(); // Validate transaction
or $db->rollback() // Cancel transaction
</source>

To read:

<source lang="php">
$resql=$db->query("My select request");
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++;
}
}
}
</source>

=== Define style of your pages ===
To have the look of your own pages to match the Dolibarr theme, it is necessary to use the Dolibarr CSS styles.

You can use for example:

* class="'''liste_titre'''" on tags ''tr'' and ''td'' for the head row of a table.
* class="'''pair'''" or class="'''impair'''" on tags ''tr'' and ''td'' of other rows of a table.
* class="'''flat'''" on all input fields (''input, select, textarea''...).
* class="'''button'''" on HTML fields with type ''input type="submit"''.

=== Use the Dolibarr date picker ===
If you want to use the Dolibarr date selector (with its calendar popup) into your pages, use the following line:
<source lang="php">
$form=new Form($db);
$form->select_date('','mykey',0,0,0,"myform");
</source>
The string mykey will identify the date selector in the form. You must use different values if you use several date selectors in same page.
The string myform is the name of the FORM in which the selector is included (value found in the form name="myform" in HTML page).
This means a date selector must be included necessarily into an html FORM.

To get value after the POST of your form, the command is:
<source lang="php">
$mydate = dol_mktime(12, 0 , 0, $_POST['mykeymonth'], $_POST['mykeyday'], $_POST['mykeyyear']);
print strftime('%A %d %B %Y', $mydate);
</source>

== Add your own setup page (optional) ==
'''When''': If your module needs parameters, which are to be provided by the user, for proper setting up of the module.

=== Create your page to edit parameters ===
If your module needs several parameters to be setup, you must create a page to edit options (these options will be saved in the [[Table llx_const|table '''llx_const''']]).
Create a page named '''mymodule_setuppage.php''' that shows a form for possible options to update them into the above mentioned table.
It is necessary to take an example from a page of the directory '''/admin''' that will show you the way to read/save your parameters.
Put this PHP page into the directory '''/admin''' of your module (e.g. mymodule/admin/mymodule_setuppage.php).

=== Modify the descriptor file of your module ===
Then, within the descriptor file of your module, modify the variable '''config_page_url''' to set name of this PHP page.
If the page is in the directory '''admin/''', then the path is not required, e.g. like this:
<source lang="php">
$this->config_page_url = array("mymodule_setuppage.php");
</source>
If the page is in the directory '''mymodule/admin/''', then like this:
<source lang="php">
$this->config_page_url = array("mymodule_setuppage.php@mymodule");
</source>

=== Test your page ===
Go into page '''Home->Setup->Modules''', you should see a picture at the end of the line of your module to reach your setup page. Click on it, you should be able to view/edit parameters from your page.

== Define your entries in menu (optional) ==
'''When''': If you have created PHP pages, it is necessary that those pages can be reached from menu entries in Dolibarr menu.

=== Define your menu entries ===
For this, you must define into the module descriptor, the array this->menu that declare all menus added by your module.
This array contains entries that will appear once your module is activated.
The example module descriptor file '''modMyModule.class.php''' contains an example to declare a top menu and also its left menu entries.

This is the example of code to declare your own menu entries in a module descriptor file:
<source lang="php">
// 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( 'fk_menu'=>0, // Put 0 if this is a top menu
'type'=>'top', // This is a Top menu entry
'titre'=>'MyModule top menu',
'mainmenu'=>'mymodule',
'leftmenu'=>'mymodule',
'url'=>'/mymodule/pagetop.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'=>'',
'user'=>2); // 0=Menu for internal users, 1=external users, 2=both
$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 of parent menu
'type'=>'left', // This is a Left menu entry
'titre'=>'MyModule left menu 1',
'mainmenu'=>'xxx',
'leftmenu'=>'yyy',
'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'=>'',
'user'=>2); // 0=Menu for internal users,1=external users, 2=both
$r++;
</source>

To show menu or not depending on a permission, modify property '''perms''' in array. See chapter on permissions later to see how to add permissions.

=== Test your menu entries ===
Disable and reenable your module under Dolibarr module setup page, menus entries must appear (if property 'enabled' is declaration array is ok).

== Add your own permissions (optional) ==
'''When''': If you want to add new permissions.

The way to define permissions that will manage your module is done inside the module descriptor created previously.
Modify line
<source lang="php">
$this->rights_class = 'mymodule'
</source>
with correct value for mymodule.

Then you must fill the array $this->rights with as many entries than different permissions you need to manage.

<source lang="php">
$this->rights[$r][0] = 10001;
$this->rights[$r][1] = 'Label by default of permission';
$this->rights[$r][3] = 1;
$this->rights[$r][4] = 'action';
$this->rights[$r][5] = 'subaction';
$r++;
</source>

Into $this->rights[$r][0], put a permission id not already used (See into menu '''System info''' on a working installation of Dolibarr to know list of id already used by standard modules.
Into $this->rights[$r][3], put 1 if this permission must be granted automatically by default to any new created user.
Into $this->rights[$r][1], put a label by default for permission (This label will be used if no translation can be found into the file '''admin.lang''').
Into $this->rights[$r][4] and $this->rights[$r][5], put an action and subaction string without spaces. You will be able to test if a user has the permission in your PHP source code with the sequence:

<source lang="php">
if ($user->rights->mymodule->action->subaction) ...
</source>

== Define you own box (optional) ==
'''When''': If your module need to provide one or several new boxes to show on home page.

=== Define your box ===
For this, modify the array $this->boxes into the module descriptor file.
All you have to do is to add 2 lines for each box file you will create into directory '''htdocs/mymodule/core/boxes'''

''Example:''
<source lang="php">
$this->boxes[0]['file']='mybox0.php@mymodule'
$this->boxes[0]['note']='My box 0'
...
$this->boxes[n]['file']='myboxn.php@mymodule'
$this->boxes[n]['note']='My box n'
</source>

Then create files '''htdocs/mymodule/core/boxes/mybox0.php''', '''htdocs/mymodule/core/boxes/mybox1.php'''... by copying an example from an existing box file (found into directory '''htdocs/core/boxes''').

=== Test if your box is detected by Dolibarr ===
Disable and enabled module.

Go into menu '''Home - Setup - Boxes'''.

Your boxes must appear in the list of boxes you can activated. Activate the box and go on home page to see if the box is showing correctly.

== Define your own export (optional) ==
'''When''': If your module provide new predefined database export profiles (for its own tables or for already existing tables of another module).

=== Define export ===
For this uncomment and modify arrays $this->export_xxx in your module descriptor file.

=== Test your export ===
Go into menu Tools -> Export. Your export will appear in the list of available predefined exports (if your module is enabled).
Choose it, you must see list of all possible fields defined in the export arrays.
Choose on field and try to build an export file. If ok, try again with all fields.

== Define your CSS styles (optional) ==
'''When''': If in your PHP pages, you use class styles that are not defined inside Dolibarr themes CSS (not recommanded).

=== Create and declare your style sheet ===
Create a style sheet CSS named '''mymodule.css''' or '''mymodule.css.php''' and put it into directory '''htdocs/mymodule'''. You can have only one CSS file per module.
Remember it's better to use existing styles already available by default into Dolibarr (The CSS file used by Dolibarr is file '''themes/mytheme/''themename''.css.php'''. Create your own CSS file only if you need absolutely to add not already existing styles.

Once your style sheet is ready, declare it into your module descriptor file by modifying the property '''$this->modules_parts'''.
Value to put here must be a relative URL to your CSS file.
For example
<source lang="php">
$this->module_parts = array('css' => array('/mymodule/css/mymodule.css.php'));
</source>

=== Test your style sheet ===
Disable and enable your module.

Go on home page (index.php). Show the HTML source of the page.

You should see into the HTML header, a line that declare your style sheet.

== Add your Javascript functions (optional) ==
'''When''': If in your PHP pages, you use javascript functions not available in Dolibarr (in file lib_head.js)

If you need to use your own javascript functions inside your PHP pages, it is necessary to have your functions, defined into your javascript file '''htdocs/mymodule/js/mymodule.js''', included into the HTML HEAD section.
To ask Dolibarr that forge this header to include your own javascript file, you must just provide it to the llxHeader() function called by your page.

Example for page /htdocs/mymodule/mypage.php :
<source lang="php">
$morejs=array("/mymodule/js/mymodule.js");
llxHeader('','Titre','','','','',$morejs,'',0,0);
</source>

== Run your own code on any Dolibarr event (optional) ==
'''When''': If you want to execute your own code once a common Dolibarr event has occurred (example: I want to update a table in my module when an invoice is created into Dolibarr), you must create a '''triggers'''.

See also [[Interfaces_Dolibarr_toward_foreign_systems]]
and [[Interfaces_from_foreign_systems_toward_Dolibarr]]

== Insert your code inside Dolibarr hooks positions (optional) ==
'''When''': When you want to add code or replace Dolibarr code into another situation than a business event (See previous chapter for adding code during a business event).

See page [[Hooks_system]].

== Add your own numbering rules ==
'''When''': When you need a new rule for generated ref of elements that is not covered by existing rules.

See page [[Create numbering module]].

== Add your document template (optional) ==
'''When''': When you want to personalized your own generated PDF or ODT documents.

Note: To add this feature you don't need to create a module descriptor.

Documentation to add your own template is available on page [[Create_a_PDF_document_template]] or [[Create_an_ODT_document_template]].

== Add your skin (optional) ==
'''When''': When you want to personalized your colors/fonts/images.

Note: To add this feature you don't need to create a module descriptor.

To add your own skin, read page [[Skins]].

=Some coding rules and predefined functions =
The coding rules to be followed are defined in the [[Developer documentation]], under section "General Information - Language and standards development".

A lot of predefined features for developers are also available and described into page [[Developer documentation]] under section "Technical components of Dolibarr".

=Using MDA =
A method to generate a functional module from a UML model has been developed. More information on the page [[UML2Dolibarr - Build a module using MDA]].

=Create a package to distribute and install your module =
This process must be used to generate a package to submit it on the http://www.dolistore.com market place.
But you can use it to have a package easy to distribute on your on network.

* Go into the directory '''/build''' and copy the file '''makepack-dolibarrmodules.conf''' into '''makepack-mymodule.conf'''. Warning, this directory may not be provided in some packages of stable versions. If so, it can be retrieved from the snapshot available for download on the Dolibarr website in area "Development version" (taken in this case the whole build directory which is autonomous and independent directory).

Edit this file to add list of file names for all new files you created for your module (module descriptor, new sql tables files, php page, images, etc...)

* Run the script via Perl (need the Perl version 5.0 or later):
<source lang="bash">
perl makepack-dolibarrmodule.pl
</source>
The script asks you the name of your module, its major and minor version. A file '''mymodule.zip ''' will then be manufactured containing your module ready to be deployed.

* The person who receives your module must then place the file in the root directory of a Dolibarr installation and perform the command:
<source lang="bash">
tar -xvf mymodule.zip
</source>

* If you want your module to be public, you can submit it (the zip file) on Dolibarr market place web site: {{LinkToPluginDownload}} (you must create an account first and be logged to use the link "Submit a module/product").
** If your module was build correctly, file will be validated later.
** If quality is enough and license permits it, code might be added inside main Dolibarr sources (except if you disagree for that).

= Enabling/activation condition of external module on DoliStore =

See [[Module_Dolistore_Validation_Rules|Validation Rules]]

Développement module

2018-02-12T12:20:41Z

Delcroip: /* Créer vos fichiers .sql */

[[Category:Noyau]]
{{TemplateDocDev}}
Pour créer un nouveau module, il existe plusieurs étapes. Ce didacticiel a pour but de vous décrire chacune d'elle afin d'ajouter un module permettant d'étendre les possibilités de Dolibarr, comme par exemple ajouter une ou plusieurs des fonctionnalités suivantes:
* Ajouter de nouvelles tables en base
* Ajouter vos propres entrées dans les menus
* Ajouter des écrans de saisie/consultation de nouvelle tables
* Ajouter ou supprimer des onglets sur les pages de vues/édition des objets (facture, produit, commande, événement, ...)
* Ajouter des exports prédéfinis pour la fonction export
* Ajouter de nouvelles boites pour la home page
* Ajouter des variables de substitutions
* Définir de nouvelles permissions
* Déclencher du code automatiquement sur une action Dolibarr particulière
* Insérer votre code aux emplacement hooks de Dolibarr
* Ajouter un module de numérotation
* Ajouter un modèle de document
* Ajouter un nouveau thème
etc...
Toutes ces opérations ne sont possibles qu'avec la version 3.2 ou plus de Dolibarr.

Les chapitres suivants vous présentent comment réaliser tout cela en manuel de manière simple. Pour les développeurs très expérimentés, une méthode par génération MDA est en cours de mise au point. Voir le dernier chapitre pour cela.

= [[File:Art.png]] Exemple de modèle de module externe=

Un bon modéle/squelette de module externe Dolibarr est disponible ici : [https://github.com/Dolibarr/dolibarr/tree/develop/htdocs/modulebuilder/template GitHub Dolibarr Module Modèle]

= [[File:Art.png]] Créer un module =
Les sous chapitres suivant décrivent les actions à faire pour créer un module Dolibarr. Les premiers chapitres sont obligatoires quelle que soit la vocation du module, les suivants dépendront de ce que doit faire le module.

== Créer un descripteur de Module (obligatoire) ==
'''Quand''': Obligatoire dès qu'une extension est développée, quelle que soit sa vocation (sauf pour l'ajout de thème ou de modèle de document).

=== Créer votre descripteur ===
La première étape est donc de créer un fichier de description du module (descripteur). Pour cela:
* Créer le répertoire '''/htdocs/''monmodule''/core/modules'''. Puis, aller dans le répertoire '''dev/skeletons''' et recopier le fichier modMyModule.class.php dans ce répertoire '''htdocs/''monmodule''/core/modules'''.
* Renommez le fichier mod'''MyModule'''.class.php en modifiant seulement la partie '''MyModule''' (le fichier doit commencer par mod)
Ensuite, modifier le contenu de ce fichier afin de remplacer:
* les ''modMyModule'' en une valeur qui corresponde à la vocation de votre module. Cette valeur doit toujours commencer par ''''mod'''' et ne contenir que des '''caractères alphabétiques'''.
* $this->numero = ''100000'' par un numéro de module libre. Pour éviter tout conflit, vous pouvez consulter la page suivante pour retrouver les numéros déjà alloués: [[List of modules id|Liste des id de modules]].
* Modifier éventuellement les autres variables définies dans le constructeurs (Voir le commentaire dans le code du squelette pour leur signification).

Le descripteur de votre module est alors en place.

=== Tester votre descripteur ===

Lancer Dolibarr et aller sur la page '''Configuration->module''', vous devez voir apparaître une nouvelle ligne avec votre nouveau module et la possibilité de l'activer ou non (parcourez tous les onglets de chaque catégories de modules jusqu'à le retrouver).
C'est la valeur de $this->special qui détermine dans quel onglet se trouve votre module.

== Arborescence d'un nouveau module ==
Voici l'arborescence à respecter pour l'organisation des fichiers d'un module.

Rem: Seule la deuxième ligne est obligatoire.
{{TemplateModuleTreeSimple}}

Un modèle de module a été crée par un contributeur Dolibarr, il est accessible ici : [https://github.com/rdoursenaud/dolibarr-module-template]

== Créer vos tables SQL et les classes PHP DAO (optionnel) ==
'''Quand''': Si votre module a besoin de gérer des données qui lui sont propres

=== Créer vos fichiers .sql ===
Si votre module a vocation à gérer des données bien à lui, qui n'existent pas en base dans la version standard de Dolibarr, il est nécessaire de définir des tables SQL pour stocker ces données.

Créer un sous-répertoire '''sql''' dans le répertoire de votre module (par exemple '''htdocs/monmodule/sql''') afin d'y placer les scripts sql que vous allez créer.

Ensuite, vérifiez dans votre fichier descripteur de module, dans la fonction '''init''' que la ligne

<source lang="php">$this->_load_tables('/mymodule/sql/');</source>

n'est pas commentée.

''Règles à respecter:''
* Ajouter les fichiers d'ordre de création de vos tables sur le principe d'un fichier '''llx_matable.sql''' par table accompagné éventuellement du fichier '''llx_matable.key.sql''' (voir les fichiers existants dans '''install/mysql/tables''' pour exemple).
* Pour ce qui est des commandes pour ajouter/manipuler des données, elles doivent toutes se trouver dans un fichier nommé '''data.sql''' situé dans le même répertoire '''/monmodule/sql/'''.
* N'utilisez pas "chaine" mais 'chaine' car les guillemets doubles (") ont une signification particulière en PostGreSQL
Exemple de contenu de fichier data.sql
<source lang="sql">
delete from llx_const where name='MONMODULE_IT_WORKS' and entity='__ENTITY__';
insert into llx_const (name, value, type, note, visible, entity) values ('MONMODULE_IT_WORKS','1','chaine','A constant for my module',1,'__ENTITY__');
</source>

Les ordres SQL des fichiers doivent être opérationnels pour la base de données '''mysql'''.
Rem: Les fichiers des autres bases ne sont pas à maintenir. Ils sont lus et convertit à la volée par le driver de la base de données.

=== Tester vos fichier .sql ===

Une fois les fichiers prêts, vous pouvez retourner sous Dolibarr puis désactiver le module, dropper les tables en base et réactiver le module.
Les tables doivent alors être recréées par l'activation du module.
Si tel n'est pas le cas, vérifiez vos scripts en les passant à la main, ou consultez les logs Dolibarr.

=== Générer la classe PHP DAO d'accès aux tables ===

Une fois votre ou vos tables créées en base, aller dans le répertoire '''dev/skeletons''', copiez le fichier '''build_class_from_table.php''' dans le répertoire sql/ de votre module, et lancez le script
<source lang="bash">php build_class_from_table.php nomtable</source>
Remarque: Si la commande ne fonctionne pas, essayer d'utiliser php-cli plutot que php.

Ceci génèrera un fichier '''out.nomtable.class.php''' qui contient la classe de gestion de la table nomtable.
Dans cette classe, se trouve des méthodes CRUD (Create/Read/Update/Delete) déjà opérationnelles pour faire un insert, un fetch (select), un update, un delete d'une ligne de la table.
Supprimer juste le "out" du nom de fichier et placer votre fichier dans le sous-répertoire de '''htdocs''' propre à votre module (Dans '''htdocs/monmodule''' par exemple).

Un fichier '''out.nomtable_script.php''' a également été généré et contient un exemple de code pour utiliser la classe pour chacune des 4 méthodes CRUD.

== Affichage des onglets (optionnel) ==

=== Ajouter ou supprimer des onglets sur les fiches objets ===
'''Quand''' : Pour ajouter votre propre onglet parmi les onglets standard d'une fiche entité (facture, commande, proposition commercial, adhérent...)

Pour cela, aller dans le fichier descripteur de module précédemment créé et modifier le tableau $this->tabs:
<source lang="php">
// Array to add new pages in new tabs or remove existing one
$this->tabs = array('objecttype:+tabname1:Title1:mylangfile@monmodule:$user->rights->monmodule->read:/monmodule/mapagetab1.php?id=__ID__' // To add a new tab identified by code tabname1
'objecttype:+tabname2:Title2:mylangfile@monmodule:$user->rights->monmodule->read:/monmodule/mapagetab2.php?id=__ID__', // To add a new tab identified by code tabname2
'objecttype:-tabname'); // To remove an existing tab identified by code tabname
</source>

Le tableau doit contenir une liste de chaîne, chaque chaîne représentant un nouvel onglet.
Le format de la chaîne étant composé de 6 parties séparées par ":"
* Partie 1: Le type d'élément (objecttype) dans lequel doit apparaître l'onglet qui est une valeur parmi celle-ci:
{{TemplateModuleTabs-fr}}
* Partie 2: Nom de code pour l'onglet à ajouter (commence par +) ou à enlever (commence par -)
* Partie 3: Le titre de l'onglet. Cela peut être un libellé en dur ou mieux un code traduction présent dans un fichier lang.
* Partie 4: Le nom du fichier .lang (sans l'extension .lang) qui contient la correspondance entre le code traduction et le libellé à afficher. Si ce com est suivi de @monmodule, Dolibarr cherche le fichier dans le répertoire lang propre au module, c'est à dire htdocs/monmodule/langs/code_CODE/monmodule.lang, sinon Dolibarr cherche le fichier traduction dans htdocs/langs/code_CODE/mylangfile.lang
* Partie 5: Une condition à tester pour savoir si l'onglet doit être visible ou pas. Mettre '1' pour qu'il soit toujours visible.
* Partie 6: L'url de la page à afficher quand on clique sur l'onglet. La chaine __ID__ sera remplacée automatiquement par l'Id de l'entité concernée.

Pour que la déclaration soit effective, il faut désactiver et réactiver le module.

Pour alimenter le contenu de l'onglet avec des données issues de la base, voir le chapitre suivant.

=== Ajouter les onglets standard d'un objet sur sa propre page ===
'''Quand''' : Pour afficher les onglets standard d'une fiche entité (produit, tiers, etc.) sur votre propre page onglet d'une entité.

Il faut appliquer la procédure suivante :

'''1. Inclure les fichiers définissant les fonctions utiles dans vos fichiers'''

Pour chaque fiche entité, il y a deux fichiers à inclure avec l'instruction
<source lang="php">require_once($url_fichier) ;</source>

Voici quelques examples de fichiers à inclure (DOL_DOCUMENT_ROOT correspond au dossier dolibarr/htdocs/) :
* Entité tiers (thirdparty) :
** DOL_DOCUMENT_ROOT/societe/class/societe.class.php
** DOL_DOCUMENT_ROOT/core/lib/company.lib.php
* Entité produit (product) :
** DOL_DOCUMENT_ROOT/product/class/product.class.php
** DOL_DOCUMENT_ROOT/core/lib/product.lib.php
* Entité facture (invoice) :
** DOL_DOCUMENT_ROOT/compta/facture/facture.class.php
** DOL_DOCUMENT_ROOT/core/lib/invoice.lib.php

'''2. Créer et charger l'objet à afficher dans votre onglet'''

Créer l'objet de la classe voulue, et récupérer les données de l'objet à partir de la base de données. Pour cela il faut utiliser les fonctions fetch() de la classe correspondante, en passant en paramètre l'identifiant de l'objet que vous récupérez depuis l'url (ex : /mononglet.php?id=1).

''Exemple :''
<source lang="php">
$id=GETPOST('id','int');
$ref=GETPOST('ref','alpha');
$product = new Product($db) ;
$result = $product->fetch($id, $ref) ; //Tester $result pour vérifier que l'accès à la base s'est bien passée
</source>

'''3. Récupérer la liste des onglets correspondants à l'entité choisie'''

Utiliser la fonction XXX_prepare_head($obj), ou XXX est le nom de l'entité, permettant de créer un tableau contenant les définitions des onglets à afficher. Le paramètre à passer est l'objet pour lequel vous voulez afficher les onglets.

Le tableau retourné est composé de la façon suivante :
<source lang="php">
$head // Tableau des onglets
$head[$h] // Élément décrivant un onglet. Il y aura autant de $h que d'onglets à afficher
$head[$h][0] // Url de la page affichée quand on clique sur l'onglet
$head[$h][1] // Titre de l’onglet
$head[$h][2] // Code de l'onglet, à utiliser pour choisir quel onglet sera 'actif' (voir paragraphe suivant)
</source>

''Exemple :''
<source lang="php">
$head = product_prepare_head($product, $user) ; //le paramètre $user n'est pas présent sur certaines fonctions
</source>

'''4. Afficher les onglets sur votre page onglet'''

Utiliser la fonction dol_fiche_head() qui affiche les onglets contenus dans le tableau $head retourné par XX_prepare_head().

<source lang="php">
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
</source>

Cette fonction affiche les onglets voulus et ouvre un élément ''< div class="" >'' qui correspond à la zone bleue sous les onglets (si paramètre $notab = 0). Pour fermer la zone bleue, il suffit de fermer l'élément ''< /div >'' dans le code PHP.

''Remarque'':
Pour plus de détail, se référer à la [http://www.dolibarr.fr/doxygen/ documentation Doxygen] ou directement au code de Dolibarr.

== Créer vos pages écran PHP (optionnel) ==
'''Quand''': Si l'objet de votre module est d'ajouter des fonctionnalités qui nécessitent de nouveaux écrans.

=== Créer une page écran PHP brute ===
Vous pouvez ensuite créer vos pages PHP, qui se basent sur les données de vos tables, en utilisant les squelettes fournis comme exemple dans le répertoire '''modulebuilder''' (Pour le développement d'un script en ligne de commande, voir [[Développement de scripts]]).

Pour créer une nouvelle page écran utilisateur, créer un sous-répertoire de '''htdocs''' (si non déjà fait) propre à votre module (Dans '''htdocs/monmodule''' par exemple) afin d'y placer les pages que vous aller créer.

Y recopier le fichier '''myobject_page.php''' qui va servir de point de départ.
Modifier le fichier afin que le main.inc.php soit trouvés
<source lang="php">
// Load Dolibarr environment
$res=0;
// Try main.inc.php into web root known defined into CONTEXT_DOCUMENT_ROOT (not always defined)
if (! $res && ! empty($_SERVER["CONTEXT_DOCUMENT_ROOT"])) $res=@include($_SERVER["CONTEXT_DOCUMENT_ROOT"]."/main.inc.php");
// Try main.inc.php into web root detected using web root caluclated from SCRIPT_FILENAME
$tmp=empty($_SERVER['SCRIPT_FILENAME'])?'':$_SERVER['SCRIPT_FILENAME'];$tmp2=realpath(__FILE__); $i=strlen($tmp)-1; $j=strlen($tmp2)-1;
while($i > 0 && $j > 0 && isset($tmp[$i]) && isset($tmp2[$j]) && $tmp[$i]==$tmp2[$j]) { $i--; $j--; }
if (! $res && $i > 0 && file_exists(substr($tmp, 0, ($i+1))."/main.inc.php")) $res=@include(substr($tmp, 0, ($i+1))."/main.inc.php");
if (! $res && $i > 0 && file_exists(dirname(substr($tmp, 0, ($i+1)))."/main.inc.php")) $res=@include(dirname(substr($tmp, 0, ($i+1)))."/main.inc.php");
// Try main.inc.php using relative path
if (! $res && file_exists("../main.inc.php")) $res=@include("../main.inc.php");
if (! $res && file_exists("../../main.inc.php")) $res=@include("../../main.inc.php");
if (! $res && file_exists("../../../main.inc.php")) $res=@include("../../../main.inc.php");
if (! $res) die("Include of main fails");
</source>
Notez qu'il est possible que vous deviez ajouter plus de "../" dans les chemin, en fonction de la profondeur de vos fichiers par rapport au répertoire de votre module.

Pour tous les modules développés après la version 3.2 de Dolibarr, il convient de pouvoir placer un répertoire de module soit dans '''htdocs''' soit dans un sous répertoire comme '''htdocs/custom''' sans avoir à modifier le code source du module, c'est pour cela que cette règle doit obligatoirement être appliquée.

C'est dans le main qu'est chargé l'environnement technique ainsi que les habilitations. Les variables objets suivantes sont alors positionnées:

* $user L'objet qui contient les caractéristiques de l'utilisateur + ses droits.
* $conf L'objet qui contient la configuration de Dolibarr.
* $db L'objet qui contient le handler de connexion ouvert à la base de données.
* $langs L'objet qui contient la langue de l'utilisateur.

* L'inclusion d'une classe ou librairie dédiée au module, sans savoir d'où le fichier sera appelé, se fait en utilisant une fonction de Dolibarr (et non en utilisant directement le include_once)
''Exemple :''
<source lang="php">
dol_include_once('/monmodule/class/maclasse.class.php', 'MaClasse');
</source>

* L'appel des classes fournies en standard avec Dolibarr se fera par contre par le require_once directe avec la syntaxe suivante:
''Exemple :''
<source lang="php">
require_once DOL_DOCUMENT_ROOT.'/core/class/doli.class.php';
</source>
La raison est que si le dol_include_once est pratique car il scanne chaque répertoire de chemin alternatifs pour trouver le fichier, il est aussi moins performant car génère des accès et recherches disque à chaque appel (en effet, PHP intègre un cache des fichiers lus mais n'intègre pas un cache des fichiers "non trouvés". Et comme un fichier donné n'est que dans une seule arborescence, il y a toujours une arborescence alternative où il ne se trouve pas et qui génère des accès superflus au disque dur, pénalisant en terme de performance. Comme pour les fichiers internes à Dolibarr, on connait toujours le chemin exacte, le require_once avec ce chemin direct doit être préféré).

=== Remplacer les parties d'écrans templatés (version 3.3+) ===
Certaines portion d'écran de Dolibarr sont isolés dans des fichiers templates.
Vous pouvez développer un module pour remplacer un ou plusieurs de ces templates par les vôtres.
{{ToComplete}}

=== Accès à la base ===
Si vous avez besoin de réaliser des modifications en base dans votre propre table ajoutée, utilisez la classe générée plus haut qui contient les méthodes pour cela.

Si toutefois vous voulez faire des accès dans des tables sans objet PHP dédié, ceci reste possible (par exemple pour récupérer une liste d'enregistrement). Dans ce cas, pensez à suivre ces exemples:

Pour un insert, update ou delete:

<source lang="php">
$db->begin(); // Debut transaction
$db->query("Ma requete insert, update ou delete");
$db->commit(); // Valide
ou $db->rollback() // Annule
</source>

Pour une lecture:

<source lang="php">
$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++;
}
}
}
</source>

=== Définition du style ===
Pour que le look de la page soit aligné avec le thème Dolibarr, il est nécessaire d'utiliser les styles des CSS de Dolibarr.

Par exemple:

* class="'''liste_titre'''" sur les balises ''tr'' et ''td'' pour une ligne de titre de tableau.
* class="'''pair'''" ou class="'''impair'''" sur les balises ''tr'' et ''td'' des lignes de données de tableau.
* class="'''flat'''" sur tous les champs de saisie (''input, select, textarea''...).
* class="'''button'''" sur les objets de type ''input type="submit"''.

=== Utiliser le sélecteur de date de Dolibarr ===
Si vous le désirez, vous pouvez profiter du sélecteur de date dans des écrans Dolibarr. Pour cela, utilisez la ligne suivante:
<source lang="php">
$form=new Form($db);
$form->select_date('','mykey',0,0,0,"myform");
</source>
La chaine mykey identifie la zone date. Il faut y mettre une valeur différente s'il y a plusieurs zones.
La chaine myform est le nom de la zone FORM (dans form name="myform" de la page HTML).
L'affichage d'un sélecteur de date doit donc être intégrée dans une zone FORM Html.

Pour récupérer la valeur, à l'issu du POST, la commande est:
<source lang="php">
$mydate = dol_mktime(12, 0 , 0, $_POST['mykeymonth'], $_POST['mykeyday'], $_POST['mykeyyear']);
print strftime('%A %d %B %Y', $mydate);
</source>

== Définir votre page de configuration (optionnel) ==
'''Quand''': Si votre module offre plusieurs options paramétrables.

=== Créer votre page d'édition de configuration ===
Si votre module offre plusieurs options paramétrables, il est nécessaire de créer une page PHP pour éditer les options (qui sont stockées dans la [[Table llx_const|table '''llx_const''']]).
Créer une page PHP nommée '''monmodule_setupapage.php''' qui affiche les options possibles et les met à jour.
Il est nécessaire de prendre exemple sur une page dans '''/admin''' qui vous montre la méthode pour lire ou sauvegarder en base votre option.
Placer cette page de configuration dans le répertoire '''/admin''' également.
Ensuite dans le descripteur de module, modifier la variable pour indiquer le nom de cette page PHP (sans le chemin qui n'est pas nécessaire, la page étant forcément dans le rep admin).
<source lang="php">
$this->config_page_url = array("monmodule_setupapage.php");
</source>

=== Tester votre page ===
Allez sur la page '''Configuration->module''', vous devez voir apparaître une icône qui permet d'accéder à la page de configuration et vous devez être capable de modifier ces options et les voir conservées en base.

== Définir vos entrées de menu (optionnel) ==
'''Quand''': Si vous avez créé des pages PHP, il est nécessaire que ces écrans soient accessibles depuis le menu Dolibarr.

=== Définissez vos entrées menus ===
Pour cela, il vous faut définir dans le fichier descripteur de module, le tableau this->menu qui déclare les menus.
Ce tableau contient toutes les entrées qui apparaîtront dans les menus une fois le module activé.
Le fichier de descripteur de module exemple '''modMonModule.class.php''' possède un exemple de déclaration de menu haut ainsi que de ses entrées menu gauche associées.

Voici un exemple de déclaration d'entrées de menu dans le fichier descripteur:
<source lang="php">
// 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( 'fk_menu'=>0, // Put 0 if this is a top menu
'type'=>'top', // This is a Top menu entry
'titre'=>'MonModule top menu',
'mainmenu'=>'monmodule',
'leftmenu'=>'monmodule',
'url'=>'/monmodule/pagetop.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->monmodule->enabled' if entry must be visible if module is enabled.
'perms'=>'1', // Use 'perms'=>'$user->rights->monmodule->level1->level2' if you want your menu with a permission rules
'target'=>'',
'user'=>2); // 0=Menu for internal users, 1=external users, 2=both
$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 of parent menu
'type'=>'left', // This is a Left menu entry
'titre'=>'MonModule left menu 1',
'mainmenu'=>'xxx',
'leftmenu'=>'yyy',
'url'=>'/monmodule/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->monmodule->enabled' if entry must be visible if module is enabled.
'perms'=>'1', // Use 'perms'=>'$user->rights->monmodule->level1->level2' if you want your menu with a permission rules
'target'=>'',
'user'=>2); // 0=Menu for internal users,1=external users, 2=both
$r++;
</source>

Pour conditionner l'accès au menu selon des permission, modifier la propriété '''perms''' du tableau. Voir le chapitre sur les permissions un peu plus loin pour savoir comment ajouter des permissions.

=== Tester vos entrées menus ===
Désactiver et réactiver votre module sous Dolibarr, les entrées menus doivent alors apparaître (si la condition dans 'enabled' est vraie).

== Définir vos propres permissions (optionnel) ==
'''Quand''': Si vous voulez ajouter de nouvelles permissions.

La définition des permissions que gérera votre module se fait dans le fichier descripteur créé dans la première étape.
Modifier la ligne
<source lang="php">
$this->rights_class = 'monmodule'
</source>
pour y mettre la bonne valeur de monmodule.

Ensuite remplissez le tableau $this->rights avec autant d'entrées que de permissions différentes à gérer.

<source lang="php">
$this->rights[$r][0] = 10001;
$this->rights[$r][1] = 'Libelle par défaut de ma permission';
$this->rights[$r][3] = 1;
$this->rights[$r][4] = 'action';
$this->rights[$r][5] = 'sousaction';
$r++;
</source>

Dans $this->rights[$r][0], mettre un id de permission non déjà pris (Voir dans le menu '''Infos Système''' sur une installation de Dolibarr opérationnelle pour connaitre les id déjà utilisés.
Dans $this->rights[$r][3], mettre 1 si cette permission est attribué d'office par défaut quand un utilisateur est créé.
Dans $this->rights[$r][1], mettre un libellé par défaut (il sera affiché si aucune traduction n'est trouvé pour votre permission dans le fichier '''admin.lang''').
Dans $this->rights[$r][4] et $this->rights[$r][5], mettre une chaîne action et sousaction sans espaces. Vous pourrez alors tester dans le code PHP si un utilisateurs a bien les droits par la séquence suivante:

<source lang="php">
if ($user->rights->monmodule->action->sousaction) ...
</source>

== Définir vos propres box (optionnel) ==
'''Quand''': Si votre module amène avec lui une ou plusieurs Boxes.

=== Définissez vos box ===
Pour cela, modifiez les tableaux $this->boxes du fichier descripteur de module.
Il suffit d'ajouter 2 lignes par fichier box que vous allez créer dans le répertoire '''htdocs/monmodule/core/boxes'''

''Exemple:''
<source lang="php">
$this->boxes[0]['file']='mabox0.php@monmodule'
$this->boxes[0]['note']='Ma box 0'
...
$this->boxes[n]['file']='maboxn.php@monmodule'
$this->boxes[n]['note']='Ma box n'
</source>

Ensuite créer les fichiers '''htdocs/monmodule/core/boxes/mabox0.php''', '''htdocs/monmodule/core/boxes/mabox1.php'''... en prenant exemple sur des box existantes (exemple dans le répertoire '''htdocs/core/boxes''')

=== Tester la présence de vos box dans Dolibarr ===
Désactiver et réactiver le module.

Aller dans le menu '''Accueil - Configuration - Boite'''.

Vos box doivent apparaître dans la liste des box activables. Activer les puis aller sur la page d'accueil et vérifier qu'elles s'affichent correctement.

== Définir vos propres exports (optionnel) ==
'''Quand''': Si votre module amène avec lui des exports prédéfini de données (pour ces propres tables ou des tables déjà existante d'un autre module de Dolibarr).

=== Définissez l'export ===
Pour cela, décommenter et modifier les tableaux $this->export_xxx du votre fichier descripteur de module.

=== Tester votre export ===
Aller dans le menu outils -> export de Dolibarr. Votre export doit apparaitre dans la liste des exports prédéfinis disponible (si votre module est bien activé).
Le choisir, vous devez alors voir les champs possible définis dans le tableau à l'étape précédente.
Choisir quelques champs et tenter une génération du fichier export.

== Définir vos styles CSS (optionnel) ==
'''Quand''': Si dans vos écrans PHP, vous utiliser des classes de styles qui ne sont pas celle des thèmes de Dolibarr (non recommandé).

Cette fonctionnalité est décrite mais pas encore opérationnel en 2.4

=== Créer et déclarer votre feuille de style ===
Créer un fichier de style css nommé '''monmodule.css''' ou '''monmodule.css.php''' et le placer dans le répertoire '''''monmodule''''' dans '''htdocs'''. Il ne peut y avoir qu'un fichier css propre à chaque module.
Rappelons qu'il vaut mieux utiliser les styles déjà existant de Dolibarr (le fichier css utilisé par Dolibarr étant le fichier '''themes/nomtheme/''nomtheme''.css.php'''). Ne créer un fichier css propre à votre module que si vous devez absolument gérer des styles non déjà existants.
Une fois votre feuille de style prête, déclarer la dans votre fichier descripteur de module en modifiant la propriété '''$this->module_parts'''.
La valeur à renseigner ici doit être le chemin relatif de l'URL de votre fichier css.
Par exemple
<source lang="php">
$this->module_parts = array('css' => array('/monmodule/css/monmodule.css.php'));
</source>

=== Tester votre feuille de style ===
Désactiver et réactiver votre module.

Appelez la page d'accueil de Dolibarr. Afficher la source de la page HTML.

Vous devriez voir dans l'entête HTML, une ligne déclarant votre feuille de style.

== Définir vos fonctions Javascript (optionnel) ==
'''Quand''': Si dans vos écrans PHP, vous utiliser des fonctions javascript non dispo en standard (fichier lib_head.js)

Si dans vos écrans PHP, vous utilisez des fonctions javascript, il est nécessaire de faire en sorte que vos fonctions déclarées dans un fichier javascript '''htdocs/monmodule/js/monmodule.js''' soit chargées dans l'entête head html.
Pour demander à Dolibarr qui gère la génération de la section header d'inclure un de vos fichiers javascript, il est nécessaire de fournir en paramètre de la fonction llxHeader() appelée au début de votre page, d'inclure le paramètre qui contient l'URL vers le js à inclure.

Exemple pour la page /htdocs/monmodule/mapage.php :
<source lang="php">
require('../main.inc.php');
$morejs=array("/monmodule/js/monmodule.js");
llxHeader('','Titre','','','','',$morejs,'',0,0);
</source>

== Déclencher du code sur un évènement Dolibarr (optionnel) ==
'''Quand''': Si vous voulez que des actions particulières s'exécutent suite au déclenchement d'actions standards de Dolibarr (exemple: je veux mettre à jour une table de mon module quand une facture se crée dans Dolibarr), il vous faut créer un fichier de '''triggers'''.

Voir aussi [[Interfaces_Dolibarr_vers_exterieur|Interfaces de Dolibarr vers l'exterieur]]
et [[Interfaces_Exterieur_vers_Dolibarr|Interfaces exterieures vers Dolibarr]]

== Insérer votre code aux emplacement hooks de Dolibarr (optionnel) ==
'''Quand''': Quand vous voulez modifier ou ajouter du code autrement que lors d'un événement métier (voir le chapitre précédent pour cela).

Voir la page [[Système de Hooks]].

== Ajouter un module de numérotation (optionnel) ==
'''Quand''': Lorsque vous voulez ajouter une règle de numérotation non couverte par les modules par défaut.

Voir la page [[Créer un module de numérotation]].

== Ajouter un nouveau modèle de document (optionnel) ==
'''Quand''': Lorsque vous voulez ajouter un nouveau modèle de document.

La documentation au sujet de la génération de documents depuis des modèles est disponible sur la page [[Créer un modèle de document PDF]] ou [[Créer un modèle de document ODT]].

== Ajouter un thème (optionnel) ==
'''Quand''': Lorsque vous voulez une interface aux couleurs personnalisées à votre cas.

Voir la page [[Themes]].

= [[File:Art.png]] Quelques règles de codage et fonctions pour développeurs =
Les règles de codage à suivre sont définis dans la [[Documentation Développeur|Documentation développeur]], rubrique "Informations Générales - Langage et normes de développement".

De nombreuses fonctions prédéfinies pour les développeurs sont disponibles et décrites sur la page [[Documentation Développeur|Documentation développeur]] sous la section "Les couches techniques de Dolibarr".

= [[File:Art.png]] Utilisation du MDA =
Une méthode pour générer un module fonctionnel depuis l'UML est en cours de mise au point. Plus d'informations sur la page [[UML2Dolibarr - Générer un module par MDA]].

= [[File:Art.png]] Créer un package pour livrer et installer votre module =
Cette procédure doit être utilisé pour fabriquer un package afin de le soumettre sur la place de marché http://www.dolistore.com.
Mais vous pouvez aussi l'utiliser pour distribuer facillement votre module via votre propre réseau de distribution.

* Aller dans le répertoire '''/build''' et recopier le fichier '''makepack-dolibarrmodules.conf''' en '''makepack-monmodule.conf'''. Attention, ce répertoire peut ne pas être fourni dans les packages de versions stables. Si c'est le cas, il peut être récupéré dans le snapshot disponible en téléchargement sur le site web Dolibarr dans la rubrique Version de développement (prendre dans ce cas tout le répertoire build qui est un répertoire autonome et indépendant de la version).
Saisissez dans ce fichier la liste des noms des nouveaux fichiers que vous avez créé pour votre module (descripteur de module, nouveaux fichiers sql de tables, page php, images, etc...)

* Lancer le script via Perl (besoin de la version Perl 5.0 ou +):
<source lang="bash">
perl makepack-dolibarrmodule.pl
</source>
Le script vous demande le nom de votre module, sa version majeure et mineure.
Un fichier '''monmodule.zip''' va alors être fabriqué contenant votre module prêt pour être déployé.

* La personne qui reçoit votre module doit alors placer le fichier dans son répertoire racine d'installation de Dolibarr et réaliser la commande:
<source lang="bash">
tar -xvf monmodule.zip
</source>

* Si vous désirez que votre module profite à tous, vous pouvez le soumettre (le fichier zip) sur la place de marché des modules complémentaires: {{LinkToPluginDownload}} (vous devez avoir créer un compte auparavant et utiliser le lien "Soumettre un module/produit").
** Si votre module a été fabriqué correctement, le fichier sera validé rapidement.
** Si la qualité est suffisante, que la licence le permet et que la fonctionnalité du module s'avère être d'un intérêt général, le code pourra être ajouté au code source de Dolibarr (sauf si vous ne le désirez pas).

= [[File:Art.png]] Validation/activation du module externe sur Dolistore =

Voir [[Module_Dolistore_Validation_Regles|Règles de Validation]]

Développement module

2018-02-12T12:20:12Z

Delcroip: /* Créer vos fichiers .sql */

[[Category:Noyau]]
{{TemplateDocDev}}
Pour créer un nouveau module, il existe plusieurs étapes. Ce didacticiel a pour but de vous décrire chacune d'elle afin d'ajouter un module permettant d'étendre les possibilités de Dolibarr, comme par exemple ajouter une ou plusieurs des fonctionnalités suivantes:
* Ajouter de nouvelles tables en base
* Ajouter vos propres entrées dans les menus
* Ajouter des écrans de saisie/consultation de nouvelle tables
* Ajouter ou supprimer des onglets sur les pages de vues/édition des objets (facture, produit, commande, événement, ...)
* Ajouter des exports prédéfinis pour la fonction export
* Ajouter de nouvelles boites pour la home page
* Ajouter des variables de substitutions
* Définir de nouvelles permissions
* Déclencher du code automatiquement sur une action Dolibarr particulière
* Insérer votre code aux emplacement hooks de Dolibarr
* Ajouter un module de numérotation
* Ajouter un modèle de document
* Ajouter un nouveau thème
etc...
Toutes ces opérations ne sont possibles qu'avec la version 3.2 ou plus de Dolibarr.

Les chapitres suivants vous présentent comment réaliser tout cela en manuel de manière simple. Pour les développeurs très expérimentés, une méthode par génération MDA est en cours de mise au point. Voir le dernier chapitre pour cela.

= [[File:Art.png]] Exemple de modèle de module externe=

Un bon modéle/squelette de module externe Dolibarr est disponible ici : [https://github.com/Dolibarr/dolibarr/tree/develop/htdocs/modulebuilder/template GitHub Dolibarr Module Modèle]

= [[File:Art.png]] Créer un module =
Les sous chapitres suivant décrivent les actions à faire pour créer un module Dolibarr. Les premiers chapitres sont obligatoires quelle que soit la vocation du module, les suivants dépendront de ce que doit faire le module.

== Créer un descripteur de Module (obligatoire) ==
'''Quand''': Obligatoire dès qu'une extension est développée, quelle que soit sa vocation (sauf pour l'ajout de thème ou de modèle de document).

=== Créer votre descripteur ===
La première étape est donc de créer un fichier de description du module (descripteur). Pour cela:
* Créer le répertoire '''/htdocs/''monmodule''/core/modules'''. Puis, aller dans le répertoire '''dev/skeletons''' et recopier le fichier modMyModule.class.php dans ce répertoire '''htdocs/''monmodule''/core/modules'''.
* Renommez le fichier mod'''MyModule'''.class.php en modifiant seulement la partie '''MyModule''' (le fichier doit commencer par mod)
Ensuite, modifier le contenu de ce fichier afin de remplacer:
* les ''modMyModule'' en une valeur qui corresponde à la vocation de votre module. Cette valeur doit toujours commencer par ''''mod'''' et ne contenir que des '''caractères alphabétiques'''.
* $this->numero = ''100000'' par un numéro de module libre. Pour éviter tout conflit, vous pouvez consulter la page suivante pour retrouver les numéros déjà alloués: [[List of modules id|Liste des id de modules]].
* Modifier éventuellement les autres variables définies dans le constructeurs (Voir le commentaire dans le code du squelette pour leur signification).

Le descripteur de votre module est alors en place.

=== Tester votre descripteur ===

Lancer Dolibarr et aller sur la page '''Configuration->module''', vous devez voir apparaître une nouvelle ligne avec votre nouveau module et la possibilité de l'activer ou non (parcourez tous les onglets de chaque catégories de modules jusqu'à le retrouver).
C'est la valeur de $this->special qui détermine dans quel onglet se trouve votre module.

== Arborescence d'un nouveau module ==
Voici l'arborescence à respecter pour l'organisation des fichiers d'un module.

Rem: Seule la deuxième ligne est obligatoire.
{{TemplateModuleTreeSimple}}

Un modèle de module a été crée par un contributeur Dolibarr, il est accessible ici : [https://github.com/rdoursenaud/dolibarr-module-template]

== Créer vos tables SQL et les classes PHP DAO (optionnel) ==
'''Quand''': Si votre module a besoin de gérer des données qui lui sont propres

=== Créer vos fichiers .sql ===
Si votre module a vocation à gérer des données bien à lui, qui n'existent pas en base dans la version standard de Dolibarr, il est nécessaire de définir des tables SQL pour stocker ces données.

Créer un sous-répertoire '''sql''' dans le répertoire de votre module (par exemple '''htdocs/monmodule/sql''') afin d'y placer les scripts sql que vous allez créer.

Ensuite, vérifiez dans votre fichier descripteur de module, dans la fonction '''init''' que la ligne

<source lang="php">$this->_load_tables('/mymodule/sql/');</source>

n'est pas commentée.

''Règles à respecter:''
* Ajouter les fichiers d'ordre de création de vos tables sur le principe d'un fichier '''llx_matable.sql''' par table accompagné éventuellement du fichier '''llx_matable.key.sql''' (voir les fichiers existants dans '''install/mysql/tables''' pour exemple).
* Pour ce qui est des commandes pour ajouter/manipuler des données, elles doivent toutes se trouver dans un fichier nommé '''data.sql''' situé dans le même répertoire '''/monmodule/sql/'''.
* N'utilisez pas "chaine" mais 'chaine' car les guillemets doubles (") ont une sinification particulière en PostGreSQL
Exemple de contenu de fichier data.sql
<source lang="sql">
delete from llx_const where name='MONMODULE_IT_WORKS' and entity='__ENTITY__';
insert into llx_const (name, value, type, note, visible, entity) values ('MONMODULE_IT_WORKS','1','chaine','A constant for my module',1,'__ENTITY__');
</source>

Les ordres SQL des fichiers doivent être opérationnels pour la base de données '''mysql'''.
Rem: Les fichiers des autres bases ne sont pas à maintenir. Ils sont lus et convertit à la volée par le driver de la base de données.

=== Tester vos fichier .sql ===

Une fois les fichiers prêts, vous pouvez retourner sous Dolibarr puis désactiver le module, dropper les tables en base et réactiver le module.
Les tables doivent alors être recréées par l'activation du module.
Si tel n'est pas le cas, vérifiez vos scripts en les passant à la main, ou consultez les logs Dolibarr.

=== Générer la classe PHP DAO d'accès aux tables ===

Une fois votre ou vos tables créées en base, aller dans le répertoire '''dev/skeletons''', copiez le fichier '''build_class_from_table.php''' dans le répertoire sql/ de votre module, et lancez le script
<source lang="bash">php build_class_from_table.php nomtable</source>
Remarque: Si la commande ne fonctionne pas, essayer d'utiliser php-cli plutot que php.

Ceci génèrera un fichier '''out.nomtable.class.php''' qui contient la classe de gestion de la table nomtable.
Dans cette classe, se trouve des méthodes CRUD (Create/Read/Update/Delete) déjà opérationnelles pour faire un insert, un fetch (select), un update, un delete d'une ligne de la table.
Supprimer juste le "out" du nom de fichier et placer votre fichier dans le sous-répertoire de '''htdocs''' propre à votre module (Dans '''htdocs/monmodule''' par exemple).

Un fichier '''out.nomtable_script.php''' a également été généré et contient un exemple de code pour utiliser la classe pour chacune des 4 méthodes CRUD.

== Affichage des onglets (optionnel) ==

=== Ajouter ou supprimer des onglets sur les fiches objets ===
'''Quand''' : Pour ajouter votre propre onglet parmi les onglets standard d'une fiche entité (facture, commande, proposition commercial, adhérent...)

Pour cela, aller dans le fichier descripteur de module précédemment créé et modifier le tableau $this->tabs:
<source lang="php">
// Array to add new pages in new tabs or remove existing one
$this->tabs = array('objecttype:+tabname1:Title1:mylangfile@monmodule:$user->rights->monmodule->read:/monmodule/mapagetab1.php?id=__ID__' // To add a new tab identified by code tabname1
'objecttype:+tabname2:Title2:mylangfile@monmodule:$user->rights->monmodule->read:/monmodule/mapagetab2.php?id=__ID__', // To add a new tab identified by code tabname2
'objecttype:-tabname'); // To remove an existing tab identified by code tabname
</source>

Le tableau doit contenir une liste de chaîne, chaque chaîne représentant un nouvel onglet.
Le format de la chaîne étant composé de 6 parties séparées par ":"
* Partie 1: Le type d'élément (objecttype) dans lequel doit apparaître l'onglet qui est une valeur parmi celle-ci:
{{TemplateModuleTabs-fr}}
* Partie 2: Nom de code pour l'onglet à ajouter (commence par +) ou à enlever (commence par -)
* Partie 3: Le titre de l'onglet. Cela peut être un libellé en dur ou mieux un code traduction présent dans un fichier lang.
* Partie 4: Le nom du fichier .lang (sans l'extension .lang) qui contient la correspondance entre le code traduction et le libellé à afficher. Si ce com est suivi de @monmodule, Dolibarr cherche le fichier dans le répertoire lang propre au module, c'est à dire htdocs/monmodule/langs/code_CODE/monmodule.lang, sinon Dolibarr cherche le fichier traduction dans htdocs/langs/code_CODE/mylangfile.lang
* Partie 5: Une condition à tester pour savoir si l'onglet doit être visible ou pas. Mettre '1' pour qu'il soit toujours visible.
* Partie 6: L'url de la page à afficher quand on clique sur l'onglet. La chaine __ID__ sera remplacée automatiquement par l'Id de l'entité concernée.

Pour que la déclaration soit effective, il faut désactiver et réactiver le module.

Pour alimenter le contenu de l'onglet avec des données issues de la base, voir le chapitre suivant.

=== Ajouter les onglets standard d'un objet sur sa propre page ===
'''Quand''' : Pour afficher les onglets standard d'une fiche entité (produit, tiers, etc.) sur votre propre page onglet d'une entité.

Il faut appliquer la procédure suivante :

'''1. Inclure les fichiers définissant les fonctions utiles dans vos fichiers'''

Pour chaque fiche entité, il y a deux fichiers à inclure avec l'instruction
<source lang="php">require_once($url_fichier) ;</source>

Voici quelques examples de fichiers à inclure (DOL_DOCUMENT_ROOT correspond au dossier dolibarr/htdocs/) :
* Entité tiers (thirdparty) :
** DOL_DOCUMENT_ROOT/societe/class/societe.class.php
** DOL_DOCUMENT_ROOT/core/lib/company.lib.php
* Entité produit (product) :
** DOL_DOCUMENT_ROOT/product/class/product.class.php
** DOL_DOCUMENT_ROOT/core/lib/product.lib.php
* Entité facture (invoice) :
** DOL_DOCUMENT_ROOT/compta/facture/facture.class.php
** DOL_DOCUMENT_ROOT/core/lib/invoice.lib.php

'''2. Créer et charger l'objet à afficher dans votre onglet'''

Créer l'objet de la classe voulue, et récupérer les données de l'objet à partir de la base de données. Pour cela il faut utiliser les fonctions fetch() de la classe correspondante, en passant en paramètre l'identifiant de l'objet que vous récupérez depuis l'url (ex : /mononglet.php?id=1).

''Exemple :''
<source lang="php">
$id=GETPOST('id','int');
$ref=GETPOST('ref','alpha');
$product = new Product($db) ;
$result = $product->fetch($id, $ref) ; //Tester $result pour vérifier que l'accès à la base s'est bien passée
</source>

'''3. Récupérer la liste des onglets correspondants à l'entité choisie'''

Utiliser la fonction XXX_prepare_head($obj), ou XXX est le nom de l'entité, permettant de créer un tableau contenant les définitions des onglets à afficher. Le paramètre à passer est l'objet pour lequel vous voulez afficher les onglets.

Le tableau retourné est composé de la façon suivante :
<source lang="php">
$head // Tableau des onglets
$head[$h] // Élément décrivant un onglet. Il y aura autant de $h que d'onglets à afficher
$head[$h][0] // Url de la page affichée quand on clique sur l'onglet
$head[$h][1] // Titre de l’onglet
$head[$h][2] // Code de l'onglet, à utiliser pour choisir quel onglet sera 'actif' (voir paragraphe suivant)
</source>

''Exemple :''
<source lang="php">
$head = product_prepare_head($product, $user) ; //le paramètre $user n'est pas présent sur certaines fonctions
</source>

'''4. Afficher les onglets sur votre page onglet'''

Utiliser la fonction dol_fiche_head() qui affiche les onglets contenus dans le tableau $head retourné par XX_prepare_head().

<source lang="php">
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
</source>

Cette fonction affiche les onglets voulus et ouvre un élément ''< div class="" >'' qui correspond à la zone bleue sous les onglets (si paramètre $notab = 0). Pour fermer la zone bleue, il suffit de fermer l'élément ''< /div >'' dans le code PHP.

''Remarque'':
Pour plus de détail, se référer à la [http://www.dolibarr.fr/doxygen/ documentation Doxygen] ou directement au code de Dolibarr.

== Créer vos pages écran PHP (optionnel) ==
'''Quand''': Si l'objet de votre module est d'ajouter des fonctionnalités qui nécessitent de nouveaux écrans.

=== Créer une page écran PHP brute ===
Vous pouvez ensuite créer vos pages PHP, qui se basent sur les données de vos tables, en utilisant les squelettes fournis comme exemple dans le répertoire '''modulebuilder''' (Pour le développement d'un script en ligne de commande, voir [[Développement de scripts]]).

Pour créer une nouvelle page écran utilisateur, créer un sous-répertoire de '''htdocs''' (si non déjà fait) propre à votre module (Dans '''htdocs/monmodule''' par exemple) afin d'y placer les pages que vous aller créer.

Y recopier le fichier '''myobject_page.php''' qui va servir de point de départ.
Modifier le fichier afin que le main.inc.php soit trouvés
<source lang="php">
// Load Dolibarr environment
$res=0;
// Try main.inc.php into web root known defined into CONTEXT_DOCUMENT_ROOT (not always defined)
if (! $res && ! empty($_SERVER["CONTEXT_DOCUMENT_ROOT"])) $res=@include($_SERVER["CONTEXT_DOCUMENT_ROOT"]."/main.inc.php");
// Try main.inc.php into web root detected using web root caluclated from SCRIPT_FILENAME
$tmp=empty($_SERVER['SCRIPT_FILENAME'])?'':$_SERVER['SCRIPT_FILENAME'];$tmp2=realpath(__FILE__); $i=strlen($tmp)-1; $j=strlen($tmp2)-1;
while($i > 0 && $j > 0 && isset($tmp[$i]) && isset($tmp2[$j]) && $tmp[$i]==$tmp2[$j]) { $i--; $j--; }
if (! $res && $i > 0 && file_exists(substr($tmp, 0, ($i+1))."/main.inc.php")) $res=@include(substr($tmp, 0, ($i+1))."/main.inc.php");
if (! $res && $i > 0 && file_exists(dirname(substr($tmp, 0, ($i+1)))."/main.inc.php")) $res=@include(dirname(substr($tmp, 0, ($i+1)))."/main.inc.php");
// Try main.inc.php using relative path
if (! $res && file_exists("../main.inc.php")) $res=@include("../main.inc.php");
if (! $res && file_exists("../../main.inc.php")) $res=@include("../../main.inc.php");
if (! $res && file_exists("../../../main.inc.php")) $res=@include("../../../main.inc.php");
if (! $res) die("Include of main fails");
</source>
Notez qu'il est possible que vous deviez ajouter plus de "../" dans les chemin, en fonction de la profondeur de vos fichiers par rapport au répertoire de votre module.

Pour tous les modules développés après la version 3.2 de Dolibarr, il convient de pouvoir placer un répertoire de module soit dans '''htdocs''' soit dans un sous répertoire comme '''htdocs/custom''' sans avoir à modifier le code source du module, c'est pour cela que cette règle doit obligatoirement être appliquée.

C'est dans le main qu'est chargé l'environnement technique ainsi que les habilitations. Les variables objets suivantes sont alors positionnées:

* $user L'objet qui contient les caractéristiques de l'utilisateur + ses droits.
* $conf L'objet qui contient la configuration de Dolibarr.
* $db L'objet qui contient le handler de connexion ouvert à la base de données.
* $langs L'objet qui contient la langue de l'utilisateur.

* L'inclusion d'une classe ou librairie dédiée au module, sans savoir d'où le fichier sera appelé, se fait en utilisant une fonction de Dolibarr (et non en utilisant directement le include_once)
''Exemple :''
<source lang="php">
dol_include_once('/monmodule/class/maclasse.class.php', 'MaClasse');
</source>

* L'appel des classes fournies en standard avec Dolibarr se fera par contre par le require_once directe avec la syntaxe suivante:
''Exemple :''
<source lang="php">
require_once DOL_DOCUMENT_ROOT.'/core/class/doli.class.php';
</source>
La raison est que si le dol_include_once est pratique car il scanne chaque répertoire de chemin alternatifs pour trouver le fichier, il est aussi moins performant car génère des accès et recherches disque à chaque appel (en effet, PHP intègre un cache des fichiers lus mais n'intègre pas un cache des fichiers "non trouvés". Et comme un fichier donné n'est que dans une seule arborescence, il y a toujours une arborescence alternative où il ne se trouve pas et qui génère des accès superflus au disque dur, pénalisant en terme de performance. Comme pour les fichiers internes à Dolibarr, on connait toujours le chemin exacte, le require_once avec ce chemin direct doit être préféré).

=== Remplacer les parties d'écrans templatés (version 3.3+) ===
Certaines portion d'écran de Dolibarr sont isolés dans des fichiers templates.
Vous pouvez développer un module pour remplacer un ou plusieurs de ces templates par les vôtres.
{{ToComplete}}

=== Accès à la base ===
Si vous avez besoin de réaliser des modifications en base dans votre propre table ajoutée, utilisez la classe générée plus haut qui contient les méthodes pour cela.

Si toutefois vous voulez faire des accès dans des tables sans objet PHP dédié, ceci reste possible (par exemple pour récupérer une liste d'enregistrement). Dans ce cas, pensez à suivre ces exemples:

Pour un insert, update ou delete:

<source lang="php">
$db->begin(); // Debut transaction
$db->query("Ma requete insert, update ou delete");
$db->commit(); // Valide
ou $db->rollback() // Annule
</source>

Pour une lecture:

<source lang="php">
$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++;
}
}
}
</source>

=== Définition du style ===
Pour que le look de la page soit aligné avec le thème Dolibarr, il est nécessaire d'utiliser les styles des CSS de Dolibarr.

Par exemple:

* class="'''liste_titre'''" sur les balises ''tr'' et ''td'' pour une ligne de titre de tableau.
* class="'''pair'''" ou class="'''impair'''" sur les balises ''tr'' et ''td'' des lignes de données de tableau.
* class="'''flat'''" sur tous les champs de saisie (''input, select, textarea''...).
* class="'''button'''" sur les objets de type ''input type="submit"''.

=== Utiliser le sélecteur de date de Dolibarr ===
Si vous le désirez, vous pouvez profiter du sélecteur de date dans des écrans Dolibarr. Pour cela, utilisez la ligne suivante:
<source lang="php">
$form=new Form($db);
$form->select_date('','mykey',0,0,0,"myform");
</source>
La chaine mykey identifie la zone date. Il faut y mettre une valeur différente s'il y a plusieurs zones.
La chaine myform est le nom de la zone FORM (dans form name="myform" de la page HTML).
L'affichage d'un sélecteur de date doit donc être intégrée dans une zone FORM Html.

Pour récupérer la valeur, à l'issu du POST, la commande est:
<source lang="php">
$mydate = dol_mktime(12, 0 , 0, $_POST['mykeymonth'], $_POST['mykeyday'], $_POST['mykeyyear']);
print strftime('%A %d %B %Y', $mydate);
</source>

== Définir votre page de configuration (optionnel) ==
'''Quand''': Si votre module offre plusieurs options paramétrables.

=== Créer votre page d'édition de configuration ===
Si votre module offre plusieurs options paramétrables, il est nécessaire de créer une page PHP pour éditer les options (qui sont stockées dans la [[Table llx_const|table '''llx_const''']]).
Créer une page PHP nommée '''monmodule_setupapage.php''' qui affiche les options possibles et les met à jour.
Il est nécessaire de prendre exemple sur une page dans '''/admin''' qui vous montre la méthode pour lire ou sauvegarder en base votre option.
Placer cette page de configuration dans le répertoire '''/admin''' également.
Ensuite dans le descripteur de module, modifier la variable pour indiquer le nom de cette page PHP (sans le chemin qui n'est pas nécessaire, la page étant forcément dans le rep admin).
<source lang="php">
$this->config_page_url = array("monmodule_setupapage.php");
</source>

=== Tester votre page ===
Allez sur la page '''Configuration->module''', vous devez voir apparaître une icône qui permet d'accéder à la page de configuration et vous devez être capable de modifier ces options et les voir conservées en base.

== Définir vos entrées de menu (optionnel) ==
'''Quand''': Si vous avez créé des pages PHP, il est nécessaire que ces écrans soient accessibles depuis le menu Dolibarr.

=== Définissez vos entrées menus ===
Pour cela, il vous faut définir dans le fichier descripteur de module, le tableau this->menu qui déclare les menus.
Ce tableau contient toutes les entrées qui apparaîtront dans les menus une fois le module activé.
Le fichier de descripteur de module exemple '''modMonModule.class.php''' possède un exemple de déclaration de menu haut ainsi que de ses entrées menu gauche associées.

Voici un exemple de déclaration d'entrées de menu dans le fichier descripteur:
<source lang="php">
// 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( 'fk_menu'=>0, // Put 0 if this is a top menu
'type'=>'top', // This is a Top menu entry
'titre'=>'MonModule top menu',
'mainmenu'=>'monmodule',
'leftmenu'=>'monmodule',
'url'=>'/monmodule/pagetop.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->monmodule->enabled' if entry must be visible if module is enabled.
'perms'=>'1', // Use 'perms'=>'$user->rights->monmodule->level1->level2' if you want your menu with a permission rules
'target'=>'',
'user'=>2); // 0=Menu for internal users, 1=external users, 2=both
$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 of parent menu
'type'=>'left', // This is a Left menu entry
'titre'=>'MonModule left menu 1',
'mainmenu'=>'xxx',
'leftmenu'=>'yyy',
'url'=>'/monmodule/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->monmodule->enabled' if entry must be visible if module is enabled.
'perms'=>'1', // Use 'perms'=>'$user->rights->monmodule->level1->level2' if you want your menu with a permission rules
'target'=>'',
'user'=>2); // 0=Menu for internal users,1=external users, 2=both
$r++;
</source>

Pour conditionner l'accès au menu selon des permission, modifier la propriété '''perms''' du tableau. Voir le chapitre sur les permissions un peu plus loin pour savoir comment ajouter des permissions.

=== Tester vos entrées menus ===
Désactiver et réactiver votre module sous Dolibarr, les entrées menus doivent alors apparaître (si la condition dans 'enabled' est vraie).

== Définir vos propres permissions (optionnel) ==
'''Quand''': Si vous voulez ajouter de nouvelles permissions.

La définition des permissions que gérera votre module se fait dans le fichier descripteur créé dans la première étape.
Modifier la ligne
<source lang="php">
$this->rights_class = 'monmodule'
</source>
pour y mettre la bonne valeur de monmodule.

Ensuite remplissez le tableau $this->rights avec autant d'entrées que de permissions différentes à gérer.

<source lang="php">
$this->rights[$r][0] = 10001;
$this->rights[$r][1] = 'Libelle par défaut de ma permission';
$this->rights[$r][3] = 1;
$this->rights[$r][4] = 'action';
$this->rights[$r][5] = 'sousaction';
$r++;
</source>

Dans $this->rights[$r][0], mettre un id de permission non déjà pris (Voir dans le menu '''Infos Système''' sur une installation de Dolibarr opérationnelle pour connaitre les id déjà utilisés.
Dans $this->rights[$r][3], mettre 1 si cette permission est attribué d'office par défaut quand un utilisateur est créé.
Dans $this->rights[$r][1], mettre un libellé par défaut (il sera affiché si aucune traduction n'est trouvé pour votre permission dans le fichier '''admin.lang''').
Dans $this->rights[$r][4] et $this->rights[$r][5], mettre une chaîne action et sousaction sans espaces. Vous pourrez alors tester dans le code PHP si un utilisateurs a bien les droits par la séquence suivante:

<source lang="php">
if ($user->rights->monmodule->action->sousaction) ...
</source>

== Définir vos propres box (optionnel) ==
'''Quand''': Si votre module amène avec lui une ou plusieurs Boxes.

=== Définissez vos box ===
Pour cela, modifiez les tableaux $this->boxes du fichier descripteur de module.
Il suffit d'ajouter 2 lignes par fichier box que vous allez créer dans le répertoire '''htdocs/monmodule/core/boxes'''

''Exemple:''
<source lang="php">
$this->boxes[0]['file']='mabox0.php@monmodule'
$this->boxes[0]['note']='Ma box 0'
...
$this->boxes[n]['file']='maboxn.php@monmodule'
$this->boxes[n]['note']='Ma box n'
</source>

Ensuite créer les fichiers '''htdocs/monmodule/core/boxes/mabox0.php''', '''htdocs/monmodule/core/boxes/mabox1.php'''... en prenant exemple sur des box existantes (exemple dans le répertoire '''htdocs/core/boxes''')

=== Tester la présence de vos box dans Dolibarr ===
Désactiver et réactiver le module.

Aller dans le menu '''Accueil - Configuration - Boite'''.

Vos box doivent apparaître dans la liste des box activables. Activer les puis aller sur la page d'accueil et vérifier qu'elles s'affichent correctement.

== Définir vos propres exports (optionnel) ==
'''Quand''': Si votre module amène avec lui des exports prédéfini de données (pour ces propres tables ou des tables déjà existante d'un autre module de Dolibarr).

=== Définissez l'export ===
Pour cela, décommenter et modifier les tableaux $this->export_xxx du votre fichier descripteur de module.

=== Tester votre export ===
Aller dans le menu outils -> export de Dolibarr. Votre export doit apparaitre dans la liste des exports prédéfinis disponible (si votre module est bien activé).
Le choisir, vous devez alors voir les champs possible définis dans le tableau à l'étape précédente.
Choisir quelques champs et tenter une génération du fichier export.

== Définir vos styles CSS (optionnel) ==
'''Quand''': Si dans vos écrans PHP, vous utiliser des classes de styles qui ne sont pas celle des thèmes de Dolibarr (non recommandé).

Cette fonctionnalité est décrite mais pas encore opérationnel en 2.4

=== Créer et déclarer votre feuille de style ===
Créer un fichier de style css nommé '''monmodule.css''' ou '''monmodule.css.php''' et le placer dans le répertoire '''''monmodule''''' dans '''htdocs'''. Il ne peut y avoir qu'un fichier css propre à chaque module.
Rappelons qu'il vaut mieux utiliser les styles déjà existant de Dolibarr (le fichier css utilisé par Dolibarr étant le fichier '''themes/nomtheme/''nomtheme''.css.php'''). Ne créer un fichier css propre à votre module que si vous devez absolument gérer des styles non déjà existants.
Une fois votre feuille de style prête, déclarer la dans votre fichier descripteur de module en modifiant la propriété '''$this->module_parts'''.
La valeur à renseigner ici doit être le chemin relatif de l'URL de votre fichier css.
Par exemple
<source lang="php">
$this->module_parts = array('css' => array('/monmodule/css/monmodule.css.php'));
</source>

=== Tester votre feuille de style ===
Désactiver et réactiver votre module.

Appelez la page d'accueil de Dolibarr. Afficher la source de la page HTML.

Vous devriez voir dans l'entête HTML, une ligne déclarant votre feuille de style.

== Définir vos fonctions Javascript (optionnel) ==
'''Quand''': Si dans vos écrans PHP, vous utiliser des fonctions javascript non dispo en standard (fichier lib_head.js)

Si dans vos écrans PHP, vous utilisez des fonctions javascript, il est nécessaire de faire en sorte que vos fonctions déclarées dans un fichier javascript '''htdocs/monmodule/js/monmodule.js''' soit chargées dans l'entête head html.
Pour demander à Dolibarr qui gère la génération de la section header d'inclure un de vos fichiers javascript, il est nécessaire de fournir en paramètre de la fonction llxHeader() appelée au début de votre page, d'inclure le paramètre qui contient l'URL vers le js à inclure.

Exemple pour la page /htdocs/monmodule/mapage.php :
<source lang="php">
require('../main.inc.php');
$morejs=array("/monmodule/js/monmodule.js");
llxHeader('','Titre','','','','',$morejs,'',0,0);
</source>

== Déclencher du code sur un évènement Dolibarr (optionnel) ==
'''Quand''': Si vous voulez que des actions particulières s'exécutent suite au déclenchement d'actions standards de Dolibarr (exemple: je veux mettre à jour une table de mon module quand une facture se crée dans Dolibarr), il vous faut créer un fichier de '''triggers'''.

Voir aussi [[Interfaces_Dolibarr_vers_exterieur|Interfaces de Dolibarr vers l'exterieur]]
et [[Interfaces_Exterieur_vers_Dolibarr|Interfaces exterieures vers Dolibarr]]

== Insérer votre code aux emplacement hooks de Dolibarr (optionnel) ==
'''Quand''': Quand vous voulez modifier ou ajouter du code autrement que lors d'un événement métier (voir le chapitre précédent pour cela).

Voir la page [[Système de Hooks]].

== Ajouter un module de numérotation (optionnel) ==
'''Quand''': Lorsque vous voulez ajouter une règle de numérotation non couverte par les modules par défaut.

Voir la page [[Créer un module de numérotation]].

== Ajouter un nouveau modèle de document (optionnel) ==
'''Quand''': Lorsque vous voulez ajouter un nouveau modèle de document.

La documentation au sujet de la génération de documents depuis des modèles est disponible sur la page [[Créer un modèle de document PDF]] ou [[Créer un modèle de document ODT]].

== Ajouter un thème (optionnel) ==
'''Quand''': Lorsque vous voulez une interface aux couleurs personnalisées à votre cas.

Voir la page [[Themes]].

= [[File:Art.png]] Quelques règles de codage et fonctions pour développeurs =
Les règles de codage à suivre sont définis dans la [[Documentation Développeur|Documentation développeur]], rubrique "Informations Générales - Langage et normes de développement".

De nombreuses fonctions prédéfinies pour les développeurs sont disponibles et décrites sur la page [[Documentation Développeur|Documentation développeur]] sous la section "Les couches techniques de Dolibarr".

= [[File:Art.png]] Utilisation du MDA =
Une méthode pour générer un module fonctionnel depuis l'UML est en cours de mise au point. Plus d'informations sur la page [[UML2Dolibarr - Générer un module par MDA]].

= [[File:Art.png]] Créer un package pour livrer et installer votre module =
Cette procédure doit être utilisé pour fabriquer un package afin de le soumettre sur la place de marché http://www.dolistore.com.
Mais vous pouvez aussi l'utiliser pour distribuer facillement votre module via votre propre réseau de distribution.

* Aller dans le répertoire '''/build''' et recopier le fichier '''makepack-dolibarrmodules.conf''' en '''makepack-monmodule.conf'''. Attention, ce répertoire peut ne pas être fourni dans les packages de versions stables. Si c'est le cas, il peut être récupéré dans le snapshot disponible en téléchargement sur le site web Dolibarr dans la rubrique Version de développement (prendre dans ce cas tout le répertoire build qui est un répertoire autonome et indépendant de la version).
Saisissez dans ce fichier la liste des noms des nouveaux fichiers que vous avez créé pour votre module (descripteur de module, nouveaux fichiers sql de tables, page php, images, etc...)

* Lancer le script via Perl (besoin de la version Perl 5.0 ou +):
<source lang="bash">
perl makepack-dolibarrmodule.pl
</source>
Le script vous demande le nom de votre module, sa version majeure et mineure.
Un fichier '''monmodule.zip''' va alors être fabriqué contenant votre module prêt pour être déployé.

* La personne qui reçoit votre module doit alors placer le fichier dans son répertoire racine d'installation de Dolibarr et réaliser la commande:
<source lang="bash">
tar -xvf monmodule.zip
</source>

* Si vous désirez que votre module profite à tous, vous pouvez le soumettre (le fichier zip) sur la place de marché des modules complémentaires: {{LinkToPluginDownload}} (vous devez avoir créer un compte auparavant et utiliser le lien "Soumettre un module/produit").
** Si votre module a été fabriqué correctement, le fichier sera validé rapidement.
** Si la qualité est suffisante, que la licence le permet et que la fonctionnalité du module s'avère être d'un intérêt général, le code pourra être ajouté au code source de Dolibarr (sauf si vous ne le désirez pas).

= [[File:Art.png]] Validation/activation du module externe sur Dolistore =

Voir [[Module_Dolistore_Validation_Regles|Règles de Validation]]

Module Timesheet

2017-08-14T08:39:04Z

Delcroip: /* Manual */

[[Category:Complementary modules]]
[[Category:timesheet]]
{{TemplateDocDevEn}}
{{TemplateDocUser}}
<keywords content="timesheet, Dolibarr, interface, project, task, report, approval" />

= Informations =
{{TemplateModuleInfo
|modulename=timesheet
|editor=delcroip
|webbuy={{LinkToPluginDownloadDoliStore|keyword=timesheet}}
|status=stable
|prerequisites=projects
|minversion=3.5.0
|maxversion=6.0
|note=Latest Module version: 2.0.1
}}

= Manual =
[https://wiki.dolibarr.org/upload/b/bd/Module_timesheet.pdf Timesheet 1.5.1 manual]

[https://wiki.dolibarr.org/upload/4/45/Module_timesheet_2.0.pdf Timesheet 2.0.1 manual]

= Features =

- Timesheet interface for all the user task per week
- Generate report on user and on project per month
- favourties to show only some project/task by a simple click on a start icon next to the task name
- Approval of the timesheets per the N+1
- Approval of the timesheets per project manager
- Generate project invoice from timesheet data

[[File:timesheet_timeentry.jpg]]

= Change logs =
2.0.1 Change log from 2.0
* Project approval corrected (for non admin no approval was shown)
* PHP warning removed
* Home timesheet box correted (was not showing the # of timesheet to approve)

2.0 Change log from 1.5.1
* Week on two month are spliced to enable monthly approval
* Chained approval for team & project.
* Create invoice with ad-hoc and already defined service based on time saved.
* Report always shows time in day and hours
* Layout change for the setup page
* Layout change for the favorite handling
* Email are sent to user when a timesheet is rejected by the team leader
* Note on task are shown as info when hoovering over the task line
* Searchbox are available instead of dropdown list (use other core module setup).
* More translation (ES, DE, IT, FR, US , mostly automated)
* Note editing available for each tasks (also in the approval flow)

Change log from 1.5
* Support dolibarr 4.0.1
* Hidden option to join file to timesheets via the setting TIMESHEET_ADD_DOCS

Change log from 1.4.3:
* Timesheet approval by N+1,
* Reminder (email) for to be approved timesheet possible through dolibarr planned tasks
* admin wiew for the Approval (change a approval status outside the normal approval flow)
* Home box with the pending timesheet to be approved
* Blocking some weekdays (e.g week ends)
* Holiday showed in the timesheet
* Holiday time can be included in the timesheet totals
* Typo correction for French.
* Posibility to add a note
* Compatible with dolibarr 3.9.2

Change log from 1.4.1:

* Correction of the Spanish language (thanks to vinclar)
* Possible to deactivate the dolibarr Ajax for the dropdown list for the setup page (in case of issue to add whitelist)
* Keep the whitlistmode after submit / go to date / next / previsous week

Change log from 1.4:
* Bugfix for the tasktime date in the project page
* Link to have the different whitelist behaviour (black list, and none)
* Spanish language (google trad)
* Typo correction for French
* Support the print mode for timesheet & the report
* Show the project open to everyone on the new whitelist page

Change log from 1.3.7:
* layout improvement: timesheet, setup page, reports
* whitelist to show only some project/task
* taslk column customisation
* new task column: company, parent task
* new report option: report all, export friendly layout
* user report available for the N-2, N-3

Change log from 1.3.6:
* compatible avec dolibarr 3.7
* Change log from 1.3.3:
* Works with PHP<=5.3
* Possibility to remove the 0:00
* Color code for already filled tasktime / new tasktime and error
* Bux fixes in the report
* Better date dialog
* N+1 is able to check the user report of his N's

Module Timesheet

2017-08-14T08:38:44Z

Delcroip: /* Informations */

[[Category:Complementary modules]]
[[Category:timesheet]]
{{TemplateDocDevEn}}
{{TemplateDocUser}}
<keywords content="timesheet, Dolibarr, interface, project, task, report, approval" />

= Informations =
{{TemplateModuleInfo
|modulename=timesheet
|editor=delcroip
|webbuy={{LinkToPluginDownloadDoliStore|keyword=timesheet}}
|status=stable
|prerequisites=projects
|minversion=3.5.0
|maxversion=6.0
|note=Latest Module version: 2.0.1
}}

= Manual =
[https://wiki.dolibarr.org/upload/b/bd/Module_timesheet.pdf Timesheet 1.5 manual]

[https://wiki.dolibarr.org/upload/4/45/Module_timesheet_2.0.pdf Timesheet 2.0.1 manual]

= Features =

- Timesheet interface for all the user task per week
- Generate report on user and on project per month
- favourties to show only some project/task by a simple click on a start icon next to the task name
- Approval of the timesheets per the N+1
- Approval of the timesheets per project manager
- Generate project invoice from timesheet data

[[File:timesheet_timeentry.jpg]]

= Change logs =
2.0.1 Change log from 2.0
* Project approval corrected (for non admin no approval was shown)
* PHP warning removed
* Home timesheet box correted (was not showing the # of timesheet to approve)

2.0 Change log from 1.5.1
* Week on two month are spliced to enable monthly approval
* Chained approval for team & project.
* Create invoice with ad-hoc and already defined service based on time saved.
* Report always shows time in day and hours
* Layout change for the setup page
* Layout change for the favorite handling
* Email are sent to user when a timesheet is rejected by the team leader
* Note on task are shown as info when hoovering over the task line
* Searchbox are available instead of dropdown list (use other core module setup).
* More translation (ES, DE, IT, FR, US , mostly automated)
* Note editing available for each tasks (also in the approval flow)

Change log from 1.5
* Support dolibarr 4.0.1
* Hidden option to join file to timesheets via the setting TIMESHEET_ADD_DOCS

Change log from 1.4.3:
* Timesheet approval by N+1,
* Reminder (email) for to be approved timesheet possible through dolibarr planned tasks
* admin wiew for the Approval (change a approval status outside the normal approval flow)
* Home box with the pending timesheet to be approved
* Blocking some weekdays (e.g week ends)
* Holiday showed in the timesheet
* Holiday time can be included in the timesheet totals
* Typo correction for French.
* Posibility to add a note
* Compatible with dolibarr 3.9.2

Change log from 1.4.1:

* Correction of the Spanish language (thanks to vinclar)
* Possible to deactivate the dolibarr Ajax for the dropdown list for the setup page (in case of issue to add whitelist)
* Keep the whitlistmode after submit / go to date / next / previsous week

Change log from 1.4:
* Bugfix for the tasktime date in the project page
* Link to have the different whitelist behaviour (black list, and none)
* Spanish language (google trad)
* Typo correction for French
* Support the print mode for timesheet & the report
* Show the project open to everyone on the new whitelist page

Change log from 1.3.7:
* layout improvement: timesheet, setup page, reports
* whitelist to show only some project/task
* taslk column customisation
* new task column: company, parent task
* new report option: report all, export friendly layout
* user report available for the N-2, N-3

Change log from 1.3.6:
* compatible avec dolibarr 3.7
* Change log from 1.3.3:
* Works with PHP<=5.3
* Possibility to remove the 0:00
* Color code for already filled tasktime / new tasktime and error
* Bux fixes in the report
* Better date dialog
* N+1 is able to check the user report of his N's

Module Timesheet

2017-08-14T08:38:13Z

Delcroip: /* Features */

[[Category:Complementary modules]]
[[Category:timesheet]]
{{TemplateDocDevEn}}
{{TemplateDocUser}}
<keywords content="timesheet, Dolibarr, interface, project, task, report, approval" />

= Informations =
{{TemplateModuleInfo
|modulename=timesheet
|editor=delcroip
|webbuy={{LinkToPluginDownloadDoliStore|keyword=timesheet}}
|status=stable
|prerequisites=projects
|minversion=3.5.0
|maxversion=4.0.4
|note=Latest Module version: 1.5.1
}}

= Manual =
[https://wiki.dolibarr.org/upload/b/bd/Module_timesheet.pdf Timesheet 1.5 manual]

[https://wiki.dolibarr.org/upload/4/45/Module_timesheet_2.0.pdf Timesheet 2.0.1 manual]

= Features =

- Timesheet interface for all the user task per week
- Generate report on user and on project per month
- favourties to show only some project/task by a simple click on a start icon next to the task name
- Approval of the timesheets per the N+1
- Approval of the timesheets per project manager
- Generate project invoice from timesheet data

[[File:timesheet_timeentry.jpg]]

= Change logs =
2.0.1 Change log from 2.0
* Project approval corrected (for non admin no approval was shown)
* PHP warning removed
* Home timesheet box correted (was not showing the # of timesheet to approve)

2.0 Change log from 1.5.1
* Week on two month are spliced to enable monthly approval
* Chained approval for team & project.
* Create invoice with ad-hoc and already defined service based on time saved.
* Report always shows time in day and hours
* Layout change for the setup page
* Layout change for the favorite handling
* Email are sent to user when a timesheet is rejected by the team leader
* Note on task are shown as info when hoovering over the task line
* Searchbox are available instead of dropdown list (use other core module setup).
* More translation (ES, DE, IT, FR, US , mostly automated)
* Note editing available for each tasks (also in the approval flow)

Change log from 1.5
* Support dolibarr 4.0.1
* Hidden option to join file to timesheets via the setting TIMESHEET_ADD_DOCS

Change log from 1.4.3:
* Timesheet approval by N+1,
* Reminder (email) for to be approved timesheet possible through dolibarr planned tasks
* admin wiew for the Approval (change a approval status outside the normal approval flow)
* Home box with the pending timesheet to be approved
* Blocking some weekdays (e.g week ends)
* Holiday showed in the timesheet
* Holiday time can be included in the timesheet totals
* Typo correction for French.
* Posibility to add a note
* Compatible with dolibarr 3.9.2

Change log from 1.4.1:

* Correction of the Spanish language (thanks to vinclar)
* Possible to deactivate the dolibarr Ajax for the dropdown list for the setup page (in case of issue to add whitelist)
* Keep the whitlistmode after submit / go to date / next / previsous week

Change log from 1.4:
* Bugfix for the tasktime date in the project page
* Link to have the different whitelist behaviour (black list, and none)
* Spanish language (google trad)
* Typo correction for French
* Support the print mode for timesheet & the report
* Show the project open to everyone on the new whitelist page

Change log from 1.3.7:
* layout improvement: timesheet, setup page, reports
* whitelist to show only some project/task
* taslk column customisation
* new task column: company, parent task
* new report option: report all, export friendly layout
* user report available for the N-2, N-3

Change log from 1.3.6:
* compatible avec dolibarr 3.7
* Change log from 1.3.3:
* Works with PHP<=5.3
* Possibility to remove the 0:00
* Color code for already filled tasktime / new tasktime and error
* Bux fixes in the report
* Better date dialog
* N+1 is able to check the user report of his N's

Module Timesheet

2017-08-14T08:36:17Z

Delcroip: /* Manual */

[[Category:Complementary modules]]
[[Category:timesheet]]
{{TemplateDocDevEn}}
{{TemplateDocUser}}
<keywords content="timesheet, Dolibarr, interface, project, task, report, approval" />

= Informations =
{{TemplateModuleInfo
|modulename=timesheet
|editor=delcroip
|webbuy={{LinkToPluginDownloadDoliStore|keyword=timesheet}}
|status=stable
|prerequisites=projects
|minversion=3.5.0
|maxversion=4.0.4
|note=Latest Module version: 1.5.1
}}

= Manual =
[https://wiki.dolibarr.org/upload/b/bd/Module_timesheet.pdf Timesheet 1.5 manual]

[https://wiki.dolibarr.org/upload/4/45/Module_timesheet_2.0.pdf Timesheet 2.0.1 manual]

= Features =

- Timesheet interface for all the user task per week
- Generate report on user and on project per month
- whitelist to show only some project/task (if no whitelist define all task are showed)
- Approval of the timesheets per the N+1

[[File:timesheet_timeentry.jpg]]

= Change logs =
2.0.1 Change log from 2.0
* Project approval corrected (for non admin no approval was shown)
* PHP warning removed
* Home timesheet box correted (was not showing the # of timesheet to approve)

2.0 Change log from 1.5.1
* Week on two month are spliced to enable monthly approval
* Chained approval for team & project.
* Create invoice with ad-hoc and already defined service based on time saved.
* Report always shows time in day and hours
* Layout change for the setup page
* Layout change for the favorite handling
* Email are sent to user when a timesheet is rejected by the team leader
* Note on task are shown as info when hoovering over the task line
* Searchbox are available instead of dropdown list (use other core module setup).
* More translation (ES, DE, IT, FR, US , mostly automated)
* Note editing available for each tasks (also in the approval flow)

Change log from 1.5
* Support dolibarr 4.0.1
* Hidden option to join file to timesheets via the setting TIMESHEET_ADD_DOCS

Change log from 1.4.3:
* Timesheet approval by N+1,
* Reminder (email) for to be approved timesheet possible through dolibarr planned tasks
* admin wiew for the Approval (change a approval status outside the normal approval flow)
* Home box with the pending timesheet to be approved
* Blocking some weekdays (e.g week ends)
* Holiday showed in the timesheet
* Holiday time can be included in the timesheet totals
* Typo correction for French.
* Posibility to add a note
* Compatible with dolibarr 3.9.2

Change log from 1.4.1:

* Correction of the Spanish language (thanks to vinclar)
* Possible to deactivate the dolibarr Ajax for the dropdown list for the setup page (in case of issue to add whitelist)
* Keep the whitlistmode after submit / go to date / next / previsous week

Change log from 1.4:
* Bugfix for the tasktime date in the project page
* Link to have the different whitelist behaviour (black list, and none)
* Spanish language (google trad)
* Typo correction for French
* Support the print mode for timesheet & the report
* Show the project open to everyone on the new whitelist page

Change log from 1.3.7:
* layout improvement: timesheet, setup page, reports
* whitelist to show only some project/task
* taslk column customisation
* new task column: company, parent task
* new report option: report all, export friendly layout
* user report available for the N-2, N-3

Change log from 1.3.6:
* compatible avec dolibarr 3.7
* Change log from 1.3.3:
* Works with PHP<=5.3
* Possibility to remove the 0:00
* Color code for already filled tasktime / new tasktime and error
* Bux fixes in the report
* Better date dialog
* N+1 is able to check the user report of his N's

Module Timesheet

2017-08-14T08:35:58Z

Delcroip: /* Manual */

[[Category:Complementary modules]]
[[Category:timesheet]]
{{TemplateDocDevEn}}
{{TemplateDocUser}}
<keywords content="timesheet, Dolibarr, interface, project, task, report, approval" />

= Informations =
{{TemplateModuleInfo
|modulename=timesheet
|editor=delcroip
|webbuy={{LinkToPluginDownloadDoliStore|keyword=timesheet}}
|status=stable
|prerequisites=projects
|minversion=3.5.0
|maxversion=4.0.4
|note=Latest Module version: 1.5.1
}}

= Manual =
[https://wiki.dolibarr.org/upload/b/bd/Module_timesheet.pdf Timesheet 1.5 manual]
[https://wiki.dolibarr.org/upload/4/45/Module_timesheet_2.0.pdf Timesheet 2.0.1 manual]

= Features =

- Timesheet interface for all the user task per week
- Generate report on user and on project per month
- whitelist to show only some project/task (if no whitelist define all task are showed)
- Approval of the timesheets per the N+1

[[File:timesheet_timeentry.jpg]]

= Change logs =
2.0.1 Change log from 2.0
* Project approval corrected (for non admin no approval was shown)
* PHP warning removed
* Home timesheet box correted (was not showing the # of timesheet to approve)

2.0 Change log from 1.5.1
* Week on two month are spliced to enable monthly approval
* Chained approval for team & project.
* Create invoice with ad-hoc and already defined service based on time saved.
* Report always shows time in day and hours
* Layout change for the setup page
* Layout change for the favorite handling
* Email are sent to user when a timesheet is rejected by the team leader
* Note on task are shown as info when hoovering over the task line
* Searchbox are available instead of dropdown list (use other core module setup).
* More translation (ES, DE, IT, FR, US , mostly automated)
* Note editing available for each tasks (also in the approval flow)

Change log from 1.5
* Support dolibarr 4.0.1
* Hidden option to join file to timesheets via the setting TIMESHEET_ADD_DOCS

Change log from 1.4.3:
* Timesheet approval by N+1,
* Reminder (email) for to be approved timesheet possible through dolibarr planned tasks
* admin wiew for the Approval (change a approval status outside the normal approval flow)
* Home box with the pending timesheet to be approved
* Blocking some weekdays (e.g week ends)
* Holiday showed in the timesheet
* Holiday time can be included in the timesheet totals
* Typo correction for French.
* Posibility to add a note
* Compatible with dolibarr 3.9.2

Change log from 1.4.1:

* Correction of the Spanish language (thanks to vinclar)
* Possible to deactivate the dolibarr Ajax for the dropdown list for the setup page (in case of issue to add whitelist)
* Keep the whitlistmode after submit / go to date / next / previsous week

Change log from 1.4:
* Bugfix for the tasktime date in the project page
* Link to have the different whitelist behaviour (black list, and none)
* Spanish language (google trad)
* Typo correction for French
* Support the print mode for timesheet & the report
* Show the project open to everyone on the new whitelist page

Change log from 1.3.7:
* layout improvement: timesheet, setup page, reports
* whitelist to show only some project/task
* taslk column customisation
* new task column: company, parent task
* new report option: report all, export friendly layout
* user report available for the N-2, N-3

Change log from 1.3.6:
* compatible avec dolibarr 3.7
* Change log from 1.3.3:
* Works with PHP<=5.3
* Possibility to remove the 0:00
* Color code for already filled tasktime / new tasktime and error
* Bux fixes in the report
* Better date dialog
* N+1 is able to check the user report of his N's

Module Timesheet

2017-08-14T08:32:46Z

Delcroip: /* Change logs */

[[Category:Complementary modules]]
[[Category:timesheet]]
{{TemplateDocDevEn}}
{{TemplateDocUser}}
<keywords content="timesheet, Dolibarr, interface, project, task, report, approval" />

= Informations =
{{TemplateModuleInfo
|modulename=timesheet
|editor=delcroip
|webbuy={{LinkToPluginDownloadDoliStore|keyword=timesheet}}
|status=stable
|prerequisites=projects
|minversion=3.5.0
|maxversion=4.0.4
|note=Latest Module version: 1.5.1
}}

= Manual =
[https://wiki.dolibarr.org/upload/b/bd/Module_timesheet.pdf manual]

= Features =

- Timesheet interface for all the user task per week
- Generate report on user and on project per month
- whitelist to show only some project/task (if no whitelist define all task are showed)
- Approval of the timesheets per the N+1

[[File:timesheet_timeentry.jpg]]

= Change logs =
2.0.1 Change log from 2.0
* Project approval corrected (for non admin no approval was shown)
* PHP warning removed
* Home timesheet box correted (was not showing the # of timesheet to approve)

2.0 Change log from 1.5.1
* Week on two month are spliced to enable monthly approval
* Chained approval for team & project.
* Create invoice with ad-hoc and already defined service based on time saved.
* Report always shows time in day and hours
* Layout change for the setup page
* Layout change for the favorite handling
* Email are sent to user when a timesheet is rejected by the team leader
* Note on task are shown as info when hoovering over the task line
* Searchbox are available instead of dropdown list (use other core module setup).
* More translation (ES, DE, IT, FR, US , mostly automated)
* Note editing available for each tasks (also in the approval flow)

Change log from 1.5
* Support dolibarr 4.0.1
* Hidden option to join file to timesheets via the setting TIMESHEET_ADD_DOCS

Change log from 1.4.3:
* Timesheet approval by N+1,
* Reminder (email) for to be approved timesheet possible through dolibarr planned tasks
* admin wiew for the Approval (change a approval status outside the normal approval flow)
* Home box with the pending timesheet to be approved
* Blocking some weekdays (e.g week ends)
* Holiday showed in the timesheet
* Holiday time can be included in the timesheet totals
* Typo correction for French.
* Posibility to add a note
* Compatible with dolibarr 3.9.2

Change log from 1.4.1:

* Correction of the Spanish language (thanks to vinclar)
* Possible to deactivate the dolibarr Ajax for the dropdown list for the setup page (in case of issue to add whitelist)
* Keep the whitlistmode after submit / go to date / next / previsous week

Change log from 1.4:
* Bugfix for the tasktime date in the project page
* Link to have the different whitelist behaviour (black list, and none)
* Spanish language (google trad)
* Typo correction for French
* Support the print mode for timesheet & the report
* Show the project open to everyone on the new whitelist page

Change log from 1.3.7:
* layout improvement: timesheet, setup page, reports
* whitelist to show only some project/task
* taslk column customisation
* new task column: company, parent task
* new report option: report all, export friendly layout
* user report available for the N-2, N-3

Change log from 1.3.6:
* compatible avec dolibarr 3.7
* Change log from 1.3.3:
* Works with PHP<=5.3
* Possibility to remove the 0:00
* Color code for already filled tasktime / new tasktime and error
* Bux fixes in the report
* Better date dialog
* N+1 is able to check the user report of his N's

Installation - Mise à jour

2017-04-04T12:11:28Z

Delcroip: /* Procédure de mise à jour */

[[Category:Admin]]
{{TemplateDocUtil}}

Les procédures suivantes décrivent comment installer ou mettre à jour Dolibarr.

= Procédure d'installation =
Ce chapitre décrit les différentes méthodes possibles (des plus simples, aux manuels) pour une première installation. Voir plus loin pour la mises à jour.

== Sur votre poste/serveur dédié ==
=== [[File:Logo_windows.png]] Avec DoliWamp (package Windows .exe) ===
- '''Prérequis''': Windows

- '''Niveau''': Débutant

Si vous maitrisez l'installation d'un serveur Web Apache, de PHP et Mysql, le chapitre suivant est plus approprié.
Pour les moins expérimentés qui sont sous Windows, il existe une distribution Dolibarr nommée '''DoliWamp''' qui permet de faire une installation Dolibarr sous Windows avec tous ses prérequis (Apache, Mysql, PHP) sans connaissance informatiques. Voici comment l'installer:

* Récupérez la version de Dolibarr pour Windows.
Pour cela, voir la page de [http://www.nltechno.com/pages/dolibarrwinbin.php téléchargement de DoliWamp chez NLTechno].

* Lancer le .exe téléchargé et suivez les instructions.

=== [[File:Logo_ubuntu.png]] Avec DoliDeb (package Debian / Ubuntu .deb) ===
- '''Prerequis''': Linux Debian, Ubuntu, ...

- '''Niveau''': Débutant

Cette procédure fonctionne uniquement pour les utilisateurs Linux Debian, Ubuntu et dérivés et est recommandée pour ceux qui n'ont pas de connaissances informatiques particulières. Si vous êtes un administrateur expérimenté d'Apache, PHP et Mysql, le chapitre '''Avec Dolibarr (package standard tgz)''' sera peut-être plus approprié. Dans le cas contraire, vous pouvez utilisez DoliDeb. DoliDeb est un package de Dolibarr spécialisé pour la distribution Debian ou Ubuntu. Ce package vous permet d'installer Dolibarr sous Ubuntu ou Debian (ou dérivé) avec tous ces prérequis (Apache, Mysql, PHP) s'ils ne sont pas déjà installés et ce sans connaissances techniques particulières.

* La procédure pour installer DoliDeb est décrite sur la page [[Dolibarr pour Ubuntu ou Debian]].

=== [[File:Logo_rpm.png|40px]] Avec DoliRpm (package Fedora, Redhat, Mandriva, Mageia or OpenSuse .rpm) ===
- '''Prerequis''': Linux Fedora, Redhat, Mandriva, Mageia or OpenSuse (may also work for any rpm linux distribution)

- '''Niveau''': Débutant

Cette procédure fonctionne uniquement pour les utilisateurs Linux d'une distribution gérant les packages rpm et est recommandée pour ceux qui n'ont pas de connaissances informatiques particulières. Si vous êtes un administrateur expérimenté d'Apache, PHP et Mysql, le chapitre suivant '''Avec Dolibarr (package standard tgz)''' sera peut-être plus approprié. Dans le cas contraire, vous pouvez utilisez DoliRpm. DoliRpm est un package de Dolibarr spécialisé pour la distribution Fedora, Redhat, Mandriva, Mageia ou OpenSuse. Ce package vous permet d'installer Dolibarr sous ces OS avec tous ces prérequis (Apache, Mysql, PHP) s'ils ne sont pas déjà installés et ce sans connaissances techniques particulières.

* La procédure pour installer DoliRpm est décrite sur la page [[Dolibarr pour Redhat ou Fedora (package rpm)]] ou [[Dolibarr pour Mandriva ou Mageia (package rpm)]] ou [[Dolibarr pour OpenSuse (package rpm)]].

=== [[File:Gnu.png]] Avec Dolibarr (package standard .tgz ou sources Git) ===
- '''Prérequis''': Apache, PHP et un serveur de base de données (MySQL ou PostgreSQL) sont présents et opérationnels, et le login/mot de passe d'accès (à une nouvelle base ou au serveur) est connu.

- '''Niveau''': Un peu de connaissances informatiques en administration Web.

Cette procédure décrit l'installation manuelle (recommandée) sur un système GNU/Linux (Debian, Mandriva, ...) mais elle est valable avec d'autres systèmes comme Windows moyennant une adaptation des chemins à ceux de votre OS.
Elle est applicable pour toute version de Dolibarr >= 2.0.0

* Vérifiez que vous avez bien Apache, PHP {{PHPMinVersion}} et un serveur de base de données (MySQL {{MySqlMinVersion}} ou PostgreSQL) d'installés (consulter pour cela la liste des packages installés sur votre machine grâce au gestionnaire de mise à jour de package de votre distribution).

* Vérifiez que l'utilisateur root ou admin principal pour le serveur de base de donnée est connu et fonctionne correctement. Si cet utilisateur root ou admin est inconnu car pas encore défini, lisez le chapitre qui suit. Sinon vous pouvez passez au point suivant:

Pour les utilisateurs Linux utilisant MySql ou MariaDB, si vous venez juste d'installer la base de donnée MySQL, le login administrateur est '''root'''. Vous devez exécuter la commande suivante pour initialiser le mot de passe:
<source lang="bash">
mysql
</source>
Une fois dans l'interface Mysql, taper la commande de modification du mote de passe de root:
<source lang="sql">
grant all privileges on *.* to root@'localhost' identified by 'newrootpass' with grant option;
</source>
Puis entrée et pour quitter \q

Pour vérifier que l'accès avec ce couple user/mot de passe fonctionne, lancer la commande
<source lang="bash">
mysql -u root -p
</source>
Et taper votre mot de passe ''newrootpass'' suivi de \q pour quitter la sessions si la connexion a réussie.

Pour les utilisateurs Linux utilisant Postgresql, si vous venez juste d'installer la base de donnée PostgreSQL, vous devez d'abord créer un utilisateur administrateur et son mot de passe. Pour cela, ajouter la ligne suivante dans le fichier '''/etc/postgresql/x.x/main/pg_hba.conf''' (remplacer x.x avec votre version de postgres)
<source lang="ini">
local all dolibarrowner md5
</source>
De plus, mettez en commentaire la ligne
<source lang="ini">
#local all all ident
</source>
qui impose que le compte système utilisé pour accéder à la base (ce sera le compte sous lequel tourne l'application web), ait le même nom que le compte dans la base (ce n'est jamais le cas).

Ensuite, lancer la commande sous un shell root
<source lang="bash">
sudo -s -u postgres
createuser dolibarrowner
psql -d template1 -c "alter user dolibarrowner with password 'dolibarrownerpass'"
exit
sudo /etc/init.d/postgresql restart
</source>
Vous pouvez tester la connexion pour l'utilisateur crée avec la commande
<source lang="bash">
psql -h localhost -d postgres -U dolibarrowner -W
</source>
Et entrez le mot de passe ''dolibarrownerpass'' et \q pour quitter la session si la connexion est ok.

* Placez-vous dans le répertoire dans lequel installer Dolibarr (le répertoire racine défini pour votre serveur web)
# Pour Debian et les familles Ubuntu, il s'agit en général de: /var/www
# Pour Mandriva, RedHat, Fedora: /var/www/html
# Pour Suse: /srv/www/htdocs
<source lang="bash">
$ cd /var/www
</source>

* Récupérez l'application

- Si vous partez du fichier dolibarr.tgz, récupérez le fichier et décompressez l'archive de l'application

<source lang="bash">
$ wget http://www.dolibarr.org/files/dolibarr.tgz
$ tar xvfz dolibarr.tgz
</source>

Renommez le répertoire dolibarr-x.y.z en dolibarr afin d'avoir un nom de répertoire indépendant de la version (où x.y.z correspond à la version source)
<source lang="bash">
$ mv dolibarr-x.y.z dolibarr
</source>

- Si vous partez des sources Git, récupérer les sources par

<source lang="bash">
$ git clone -b develop http://github.com/Dolibarr/dolibarr.git dolibarr
</source>

Il est possible de remplacer HEAD par X.y pour récupérer la dernière version stable de la branche x.y.

* Modifiez les permissions et propriétaires du répertoire 'dolibarr' pour être sur que tous les fichiers soient en lecture pour l'utilisateur sur lequel tourne le serveur (on supposera qu'il s'agit de l'utilisateur 'www-data' pour debian ou ubuntu, 'apache' pour redhat, mandriva, fedora)
<source lang="bash">
$ chmod -R 755 /var/www/dolibarr
$ chown -R www-data.www-data /var/www/dolibarr
or
$ chmod -R 755 /var/www/html/dolibarr
$ chown -R apache.apache /var/www/html/dolibarr
</source>

* En tant que root, créez, dans le répertoire dolibarr/htdocs/conf, un fichier de configuration vide, et attribuez-lui comme propriétaire du fichier, l'utilisateur du serveur web (exemple www-data sur debian, nobody sur une vieille RedHat, apache sur une autre version ...). Ceci est requis car le serveur web a besoin d'écrire dans ce fichier lors de l'installation.
<source lang="bash">
$ cd dolibarr ; touch htdocs/conf/conf.php ; chown www-data htdocs/conf/conf.php
</source>

* Sur Fedora, comme SELinux est activé en général, il est aussi conseillé de lancer les commandes pour rendre le répertoire 'dolibarr' accepté par l'environnement SELinux (an absence de commande, vous devriez recevoir des nombreuses alertes d'anomalies) :
<source lang="bash">
$ semanage fcontext -a -t httpd_sys_rw_content_t '/var/www/html/dolibarr(/.*)?'
$ restorecon -R -v '/var/www/html/dolibarr'
</source>

* Toujours en root, créez le répertoire qui servira aux documents générés ou stockés par Dolibarr (factures pdf, images, ...), et attribuez lui comme propriétaire, l'utilisateur du serveur web (exemple www-data sur Debian, nobody sur une vieille RedHat, Apache sur une Mandriva ou une RedHat récente, ...). Le serveur web doit avoir les droits en écriture dans ce répertoire.
<source lang="bash">
$ mkdir documents ; chown www-data documents
</source>

* Pointez votre navigateur sur la page principale
<source lang="ini">
http://127.0.0.1/dolibarr/htdocs/
</source>

* Suivez les instructions de l'installation

* Pour des raisons de sécurité nous vous conseillons, une fois l'installation terminée, de créer un fichier install.lock dans le répertoire d'installation, que seul root doit avoir le droit d'effacer. Ceci va vérouiller la procédure d'installation qui ne pourra plus être appelée par erreur (Il faudra le supprimer pour les mises à jour).
<source lang="bash">
$ touch /var/www/dolibarr/install.lock; chmod go-w /var/www/dolibarr;
</source>

== Sur un hébergement mutualisé (à accès restreint) ==
Il n'est pas possible de présenter une solution générique à ce cas car la procédures dépend de l'hébergeur.
La plupart du temps, la procédure générique suivante fonctionnera:

Voici toutefois quelques documents/procédures spécifiques à certains hébergeurs:
* Hébergement FREE mutualisé: [[File:Installation Dolibarr Free-20100526.odt]]
* Hébergement OVH oneclick: OVH propose une version de Dolibarr parfois plus ancienne que la version stable courante mais installable depuis son interface d'administration dans sa solution "OneClick".

Procédure générique:

- '''Prerequis''':
Un serveur web Apache, PHP et une base de donnée (MySQL ou PostgreSQL) tourne correctement et le compte login/mot de passe (de la nouvelle base de donnée ou d'administration du serveur) est connu (sinon les demander à l'hébergeur).

- '''Niveau''': Utilisateurs avec quelques notions d'administration Web and base de donnée. Maitrise d'un outil de transfert de fichier (FTP, SFTP, ...) pour uploader les fichiers sur le serveur.

* Vérifiez que vous avez un serveur Web Apache, PHP et une base de donnée (MySQL ou PostGreSQL) qui fonctionne correctement.
[[File:warning.png]] Attention, la page de code du serveur PHP et de la base de donnée doivent être identique.

* Vérifiez que vous avez un compte root ou administrateur avec login/mot de passe connu et que ces comptes fonctionnent. Si inconnu, demandez les à votre hébergeur.

* Récupérer l'archive de la dernière version stable de Dolibarr et décompressez la localement..

* Uploadez tout le contenu du répertoire dans le répertoire racine de votre site web, par exemple par FTP en mode binaire.

* Créez un répertoire nommé "documents", dans cette racine, qui servira à sauver tous les documents générés et stockés par Dolibarr (factures PDF, images uploadées, ...). Le serveur web doit avoir les permissions d'écrire dedans. Vous pouvez attribuer ces permission avec un client FTP.

* Maintenant appeler la page principale index.php de dolibarr avec votre navigateur.

* Suivez les instructions pas à pas du processus d'installation.

* Pour des raisons de sécurité, il est recommandé, une fois l'installation terminée, de créer un fichier install.lock dans le répertoire de Dolibarr. Ceci vérrouillera l'appel au processus d'installation (il vous faudra supprimer ce fichier pour permettre les mise à jour). Si ceci n'est pas fait, Dolibarr vous affichera un warning lorsque vous êtes loggués comme administrateur.

== Sur un hébergeur SaaS ou Cloud ==
Dolibarr est aussi disponible en version "pré-installée" chez de nombreux hébergeurs payants, fournissant des instances hébergées "prêtes à l'emploi".

Voir la page [[Solutions de Cloud]].

Dolibarr peut aussi être installé manuellement sur toute plateforme Cloud (gratuite ou payante) qui supporte le PHP et Mysql.

Voir la page [[Solutions de Cloud]].

= Procédure de mise à jour =
Ce chapitre décrit le processus pour mettre à niveau une installation existante de Dolibarr d'une ancienne version vers une autre. Le processus est le même quel que soit la version depuis laquelle vous venez et la version vers laquelle vous allez, mais sera différent selon la distribution ou système d'exploitation utilisé pour votre première installation. Il est recommandé d'utiliser le même type de distribution pour la mise à jour que celle utilisée pour la première installation.

== Sauvegarde ==

Avant de faire une mise à jour, il est recommendé de faire un sauvegarde de la base de donnée mais aussi des documents, de cette façon même en cas de catastrophe vous ne perdrez pas vos preciseuses données
https://wiki.dolibarr.org/index.php/Sauvegardes

== [[File:Logo_windows.png]] Avec DoliWamp (package Windows .exe) ==

Si vous aviez installé la version de Dolibarr spécifique nommé DoliWamp (qui embarque le serveur Web, PHP et Mysql), la procédure à suivre est celle-ci (Dans tout autre cas, utilisez une des procédures des chapitres suivant):

* Télécharger la nouvelle version de DoliWamp.

* Lancer le .exe et laissez vous guider dans toutes les étapes de migration en cliquant suivant,suivant,... à chaque fois sans rien changer aux valeurs proposées par défaut.

* Au premier accès de Dolibarr, l'application détectera que vous avez une base en version ancienne. Choisissez le menu proposé pour migrer à la version supérieure. Si vous avez fait un saut de plusieurs version, garder le choix proposer de migrer d'une seule version, à la fin le menu vous sera reproposé pour migrer à la suivante et ainsi de suite jusqu'à atteindre la version qui a été installé (par si vous avez installer Dolibarr 3.5 par dessus votre version courante qui était Dolibarr 3.2, choisissez le menu de migration pour passer de 3.2 à 3.3, puis 3.3 à 3.4 puis 3.4 à 3.5).

== [[File:Logo_ubuntu.png]] Avec DoliDeb (package Debian / Ubuntu .deb) ==
Si vous aviez installé Dolibarr via un packagage Debian-Ubuntu, sa mise a jour se fait simplement de la même manière qu'une première installation. Il suffit d'installer le nouveau package .deb.
Par exemple en suivant la procédure [[Dolibarr pour Ubuntu ou Debian]].

* Au premier accès de Dolibarr, l'application détectera que vous avez une base en version ancienne. Choisissez le menu proposé pour migrer à la version supérieure. Si vous avez fait un saut de plusieurs version, garder le choix proposer de migrer d'une seule version, à la fin le menu vous sera reproposé pour migrer à la suivante et ainsi de suite jusqu'à atteindre la version qui a été installé (par si vous avez installer Dolibarr 3.5 par dessus votre version courante qui était Dolibarr 3.2, choisissez le menu de migration pour passer de 3.2 à 3.3, puis 3.3 à 3.4 puis 3.4 à 3.5).

== [[File:Logo_rpm.png|40px]] Avec DoliRpm (package Fedora, Redhat, Mandriva, Mageia ou OpenSuse .rpm) ==
Si vous aviez installé Dolibarr via un packagage rpm, sa mise a jour se fait simplement de la même manière qu'une première installation. Il suffit d'installer le nouveau package .rpm.

* Au premier accès de Dolibarr, l'application détectera que vous avez une base en version ancienne. Choisissez le menu proposé pour migrer à la version supérieure. Si vous avez fait un saut de plusieurs version, garder le choix proposer de migrer d'une seule version, à la fin le menu vous sera reproposé pour migrer à la suivante et ainsi de suite jusqu'à atteindre la version qui a été installé (par si vous avez installer Dolibarr 3.5 par dessus votre version courante qui était Dolibarr 3.2, choisissez le menu de migration pour passer de 3.2 à 3.3, puis 3.3 à 3.4 puis 3.4 à 3.5).

== [[File:Gnu.png]] Avec Dolibarr (package standard .tgz) ==

Cette procédure décrit la mise à jour de Dolibarr depuis une ancienne version vers une plus récente par la méthode manuelle, avec la distribution standard.

* Placez-vous dans le répertoire dans lequel a été installé Dolibarr (le répertoire racine de votre serveur web, par exemple /var/www sous Debian)
<source lang="bash">
$ cd /var/www
</source>

* Récupérez l'archive de la nouvelle version
<source lang="bash">
$ wget http://www.dolibarr.org/files/dolibarr.tgz
</source>

* Décompressez l'archive
<source lang="bash">
$ tar xvfz dolibarr.tgz
</source>

* Recopiez les nouveaux fichiers (qui ont été décompressés dans le répertoire dolibarr-x.y.z) vers le répertoire où vous avez votre ancienne version de Dolibarr. Ceci a pour effet de remplacer les anciens fichiers par les nouveaux tout en conservant les fichiers qui vous sont spécifiques (comme le fichier conf.php ou encore vos modules complémentaires non officiels installés).
* Si vous deplacez ou renommez également le dossier de votre ancienne version de Dolibarr, pensez à modifier les chemins dans le fichier /conf/conf.php (sinon vous risquez un fatal error: Cannot redeclare versiontostring)
<source lang="bash">
$ cp -r dolibarr-x.y.z/* dolibarr
</source>

* Vous pouvez alors supprimer le répertoire des fichiers sources
<source lang="bash">
$ rm -fr dolibarr-x.y.z
</source>

* Lancer Dolibarr dans votre navigateur habituel. Ceci fera apparaître l'assistant de migration: L'application détectera que vous avez une base en version ancienne. Choisissez le menu proposé pour migrer à la version supérieure. Si vous avez fait un saut de plusieurs version, garder le choix proposer de migrer d'une seule version, à la fin le menu vous sera reproposé pour migrer à la suivante et ainsi de suite jusqu'à atteindre la version qui a été installé (par si vous avez installer Dolibarr 3.5 par dessus votre version courante qui était Dolibarr 3.2, choisissez le menu de migration pour passer de 3.2 à 3.3, puis 3.3 à 3.4 puis 3.4 à 3.5).

ou

Lancer les 2 étapes de migration en ligne de commande:
<source lang="bash">
$ cd htdocs/install
$ php upgrade.php oldx.oldy.oldz x.y.z > output.html
$ php upgrade2.php oldx.oldy.oldz x.y.z > output2.html
$ php step5.php oldx.oldy.oldz x.y.z > output3.html
</source>
Note: z doit être "0" car seul les versions majeures ont un script de migration à exécuter.

Le code retour sera 0 en cas de succès, 1 en cas d'erreur (voir alors le fichier sortie output.html ou output2.html)

Note: Si vous avez un message signalant que le processus de mise à jour est vérrouillé par un fichier install.lock, supprimer ce fichier (il est stocké dans le répertoire racine ou "documents" de Dolibarr) puis rafraichissez la page.

* Pour des raisons de sécurité nous vous conseillons, une fois la mise à jour terminée, de verrouiller le répertoire d'installation en créant un fichier install.lock dans le répertoire de donnée de Dolibarr. Dans le cas contraire, Dolibarr vous avertira d'un message dans l'interface une fois loggé
<source lang="bash">
$ echo > documents/install.lock
$ chmod 444 documents/install.lock
</source>

= Sauvegarde =

Avant de faire une mise à jour, il est recommendé de faire un sauvegarde de la base de donnée mais aussi des documents, de cette façon même en case de catastrophe vous ne perdrez pas vos preciseuses données
https://wiki.dolibarr.org/index.php/Sauvegardes

== [[File:Logo_windows.png]] Avec DoliWamp (package Windows .exe) ==

Si vous aviez installé la version de Dolibarr spécifique nommé DoliWamp (qui embarque le serveur Web, PHP et Mysql), la procédure à suivre est celle-ci (Dans tout autre cas, utilisez une des procédures des chapitres suivant):

* Télécharger la nouvelle version de DoliWamp.

* Lancer le .exe et laissez vous guider dans toutes les étapes de migration en cliquant suivant,suivant,... à chaque fois sans rien changer aux valeurs proposées par défaut.

* Au premier accès de Dolibarr, l'application détectera que vous avez une base en version ancienne. Choisissez le menu proposé pour migrer à la version supérieure. Si vous avez fait un saut de plusieurs version, garder le choix proposer de migrer d'une seule version, à la fin le menu vous sera reproposé pour migrer à la suivante et ainsi de suite jusqu'à atteindre la version qui a été installé (par si vous avez installer Dolibarr 3.5 par dessus votre version courante qui était Dolibarr 3.2, choisissez le menu de migration pour passer de 3.2 à 3.3, puis 3.3 à 3.4 puis 3.4 à 3.5).

== [[File:Logo_ubuntu.png]] Avec DoliDeb (package Debian / Ubuntu .deb) ==
Si vous aviez installé Dolibarr via un packagage Debian-Ubuntu, sa mise a jour se fait simplement de la même manière qu'une première installation. Il suffit d'installer le nouveau package .deb.
Par exemple en suivant la procédure [[Dolibarr pour Ubuntu ou Debian]].

* Au premier accès de Dolibarr, l'application détectera que vous avez une base en version ancienne. Choisissez le menu proposé pour migrer à la version supérieure. Si vous avez fait un saut de plusieurs version, garder le choix proposer de migrer d'une seule version, à la fin le menu vous sera reproposé pour migrer à la suivante et ainsi de suite jusqu'à atteindre la version qui a été installé (par si vous avez installer Dolibarr 3.5 par dessus votre version courante qui était Dolibarr 3.2, choisissez le menu de migration pour passer de 3.2 à 3.3, puis 3.3 à 3.4 puis 3.4 à 3.5).

== [[File:Logo_rpm.png|40px]] Avec DoliRpm (package Fedora, Redhat, Mandriva, Mageia ou OpenSuse .rpm) ==
Si vous aviez installé Dolibarr via un packagage rpm, sa mise a jour se fait simplement de la même manière qu'une première installation. Il suffit d'installer le nouveau package .rpm.

* Au premier accès de Dolibarr, l'application détectera que vous avez une base en version ancienne. Choisissez le menu proposé pour migrer à la version supérieure. Si vous avez fait un saut de plusieurs version, garder le choix proposer de migrer d'une seule version, à la fin le menu vous sera reproposé pour migrer à la suivante et ainsi de suite jusqu'à atteindre la version qui a été installé (par si vous avez installer Dolibarr 3.5 par dessus votre version courante qui était Dolibarr 3.2, choisissez le menu de migration pour passer de 3.2 à 3.3, puis 3.3 à 3.4 puis 3.4 à 3.5).

== [[File:Gnu.png]] Avec Dolibarr (package standard .tgz) ==

Cette procédure décrit la mise à jour de Dolibarr depuis une ancienne version vers une plus récente par la méthode manuelle, avec la distribution standard.

* Placez-vous dans le répertoire dans lequel a été installé Dolibarr (le répertoire racine de votre serveur web, par exemple /var/www sous Debian)
<source lang="bash">
$ cd /var/www
</source>

* Récupérez l'archive de la nouvelle version
<source lang="bash">
$ wget http://www.dolibarr.org/files/dolibarr.tgz
</source>

* Décompressez l'archive
<source lang="bash">
$ tar xvfz dolibarr.tgz
</source>

* Recopiez les nouveaux fichiers (qui ont été décompressés dans le répertoire dolibarr-x.y.z) vers le répertoire où vous avez votre ancienne version de Dolibarr. Ceci a pour effet de remplacer les anciens fichiers par les nouveaux tout en conservant les fichiers qui vous sont spécifiques (comme le fichier conf.php ou encore vos modules complémentaires non officiels installés).
* Si vous deplacez ou renommez également le dossier de votre ancienne version de Dolibarr, pensez à modifier les chemins dans le fichier /conf/conf.php (sinon vous risquez un fatal error: Cannot redeclare versiontostring)
<source lang="bash">
$ cp -r dolibarr-x.y.z/* dolibarr
</source>

* Vous pouvez alors supprimer le répertoire des fichiers sources
<source lang="bash">
$ rm -fr dolibarr-x.y.z
</source>

* Lancer Dolibarr dans votre navigateur habituel. Ceci fera apparaître l'assistant de migration: L'application détectera que vous avez une base en version ancienne. Choisissez le menu proposé pour migrer à la version supérieure. Si vous avez fait un saut de plusieurs version, garder le choix proposer de migrer d'une seule version, à la fin le menu vous sera reproposé pour migrer à la suivante et ainsi de suite jusqu'à atteindre la version qui a été installé (par si vous avez installer Dolibarr 3.5 par dessus votre version courante qui était Dolibarr 3.2, choisissez le menu de migration pour passer de 3.2 à 3.3, puis 3.3 à 3.4 puis 3.4 à 3.5).

ou

Lancer les 2 étapes de migration en ligne de commande:
<source lang="bash">
$ cd htdocs/install
$ php upgrade.php oldx.oldy.oldz x.y.z > output.html
$ php upgrade2.php oldx.oldy.oldz x.y.z > output2.html
$ php step5.php oldx.oldy.oldz x.y.z > output3.html
</source>
Note: z doit être "0" car seul les versions majeures ont un script de migration à exécuter.

Le code retour sera 0 en cas de succès, 1 en cas d'erreur (voir alors le fichier sortie output.html ou output2.html)

Note: Si vous avez un message signalant que le processus de mise à jour est vérrouillé par un fichier install.lock, supprimer ce fichier (il est stocké dans le répertoire racine ou "documents" de Dolibarr) puis rafraichissez la page.

* Pour des raisons de sécurité nous vous conseillons, une fois la mise à jour terminée, de verrouiller le répertoire d'installation en créant un fichier install.lock dans le répertoire de donnée de Dolibarr. Dans le cas contraire, Dolibarr vous avertira d'un message dans l'interface une fois loggé
<source lang="bash">
$ echo > documents/install.lock
$ chmod 444 documents/install.lock
</source>

= Configurer une connexion LDAP =
Si vous désirez utiliser LDAP: Voir [[Installer et configurer OpenLDAP]].

= Importer des données externes =
Pour cette opération, consulter la page [[Imports_de_masse]].

= Configuration - Paramétrage =
Voir la page [[Premiers_paramétrages|Configuration/Paramétrage]].

Installation - Mise à jour

2017-04-04T12:09:25Z

Delcroip: /* Procédure de mise à jour */

[[Category:Admin]]
{{TemplateDocUtil}}

Les procédures suivantes décrivent comment installer ou mettre à jour Dolibarr.

= Procédure d'installation =
Ce chapitre décrit les différentes méthodes possibles (des plus simples, aux manuels) pour une première installation. Voir plus loin pour la mises à jour.

== Sur votre poste/serveur dédié ==
=== [[File:Logo_windows.png]] Avec DoliWamp (package Windows .exe) ===
- '''Prérequis''': Windows

- '''Niveau''': Débutant

Si vous maitrisez l'installation d'un serveur Web Apache, de PHP et Mysql, le chapitre suivant est plus approprié.
Pour les moins expérimentés qui sont sous Windows, il existe une distribution Dolibarr nommée '''DoliWamp''' qui permet de faire une installation Dolibarr sous Windows avec tous ses prérequis (Apache, Mysql, PHP) sans connaissance informatiques. Voici comment l'installer:

* Récupérez la version de Dolibarr pour Windows.
Pour cela, voir la page de [http://www.nltechno.com/pages/dolibarrwinbin.php téléchargement de DoliWamp chez NLTechno].

* Lancer le .exe téléchargé et suivez les instructions.

=== [[File:Logo_ubuntu.png]] Avec DoliDeb (package Debian / Ubuntu .deb) ===
- '''Prerequis''': Linux Debian, Ubuntu, ...

- '''Niveau''': Débutant

Cette procédure fonctionne uniquement pour les utilisateurs Linux Debian, Ubuntu et dérivés et est recommandée pour ceux qui n'ont pas de connaissances informatiques particulières. Si vous êtes un administrateur expérimenté d'Apache, PHP et Mysql, le chapitre '''Avec Dolibarr (package standard tgz)''' sera peut-être plus approprié. Dans le cas contraire, vous pouvez utilisez DoliDeb. DoliDeb est un package de Dolibarr spécialisé pour la distribution Debian ou Ubuntu. Ce package vous permet d'installer Dolibarr sous Ubuntu ou Debian (ou dérivé) avec tous ces prérequis (Apache, Mysql, PHP) s'ils ne sont pas déjà installés et ce sans connaissances techniques particulières.

* La procédure pour installer DoliDeb est décrite sur la page [[Dolibarr pour Ubuntu ou Debian]].

=== [[File:Logo_rpm.png|40px]] Avec DoliRpm (package Fedora, Redhat, Mandriva, Mageia or OpenSuse .rpm) ===
- '''Prerequis''': Linux Fedora, Redhat, Mandriva, Mageia or OpenSuse (may also work for any rpm linux distribution)

- '''Niveau''': Débutant

Cette procédure fonctionne uniquement pour les utilisateurs Linux d'une distribution gérant les packages rpm et est recommandée pour ceux qui n'ont pas de connaissances informatiques particulières. Si vous êtes un administrateur expérimenté d'Apache, PHP et Mysql, le chapitre suivant '''Avec Dolibarr (package standard tgz)''' sera peut-être plus approprié. Dans le cas contraire, vous pouvez utilisez DoliRpm. DoliRpm est un package de Dolibarr spécialisé pour la distribution Fedora, Redhat, Mandriva, Mageia ou OpenSuse. Ce package vous permet d'installer Dolibarr sous ces OS avec tous ces prérequis (Apache, Mysql, PHP) s'ils ne sont pas déjà installés et ce sans connaissances techniques particulières.

* La procédure pour installer DoliRpm est décrite sur la page [[Dolibarr pour Redhat ou Fedora (package rpm)]] ou [[Dolibarr pour Mandriva ou Mageia (package rpm)]] ou [[Dolibarr pour OpenSuse (package rpm)]].

=== [[File:Gnu.png]] Avec Dolibarr (package standard .tgz ou sources Git) ===
- '''Prérequis''': Apache, PHP et un serveur de base de données (MySQL ou PostgreSQL) sont présents et opérationnels, et le login/mot de passe d'accès (à une nouvelle base ou au serveur) est connu.

- '''Niveau''': Un peu de connaissances informatiques en administration Web.

Cette procédure décrit l'installation manuelle (recommandée) sur un système GNU/Linux (Debian, Mandriva, ...) mais elle est valable avec d'autres systèmes comme Windows moyennant une adaptation des chemins à ceux de votre OS.
Elle est applicable pour toute version de Dolibarr >= 2.0.0

* Vérifiez que vous avez bien Apache, PHP {{PHPMinVersion}} et un serveur de base de données (MySQL {{MySqlMinVersion}} ou PostgreSQL) d'installés (consulter pour cela la liste des packages installés sur votre machine grâce au gestionnaire de mise à jour de package de votre distribution).

* Vérifiez que l'utilisateur root ou admin principal pour le serveur de base de donnée est connu et fonctionne correctement. Si cet utilisateur root ou admin est inconnu car pas encore défini, lisez le chapitre qui suit. Sinon vous pouvez passez au point suivant:

Pour les utilisateurs Linux utilisant MySql ou MariaDB, si vous venez juste d'installer la base de donnée MySQL, le login administrateur est '''root'''. Vous devez exécuter la commande suivante pour initialiser le mot de passe:
<source lang="bash">
mysql
</source>
Une fois dans l'interface Mysql, taper la commande de modification du mote de passe de root:
<source lang="sql">
grant all privileges on *.* to root@'localhost' identified by 'newrootpass' with grant option;
</source>
Puis entrée et pour quitter \q

Pour vérifier que l'accès avec ce couple user/mot de passe fonctionne, lancer la commande
<source lang="bash">
mysql -u root -p
</source>
Et taper votre mot de passe ''newrootpass'' suivi de \q pour quitter la sessions si la connexion a réussie.

Pour les utilisateurs Linux utilisant Postgresql, si vous venez juste d'installer la base de donnée PostgreSQL, vous devez d'abord créer un utilisateur administrateur et son mot de passe. Pour cela, ajouter la ligne suivante dans le fichier '''/etc/postgresql/x.x/main/pg_hba.conf''' (remplacer x.x avec votre version de postgres)
<source lang="ini">
local all dolibarrowner md5
</source>
De plus, mettez en commentaire la ligne
<source lang="ini">
#local all all ident
</source>
qui impose que le compte système utilisé pour accéder à la base (ce sera le compte sous lequel tourne l'application web), ait le même nom que le compte dans la base (ce n'est jamais le cas).

Ensuite, lancer la commande sous un shell root
<source lang="bash">
sudo -s -u postgres
createuser dolibarrowner
psql -d template1 -c "alter user dolibarrowner with password 'dolibarrownerpass'"
exit
sudo /etc/init.d/postgresql restart
</source>
Vous pouvez tester la connexion pour l'utilisateur crée avec la commande
<source lang="bash">
psql -h localhost -d postgres -U dolibarrowner -W
</source>
Et entrez le mot de passe ''dolibarrownerpass'' et \q pour quitter la session si la connexion est ok.

* Placez-vous dans le répertoire dans lequel installer Dolibarr (le répertoire racine défini pour votre serveur web)
# Pour Debian et les familles Ubuntu, il s'agit en général de: /var/www
# Pour Mandriva, RedHat, Fedora: /var/www/html
# Pour Suse: /srv/www/htdocs
<source lang="bash">
$ cd /var/www
</source>

* Récupérez l'application

- Si vous partez du fichier dolibarr.tgz, récupérez le fichier et décompressez l'archive de l'application

<source lang="bash">
$ wget http://www.dolibarr.org/files/dolibarr.tgz
$ tar xvfz dolibarr.tgz
</source>

Renommez le répertoire dolibarr-x.y.z en dolibarr afin d'avoir un nom de répertoire indépendant de la version (où x.y.z correspond à la version source)
<source lang="bash">
$ mv dolibarr-x.y.z dolibarr
</source>

- Si vous partez des sources Git, récupérer les sources par

<source lang="bash">
$ git clone -b develop http://github.com/Dolibarr/dolibarr.git dolibarr
</source>

Il est possible de remplacer HEAD par X.y pour récupérer la dernière version stable de la branche x.y.

* Modifiez les permissions et propriétaires du répertoire 'dolibarr' pour être sur que tous les fichiers soient en lecture pour l'utilisateur sur lequel tourne le serveur (on supposera qu'il s'agit de l'utilisateur 'www-data' pour debian ou ubuntu, 'apache' pour redhat, mandriva, fedora)
<source lang="bash">
$ chmod -R 755 /var/www/dolibarr
$ chown -R www-data.www-data /var/www/dolibarr
or
$ chmod -R 755 /var/www/html/dolibarr
$ chown -R apache.apache /var/www/html/dolibarr
</source>

* En tant que root, créez, dans le répertoire dolibarr/htdocs/conf, un fichier de configuration vide, et attribuez-lui comme propriétaire du fichier, l'utilisateur du serveur web (exemple www-data sur debian, nobody sur une vieille RedHat, apache sur une autre version ...). Ceci est requis car le serveur web a besoin d'écrire dans ce fichier lors de l'installation.
<source lang="bash">
$ cd dolibarr ; touch htdocs/conf/conf.php ; chown www-data htdocs/conf/conf.php
</source>

* Sur Fedora, comme SELinux est activé en général, il est aussi conseillé de lancer les commandes pour rendre le répertoire 'dolibarr' accepté par l'environnement SELinux (an absence de commande, vous devriez recevoir des nombreuses alertes d'anomalies) :
<source lang="bash">
$ semanage fcontext -a -t httpd_sys_rw_content_t '/var/www/html/dolibarr(/.*)?'
$ restorecon -R -v '/var/www/html/dolibarr'
</source>

* Toujours en root, créez le répertoire qui servira aux documents générés ou stockés par Dolibarr (factures pdf, images, ...), et attribuez lui comme propriétaire, l'utilisateur du serveur web (exemple www-data sur Debian, nobody sur une vieille RedHat, Apache sur une Mandriva ou une RedHat récente, ...). Le serveur web doit avoir les droits en écriture dans ce répertoire.
<source lang="bash">
$ mkdir documents ; chown www-data documents
</source>

* Pointez votre navigateur sur la page principale
<source lang="ini">
http://127.0.0.1/dolibarr/htdocs/
</source>

* Suivez les instructions de l'installation

* Pour des raisons de sécurité nous vous conseillons, une fois l'installation terminée, de créer un fichier install.lock dans le répertoire d'installation, que seul root doit avoir le droit d'effacer. Ceci va vérouiller la procédure d'installation qui ne pourra plus être appelée par erreur (Il faudra le supprimer pour les mises à jour).
<source lang="bash">
$ touch /var/www/dolibarr/install.lock; chmod go-w /var/www/dolibarr;
</source>

== Sur un hébergement mutualisé (à accès restreint) ==
Il n'est pas possible de présenter une solution générique à ce cas car la procédures dépend de l'hébergeur.
La plupart du temps, la procédure générique suivante fonctionnera:

Voici toutefois quelques documents/procédures spécifiques à certains hébergeurs:
* Hébergement FREE mutualisé: [[File:Installation Dolibarr Free-20100526.odt]]
* Hébergement OVH oneclick: OVH propose une version de Dolibarr parfois plus ancienne que la version stable courante mais installable depuis son interface d'administration dans sa solution "OneClick".

Procédure générique:

- '''Prerequis''':
Un serveur web Apache, PHP et une base de donnée (MySQL ou PostgreSQL) tourne correctement et le compte login/mot de passe (de la nouvelle base de donnée ou d'administration du serveur) est connu (sinon les demander à l'hébergeur).

- '''Niveau''': Utilisateurs avec quelques notions d'administration Web and base de donnée. Maitrise d'un outil de transfert de fichier (FTP, SFTP, ...) pour uploader les fichiers sur le serveur.

* Vérifiez que vous avez un serveur Web Apache, PHP et une base de donnée (MySQL ou PostGreSQL) qui fonctionne correctement.
[[File:warning.png]] Attention, la page de code du serveur PHP et de la base de donnée doivent être identique.

* Vérifiez que vous avez un compte root ou administrateur avec login/mot de passe connu et que ces comptes fonctionnent. Si inconnu, demandez les à votre hébergeur.

* Récupérer l'archive de la dernière version stable de Dolibarr et décompressez la localement..

* Uploadez tout le contenu du répertoire dans le répertoire racine de votre site web, par exemple par FTP en mode binaire.

* Créez un répertoire nommé "documents", dans cette racine, qui servira à sauver tous les documents générés et stockés par Dolibarr (factures PDF, images uploadées, ...). Le serveur web doit avoir les permissions d'écrire dedans. Vous pouvez attribuer ces permission avec un client FTP.

* Maintenant appeler la page principale index.php de dolibarr avec votre navigateur.

* Suivez les instructions pas à pas du processus d'installation.

* Pour des raisons de sécurité, il est recommandé, une fois l'installation terminée, de créer un fichier install.lock dans le répertoire de Dolibarr. Ceci vérrouillera l'appel au processus d'installation (il vous faudra supprimer ce fichier pour permettre les mise à jour). Si ceci n'est pas fait, Dolibarr vous affichera un warning lorsque vous êtes loggués comme administrateur.

== Sur un hébergeur SaaS ou Cloud ==
Dolibarr est aussi disponible en version "pré-installée" chez de nombreux hébergeurs payants, fournissant des instances hébergées "prêtes à l'emploi".

Voir la page [[Solutions de Cloud]].

Dolibarr peut aussi être installé manuellement sur toute plateforme Cloud (gratuite ou payante) qui supporte le PHP et Mysql.

Voir la page [[Solutions de Cloud]].

= Procédure de mise à jour =
Ce chapitre décrit le processus pour mettre à niveau une installation existante de Dolibarr d'une ancienne version vers une autre. Le processus est le même quel que soit la version depuis laquelle vous venez et la version vers laquelle vous allez, mais sera différent selon la distribution ou système d'exploitation utilisé pour votre première installation. Il est recommandé d'utiliser le même type de distribution pour la mise à jour que celle utilisée pour la première installation.

= Sauvegarde =

Avant de faire une mise à jour, il est recommendé de faire un sauvegarde de la base de donnée mais aussi des documents, de cette façon même en case de catastrophe vous ne perdrez pas vos preciseuses données
https://wiki.dolibarr.org/index.php/Sauvegardes

== [[File:Logo_windows.png]] Avec DoliWamp (package Windows .exe) ==

Si vous aviez installé la version de Dolibarr spécifique nommé DoliWamp (qui embarque le serveur Web, PHP et Mysql), la procédure à suivre est celle-ci (Dans tout autre cas, utilisez une des procédures des chapitres suivant):

* Télécharger la nouvelle version de DoliWamp.

* Lancer le .exe et laissez vous guider dans toutes les étapes de migration en cliquant suivant,suivant,... à chaque fois sans rien changer aux valeurs proposées par défaut.

* Au premier accès de Dolibarr, l'application détectera que vous avez une base en version ancienne. Choisissez le menu proposé pour migrer à la version supérieure. Si vous avez fait un saut de plusieurs version, garder le choix proposer de migrer d'une seule version, à la fin le menu vous sera reproposé pour migrer à la suivante et ainsi de suite jusqu'à atteindre la version qui a été installé (par si vous avez installer Dolibarr 3.5 par dessus votre version courante qui était Dolibarr 3.2, choisissez le menu de migration pour passer de 3.2 à 3.3, puis 3.3 à 3.4 puis 3.4 à 3.5).

== [[File:Logo_ubuntu.png]] Avec DoliDeb (package Debian / Ubuntu .deb) ==
Si vous aviez installé Dolibarr via un packagage Debian-Ubuntu, sa mise a jour se fait simplement de la même manière qu'une première installation. Il suffit d'installer le nouveau package .deb.
Par exemple en suivant la procédure [[Dolibarr pour Ubuntu ou Debian]].

* Au premier accès de Dolibarr, l'application détectera que vous avez une base en version ancienne. Choisissez le menu proposé pour migrer à la version supérieure. Si vous avez fait un saut de plusieurs version, garder le choix proposer de migrer d'une seule version, à la fin le menu vous sera reproposé pour migrer à la suivante et ainsi de suite jusqu'à atteindre la version qui a été installé (par si vous avez installer Dolibarr 3.5 par dessus votre version courante qui était Dolibarr 3.2, choisissez le menu de migration pour passer de 3.2 à 3.3, puis 3.3 à 3.4 puis 3.4 à 3.5).

== [[File:Logo_rpm.png|40px]] Avec DoliRpm (package Fedora, Redhat, Mandriva, Mageia ou OpenSuse .rpm) ==
Si vous aviez installé Dolibarr via un packagage rpm, sa mise a jour se fait simplement de la même manière qu'une première installation. Il suffit d'installer le nouveau package .rpm.

* Au premier accès de Dolibarr, l'application détectera que vous avez une base en version ancienne. Choisissez le menu proposé pour migrer à la version supérieure. Si vous avez fait un saut de plusieurs version, garder le choix proposer de migrer d'une seule version, à la fin le menu vous sera reproposé pour migrer à la suivante et ainsi de suite jusqu'à atteindre la version qui a été installé (par si vous avez installer Dolibarr 3.5 par dessus votre version courante qui était Dolibarr 3.2, choisissez le menu de migration pour passer de 3.2 à 3.3, puis 3.3 à 3.4 puis 3.4 à 3.5).

== [[File:Gnu.png]] Avec Dolibarr (package standard .tgz) ==

Cette procédure décrit la mise à jour de Dolibarr depuis une ancienne version vers une plus récente par la méthode manuelle, avec la distribution standard.

* Placez-vous dans le répertoire dans lequel a été installé Dolibarr (le répertoire racine de votre serveur web, par exemple /var/www sous Debian)
<source lang="bash">
$ cd /var/www
</source>

* Récupérez l'archive de la nouvelle version
<source lang="bash">
$ wget http://www.dolibarr.org/files/dolibarr.tgz
</source>

* Décompressez l'archive
<source lang="bash">
$ tar xvfz dolibarr.tgz
</source>

* Recopiez les nouveaux fichiers (qui ont été décompressés dans le répertoire dolibarr-x.y.z) vers le répertoire où vous avez votre ancienne version de Dolibarr. Ceci a pour effet de remplacer les anciens fichiers par les nouveaux tout en conservant les fichiers qui vous sont spécifiques (comme le fichier conf.php ou encore vos modules complémentaires non officiels installés).
* Si vous deplacez ou renommez également le dossier de votre ancienne version de Dolibarr, pensez à modifier les chemins dans le fichier /conf/conf.php (sinon vous risquez un fatal error: Cannot redeclare versiontostring)
<source lang="bash">
$ cp -r dolibarr-x.y.z/* dolibarr
</source>

* Vous pouvez alors supprimer le répertoire des fichiers sources
<source lang="bash">
$ rm -fr dolibarr-x.y.z
</source>

* Lancer Dolibarr dans votre navigateur habituel. Ceci fera apparaître l'assistant de migration: L'application détectera que vous avez une base en version ancienne. Choisissez le menu proposé pour migrer à la version supérieure. Si vous avez fait un saut de plusieurs version, garder le choix proposer de migrer d'une seule version, à la fin le menu vous sera reproposé pour migrer à la suivante et ainsi de suite jusqu'à atteindre la version qui a été installé (par si vous avez installer Dolibarr 3.5 par dessus votre version courante qui était Dolibarr 3.2, choisissez le menu de migration pour passer de 3.2 à 3.3, puis 3.3 à 3.4 puis 3.4 à 3.5).

ou

Lancer les 2 étapes de migration en ligne de commande:
<source lang="bash">
$ cd htdocs/install
$ php upgrade.php oldx.oldy.oldz x.y.z > output.html
$ php upgrade2.php oldx.oldy.oldz x.y.z > output2.html
$ php step5.php oldx.oldy.oldz x.y.z > output3.html
</source>
Note: z doit être "0" car seul les versions majeures ont un script de migration à exécuter.

Le code retour sera 0 en cas de succès, 1 en cas d'erreur (voir alors le fichier sortie output.html ou output2.html)

Note: Si vous avez un message signalant que le processus de mise à jour est vérrouillé par un fichier install.lock, supprimer ce fichier (il est stocké dans le répertoire racine ou "documents" de Dolibarr) puis rafraichissez la page.

* Pour des raisons de sécurité nous vous conseillons, une fois la mise à jour terminée, de verrouiller le répertoire d'installation en créant un fichier install.lock dans le répertoire de donnée de Dolibarr. Dans le cas contraire, Dolibarr vous avertira d'un message dans l'interface une fois loggé
<source lang="bash">
$ echo > documents/install.lock
$ chmod 444 documents/install.lock
</source>

= Configurer une connexion LDAP =
Si vous désirez utiliser LDAP: Voir [[Installer et configurer OpenLDAP]].

= Importer des données externes =
Pour cette opération, consulter la page [[Imports_de_masse]].

= Configuration - Paramétrage =
Voir la page [[Premiers_paramétrages|Configuration/Paramétrage]].

Module Timesheet

2017-03-08T15:38:36Z

Delcroip:

[[Category:Complementary modules]]
[[Category:timesheet]]
{{TemplateDocDevEn}}
{{TemplateDocUser}}
<keywords content="timesheet, Dolibarr, interface, project, task, report, approval" />

= Informations =
{{TemplateModuleInfo
|modulename=timesheet
|editor=delcroip
|webbuy={{LinkToPluginDownloadDoliStore|keyword=timesheet}}
|status=stable
|prerequisites=projects
|minversion=3.5.0
|maxversion=4.0.4
|note=Latest Module version: 1.5.1
}}

= Manual =
[https://wiki.dolibarr.org/upload/b/bd/Module_timesheet.pdf manual]

= Features =

- Timesheet interface for all the user task per week
- Generate report on user and on project per month
- whitelist to show only some project/task (if no whitelist define all task are showed)
- Approval of the timesheets per the N+1

[[File:timesheet_timeentry.jpg]]

= Change logs =

Change log from 1.5
* Support dolibarr 4.0.1
* Hidden option to join file to timesheets via the setting TIMESHEET_ADD_DOCS

Change log from 1.4.3:
* Timesheet approval by N+1,
* Reminder (email) for to be approved timesheet possible through dolibarr planned tasks
* admin wiew for the Approval (change a approval status outside the normal approval flow)
* Home box with the pending timesheet to be approved
* Blocking some weekdays (e.g week ends)
* Holiday showed in the timesheet
* Holiday time can be included in the timesheet totals
* Typo correction for French.
* Posibility to add a note
* Compatible with dolibarr 3.9.2

Change log from 1.4.1:

* Correction of the Spanish language (thanks to vinclar)
* Possible to deactivate the dolibarr Ajax for the dropdown list for the setup page (in case of issue to add whitelist)
* Keep the whitlistmode after submit / go to date / next / previsous week

Change log from 1.4:
* Bugfix for the tasktime date in the project page
* Link to have the different whitelist behaviour (black list, and none)
* Spanish language (google trad)
* Typo correction for French
* Support the print mode for timesheet & the report
* Show the project open to everyone on the new whitelist page

Change log from 1.3.7:
* layout improvement: timesheet, setup page, reports
* whitelist to show only some project/task
* taslk column customisation
* new task column: company, parent task
* new report option: report all, export friendly layout
* user report available for the N-2, N-3

Change log from 1.3.6:
* compatible avec dolibarr 3.7
* Change log from 1.3.3:
* Works with PHP<=5.3
* Possibility to remove the 0:00
* Color code for already filled tasktime / new tasktime and error
* Bux fixes in the report
* Better date dialog
* N+1 is able to check the user report of his N's

Module Timesheet

2017-03-08T15:37:58Z

Delcroip: /* Informations */

Module Timesheet

2017-03-08T15:37:26Z

Delcroip: /* Informations */

[[Category:Complementary modules]]
[[Category:timesheet]]
{{TemplateDocDevEn}}
{{TemplateDocUser}}
<keywords content="timesheet, Dolibarr, interface, project, task, report, approval" />

= Informations =
{{TemplateModuleInfo
|modulename=timesheet
|editor=delcroip
|webbuy={{LinkToPluginDownloadDoliStore|keyword=timesheet}}
|status=stable
|prerequisites=projects
|minversion=3.5.0
|maxversion=4.0.4
|note=Latest Module version: 1.5.1
|manual=[https://wiki.dolibarr.org/upload/b/bd/Module_timesheet.pdf manual]
}}

= Features =

- Timesheet interface for all the user task per week
- Generate report on user and on project per month
- whitelist to show only some project/task (if no whitelist define all task are showed)
- Approval of the timesheets per the N+1

[[File:timesheet_timeentry.jpg]]

= Change logs =

Change log from 1.5
* Support dolibarr 4.0.1
* Hidden option to join file to timesheets via the setting TIMESHEET_ADD_DOCS

Change log from 1.4.3:
* Timesheet approval by N+1,
* Reminder (email) for to be approved timesheet possible through dolibarr planned tasks
* admin wiew for the Approval (change a approval status outside the normal approval flow)
* Home box with the pending timesheet to be approved
* Blocking some weekdays (e.g week ends)
* Holiday showed in the timesheet
* Holiday time can be included in the timesheet totals
* Typo correction for French.
* Posibility to add a note
* Compatible with dolibarr 3.9.2

Change log from 1.4.1:

* Correction of the Spanish language (thanks to vinclar)
* Possible to deactivate the dolibarr Ajax for the dropdown list for the setup page (in case of issue to add whitelist)
* Keep the whitlistmode after submit / go to date / next / previsous week

Change log from 1.4:
* Bugfix for the tasktime date in the project page
* Link to have the different whitelist behaviour (black list, and none)
* Spanish language (google trad)
* Typo correction for French
* Support the print mode for timesheet & the report
* Show the project open to everyone on the new whitelist page

Change log from 1.3.7:
* layout improvement: timesheet, setup page, reports
* whitelist to show only some project/task
* taslk column customisation
* new task column: company, parent task
* new report option: report all, export friendly layout
* user report available for the N-2, N-3

Change log from 1.3.6:
* compatible avec dolibarr 3.7
* Change log from 1.3.3:
* Works with PHP<=5.3
* Possibility to remove the 0:00
* Color code for already filled tasktime / new tasktime and error
* Bux fixes in the report
* Better date dialog
* N+1 is able to check the user report of his N's

Module Timesheet

2017-03-08T15:32:43Z

Delcroip: /* Informations */

Module Timesheet

2016-09-28T15:06:09Z

Delcroip:

Module Timesheet

2016-09-28T15:05:45Z

Delcroip:

Module Timesheet

2016-09-28T15:02:57Z

Delcroip:

File:Timesheet timeentry.jpg

2016-09-28T14:50:41Z

Delcroip: screenshot of module timesheet: user display of an empty timesheet

screenshot of module timesheet:
user display of an empty timesheet

Module Timesheet

2016-09-28T14:48:58Z

Delcroip:

Module Timesheet

2016-09-27T21:08:07Z

Delcroip: Creation of the timesheet page