Créer un modèle de document ODT ou ODS

2024-09-20T20:17:27Z

Fabquenneville: Added missing tags for project documents from english in french version of the page

[[en:Create_an_ODT_or_ODS_document_template]]
[[es:Crear_un_modelo_de_documento_ODT_o_ODS]]
[[de:Erstellen einer ODT-Dokumentvorlage]]


[[Category:Admin fr]]
{{TemplateDocUtil}}
Cette page décrit comment construire un modèle de document ODT ou ODS (Format de LibreOffice, OpenOffice, ...) pour générer un document automatiquement rempli par Dolibarr.

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

*ODT est le format de documents générés par LibreOffice Writer par exemple (cas le plus fréquemment utilisé pour la génération de document).
*ODS est le format de documents générés par LibreOffice Calc par exemple.

Vous pouvez utiliser l'un ou l'autre comme modèle de document dans Dolibarr...

==Prérequis==

*Dolibarr: 3.1+
*LibreOffice ou tout éditeur de fichier ODT ou ODS (OpenOffice, ...)

==Créer votre document==

*Créer un document OpenOffice ou LibreOffice en partant de rien ou en prenant un example fournis. Si vous partez d'un exemple, vous les trouverez installés dans les sous-répertoires du répertoire '''documents/doctemplates'''
*Éditer le document en utilisant toutes les fonctions de votre suite bureautique.

Inclure dans votre documents les tags des informations que vous voulez voir. Les tags seront remplacés automatiquement au moment de la génération du document par Dolibarr. La liste des tags disponibles est décrite dans le chapitre suivant.

[[File:warning.png]] <span style="color:#FE0000">Attention, les tags sont entourés de {} ou [] pour les tableaux ou conditions (voir plus loin) et doivent être tapés d'une traite sous la suite Office (sans retour arrière ou effacement, ni par copié-collé). Dans le cas contraire, la suite Office ajoutera des informations invisibles qui empêche le remplacement. Il est également possible d'utiliser les copier-coller mais en faisant un collage spécial sans formatage (CTRL+MAJ+V)</span>.

==Tags==
Voici la liste des tags qui seront remplacés par les informations appropriées:

===Company/foundation information===
{{TagsOdtMyCompany}}

===Customers, prospects or suppliers information===
{{TagsOdtThirdParty}}

===Contacts===
Ce sont les balises pour :

*contact de facture pour les factures (type BILLING)
*contact d'appel d'offres (type CUSTOMER)
*contact de commande pour les commandes de vente (type CUSTOMER)

Il n'y a pas de tags pour le contact de livraison et les autres objets ne peuvent utiliser ces tags non plus.
{{TagsOdtContact}}

===Information utilisateur===
{{TagsOdtUser}}

===Autres informations===
{{TagsOdtOther}}

===Informations sur l'objet (facture, proposition commerciale, commande, ...)===
{{TagsOdtObjects}}

[[File:Info.png]]

Pour la balise {object_total..._x}, s'il n'y a pas de montant pour le taux de tva x, la clé n'est pas remplacée. Vous pouvez donc utiliser la syntaxe de condition pour afficher 0 au lieu de la clé lorsque la valeur n'est pas définie :
<syntaxhighlight lang="bash">
[!-- IF {object_total..._locale_x} --]
0
[!-- ELSE {object_total..._locale_x} --]
{object_total_vat_locale_x}
[!-- ENDIF {object_total..._locale_x} --]
</syntaxhighlight>
[[File:Warning.png]] Pour être sûr que cette partie du code ne contient pas de texte caché (ajouté silencieusement par LibreOffice à des fins de gestion de version/suivi des changements), vous devez sélectionner toute la section de code, faire un clic droit et sélectionner la fonctionnalité "Supprimer le formatage direct" (ne pas faire cela peut rendre la section de code non opérationnelle).

===Lignes des objets===
Voici comment utiliser les tableaux de lignes des objets (lignes de factures, commandes, etc...). Vous devez créer un tableau dans le document et utiliser une balise "begin" et "end" pour définir la ligne du tableau. Cette ligne sera répétée autant de fois que requis au moment de la génération.
<pre>
[!-- BEGIN row.lines --]
...
[!-- END row.lines --]
</pre>

Ensuite, ajouter les tags de votre choix dans les lignes parmi ceux-ci (en plus des tags de documents également disponibles):
{{TagsOdtLines}}

Voici un exemple de ce que vous pourriez avoir dans votre traitement de texte:
[[File:Line for document generation.png|500px]]

===Pour les documents de projet===
Pour les documents sur les projets et les tâches, vous avez également
{{TagsOdtProject}}

===Substitution conditionnelle===

Vous pouvez utiliser des '''remplacements conditionnels''', ce qui en termes simples signifie que vous pouvez décider d'imprimer quelque chose si une variable est vrai, ou imprimer autre chose si elle est fausse (ou rien du tout) - et cela marche non seulement avec du texte, mais aussi toute structure plus complexe comme les tableaux et les images.

Exemple:
<pre>
[!-- IF {my_var} --]
Print this text if {my_var} is true (can be any value but null/0/empty string)
[!-- ELSE {my_var} --]
Or print this if it's false (null/0/empty string)
[!-- ENDIF {my_var} --]
</pre>

Note: le tag ELSE est bien sûr optionnel, vous pouvez sans problème juste utiliser un IF/ENDIF si vous préférez.

ATTENTION: le format de cette balise spéciale est très précis et pointilleux, faire attention à '''mettre un seul espace''' entre:

*[!--
*IF/ELSE/ENDIF
*{my var}
*--]

Exemple d'utilisation :

[!-- IF {line_product_label} --] {line_product_label} [!-- ELSE {line_product_label} --] {line_fulldesc} [!-- ENDIF {line_product_label} --]

===Autres tags personnalisés===
Si vous voulez ajouter un champ de substitution non prédéfini, il y a une solution:

*Ajouter un fichier nommé '''htdocs/monmodule/core/substitutions/functions_mymodule.lib.php'''
*Dans ce fichier , écrivez juste une fonction du genre:

<syntaxhighlight lang="PHP">
/** Function called to complete substitution array (before generating on ODT, or a personalized email)
* functions xxx_completesubstitutionarray are called by make_substitutions() if file
* is inside directory htdocs/core/substitutions
*
* @param array $substitutionarray Array with substitution key=>val
* @param Translate $langs Output langs
* @param Object $object Object to use to get values
* @return void The entry parameter $substitutionarray is modified
*/
function mymodule_completesubstitutionarray(&$substitutionarray,$langs,$object)
{
global $conf,$db;

$myvalue='Put here calculated value to insert';
$substitutionarray['myowntag']=$myvalue;
}
</syntaxhighlight>

La fonction sera appelée avant la génération du document afin de compléter le tableau des substitutions afin que le tag '''myowntag''' soit remplacé par la valeur définie dans '''$myvalue'''.
Vous pouvez ajouter autant de tag que désiré, et mettre le code que vous voulez pour définir les valeurs (recherche en base, en fichier, calcul, partir des variables reçues ou globales...).

Attention: Le premier paramètre dans la déclaration de la fonction doit commencer par & car il est modifié par le code et doit être retourné modifié.

Pour que vote votre fonction de substitution soit bien appelée, il vous faut:

*Vérifier que votre fichier de substitution est bien stocké dans le répertoire '''htdocs/monmodule/core/substitutions'''
*Créer un module (Voir la page [[Développement module]]) avec son fichier descripteur de module.
*Vérifier que le fichier descripteur de module contient une entrée pour déclarer qu'il y a un fichier de substitution à appeler. Cette doit être

<syntaxhighlight lang="PHP">
$this->module_parts = array('substitutions' => 1)
</syntaxhighlight>

*Activer le module (un module doit être activé et désactivé pour prendre en compte les changement dans son fichier descripteur)

===Autres tags personnalisées pour les lignes===

Cette fonctionnalité est disponible depuis Dolibarr v3.3 (version de développement futur).

De manière similaire au chapitre précédent, vous devez définir une fonction de la même façon mais avec quelques différences:

*Créez ou modifiez le même fichier que précédemment (voir le chapitre précédent).
*Voici les différences: dans le fichier, écrire une autre fonction avec presque le même nom mais avec '_lines' en suffixe, et également ajouter une nouvelle variable $lines:

<syntaxhighlight lang="PHP">
/** Function called to complete substitution array for lines (before generating on ODT, or a personalized email)
* functions xxx_completesubstitutionarray_lines are called by make_substitutions() if file
* is inside directory htdocs/core/substitutions
*
* @param array $substitutionarray Array with substitution key=>val
* @param Translate $langs Output langs
* @param Object $object Object to use to get values
* @param Object $line Current line being processed, use this object to get values
* @return void The entry parameter $substitutionarray is modified
*/
function mymodule_completesubstitutionarray_lines(&$substitutionarray,$langs,$object,$line) {
{
global $conf,$db;

$myvalue='Put here calculated value to insert';
$substitutionarray['myowntag']=$myvalue;
}
</syntaxhighlight>

Contrairement à la fonction précédente qui n'est jamais appelée qu'une seule fois, cette fonction sera appelée à chaque fois qu'une ligne de produit sera traitée, en vous donnant chaque fois un objet $line différent que vous pouvez traiter. Cela vous permet de faire des substitutions de tags différentes pour chaque produit.

==Enregistrer votre document==
Pour voir apparaître votre modèle de document dans la liste des modèles disponibles en allant dans la configuration du module. Dans la section Modèle ODT/ODS, il y a un petit formulaire pour téléverser le modèle.
Il est aussi possible de placer le fichier manuellement dans le sous-répertoire adéquat qui se trouve dans le répertoire '''documents/doctemplates'''

Dolibarr ERP CRM Wiki - User contributions [en]

Créer un modèle de document ODT ou ODS