Difference between revisions of "Module CustomFields FR"

From Dolibarr ERP CRM Wiki
Jump to navigation Jump to search
Visual
(Ajout de quelques paragraphes en fr)
m
Tag: 2017 source edit
 
(25 intermediate revisions by 5 users not shown)
Line 1: Line 1:
−
{{ToTranslate}}
+
<!-- BEGIN interlang links -->
 +
<!-- Do NOT edit this section
 +
    Links below are automatically managed by PolyglotBot
 +
    You can edit links on the English source page : Module_CustomFields -->
 +
[[en:Module_CustomFields]]
 +
<!-- END interlang links -->
 +
 
 +
[[Category:Modules complémentaires]]
 +
[[Category:CustomFields]]
 +
{{TemplateDocUtil}}
 +
{{TemplateModFR}}
 +
 
 +
'''<span style="color:red; font-size: 1.5em;">This module is not available for Dolibarr Version > 3 . </span>'''
 +
'''<span style="color:red; font-size: 1.5em;">For newer Dolibarr version use the native [[Extrafields]] feature, see the related page.</span>'''
 +
 
 
L'article n'a pas encore été entièrement traduit en français.
 
L'article n'a pas encore été entièrement traduit en français.
  
 
Veuillez [[Module_CustomFields|lire le wiki en anglais]] qui est déjà complet (icône à gauche).
 
Veuillez [[Module_CustomFields|lire le wiki en anglais]] qui est déjà complet (icône à gauche).
  
 +
{{ToTranslate}}
 +
 +
= Informations =
 +
{{TemplateModuleInfo
 +
|editor=
 +
|web=
 +
|webbuy={{LinkToPluginDownloadDoliStore|keyword=customfield}}
 +
|status=stable
 +
|prerequisites=Dolibarr <= 3.3.*
 +
|minversion=3.2.0
 +
|note=
 +
}}
 +
 +
= Description =
 +
Ce module permet à l'utilisateur de créer et de manipuler facilement des champs personnalisés, et de les utiliser ensuite dans les documents PDF ou ODT, ainsi que dans le code PHP
 +
 +
Vous pouvez choisir le type de données, la taille, le libellé, les valeurs possibles, celle par défaut ainsi que des contraintes (liens vers d'autres tables) ou des requêtes SQL.
 +
 +
Le module CustomFields a été conçu pour vous permettre de :
 +
 +
* créer facilement des champs personnalisés avec le type de données de votre choix
 +
* manipuler/créer/modifier/supprimer des listes de champs personnalisés
 +
* Utiliser facilement ces champs dans vos documents PDF ou ODT, ou dans n'importe quel morceau de code PHP
 +
 +
Ce module a pour philosophie :
 +
 +
* Le respect des standards.
 +
* L'indépendance du code de dolibarr.
 +
* Etre réutilisable.
 +
 +
CustomFields a été conçu dans l'optique d'être le plus portable, souple, modulaire et réutilisable possible, ainsi il pourra être adapté à n'importe quel module Dolibarr, ainsi qu'à (presque) n'importe quel besoin utilisateur (même si ce besoin n'est pas encore codé, vous pourrez probablement simplement créer une requête SQL, le reste sera généré autumatiquement).
 +
 +
= Comprendre CustomFields =
 +
 +
Techniquement parlant, ce module est une coquille (wrapper) pour la base de données SQL. Il repsecte les standards SQL, et les manipule de façon standardisée.
 +
 +
Ceci signifie que vous pouvez modifier votre base de données avec un outil tel que phpMyAdmin et que ces changements seront reflétés dans le module de la même façon.
 +
 +
= Fonctionnalités =
 +
 +
- Implémenté nativement dans les modules : Factures, Propales et Produits/Services.
 +
 +
- Totalement multilingue :
 +
* Interface d'Administration  (français et anglais pour l'instant, mais peut être traduit dans n'importe quel langue avec les fichier .lang)
 +
* Libellés des champs personnalisés multilingues
 +
* Valeurs des champs personnalisés multilingues (ex: Case à cocher oui/non qui peut être traduite vers n'importe quelle langue, idem pour les énumérations définies par l'utilisateur). Vous pouvez même traduire les valeurs de vos listes déroulantes ou vos champs contraints.
 +
 +
- Plusieurs types de données standards supportés :
 +
* Textbox
 +
* Areabox
 +
* YesNoBox
 +
* TrueFalseBox
 +
* DropdownBox (avec vos propores valeurs)
 +
* Date
 +
* DateTime
 +
* Integer
 +
* Float
 +
* Double
 +
* Contrainte (lien vers d'autres tables)
 +
* Autres (type personnalisé, défini par votre propre requête SQL)
 +
 +
Note : vous pouvez ajouter vos propres types de données SQL, voyez le chapitre adéquat.
 +
Le dernier type n'est pas un type de données standard à proprement parler, mais il permet d'utiliser tout type de données SQL qui n'est pas encore implémenté, il sera manipulé du mieux possible par le module (per défaut, il sera affiché comme une TextBox)
 +
 +
- Requêtes SQL personnalisées pour créer des champs complexes : ces requêtes seront exécutées après la création/modification de la définition du champ personnalisé.
 +
 +
- Mise à jour des champs personnalisés automatique par la base de données et par les Triggers.
 +
 +
- utilisable par tout module, qu'il soit natif (core) ou externe (voir le chaiptre correspondant).
 +
 +
- Détection et utilisation des contraintes automatique (recherche de la clé primaire, choix du même type et taille du champ) et gestion automatique de l'impression et de la modification (affichées comme une liste déroulante).
 +
 +
- remplacement des index par les valeurs d'une autre colonne pour les champs avec contraintes : indiquez quelle(s) colonne(s) vous souhaitez voir apparaitre, et le module affichera la colonne associée à la place de l'ID de l'enregistrement (voir le chapitre correspondant)
 +
 +
- possibilité de définir plusieurs champs personnalisés pour chaque module
 +
 +
- utilisation facile dans les templates PDF et ODT (voir le chapitre correspondant).
 +
 +
- Fonctionne sur mobiles et tablettes : pas d'AJAX, pas de javascript, uniquement du HTML standard.
 +
 +
- Présentation élégantes dans les feuilles de calcul.
 +
 +
- Supporte toutes les fonctions classiques des champs standards (création, édtion, duplication, etc.)
 +
 +
- Isolation du code : n'interfère pas avec le fonctionnement normal de Dolibarr, tout est séparé. Vous pouvez simplement supprimer les champs personnalisés, aucune donnée ne sera impactée, pas plus que votre installation de Dolibarr.
 +
 +
- Développez votre propres modules avec CustomFields : CF fournit de nombreuses méthodes de gestion des entrées des utilisateurs ainsi que de manipulation des valeurs depuis n'importe où dans le code (Natif ou vos modules), et même quelques fonctions génériques pour exécuter n'importe quelle requête SQL et vous aider à l'optimiser, avec gestion automatique des erreurs.
 +
 +
- Le code est très simple à modifier/customiser/réutiliser/porter... (Architecture modulaire totalement commentée, et aucune fonction en double).
 +
 +
- Utilisation stricte des standards SQL, garantissant ainsi le bon fonctionnement avec n'importe quelle base de données respectant ces standards (testé avec MySQL, fonctionne probablement avec PostgreSQL et SQLite).
 +
 +
- Sécurisé : seuls les utilisateurs autorisés peuvent éditer les champs personnalisés (ceux qui ont les droits Créer et Modifier pour ce module)
 +
 +
- Optimisé et rapide : utilisation du cache partout ou cela est possible, et requêtes SQL super optimisées. Code PHP rapide, avec aussi peu de boucles que possible.
 +
 +
 +
= Pré-requis =
 +
 +
Ce module nécessite que votre base de données implémente les clés étrangères pour être totalement fonctionnel - par exemple utilisez InnoDB avec MySQL plutot que MyISAM qui ne supporte pas les clés étrangères et le contrôle d'intégrité référentielle.
 +
 +
Cependant, dans le cas où vous ne pouvez vraiment pas utiliser les clés étrangères dans votre base de données, CustomFields peut toujours fonctionner en [[Module_CustomFields_Dev#SQL_Compatibility_mode|mode de compatibilité]]: vous aurez la plupart des fonctions, dont les contraintes, mais votre base de données sera un peu moins propre.
 +
 +
pour de plus amples informations, référez-vous à la documentation Développeur au sujet du [[Module_CustomFields_Dev#SQL_Compatibility_mode|mode de compatibilité SQL]].
 +
 +
= Utilisation =
 
== Traduction du libellé d'un champ ==
 
== Traduction du libellé d'un champ ==
  
Line 17: Line 137:
 
== Testez vos champs personnalisés avec le module PDFTest ==
 
== Testez vos champs personnalisés avec le module PDFTest ==
  
−
An auxiliary module called CustomFieldsPDFTest is provided so that you can easily test your custom fields in your PDF outputs. This avoids the need to make your own PDF template and risking to do some mistakes in the php code.
+
Un module auxiliare appelé CustomFieldsPDFTest est fourni afin que que vous puissiez facilement et rapidement tester vos champs personnalisés dans vos documents PDF. Cela évite d'avoir à faire votre propre modèle PDF juste pour tester et risquer de faire des erreurs de code php.
 +
 
 +
Il suffit juste d'activer le module CustomFieldsPDFTest dans Accueil>Configuration>Modules et ensuite de générer un fichier PDF en utilisant n'importe quel modèle.
  
−
Just enable the CustomFieldsPDFTest in Home>Setup>Modules and then generate a PDF document using any template.
+
Une page sera rajouté à la fin du fichier PDF généré, contenant une liste extensive de tous les champs personnalisés disponibles ainsi que leurs valeurs, et leurs valeurs brut(=raw) (valeur raw = pas de beautification, pas d'encode html ni de traduction).
  
−
A page will be appended to the end of the generated PDF with an extensive list of all the available custom fields, their values and their raw values (raw value = no beautify, no html encode and no translation).
+
Vous pouvez ainsi vérifier qu'un champ personnalisé correspond bien à vos besoins et délivre toutes les informations dont vous aurez besoin dans votre futur modèle PDF.
  
−
You can then see if the custom fields fits your needs and contain all the informations you will need in your final PDF template. Disable it when finished, you will make your own PDF template after (see below).
+
Quand vous avez fini le test, désactivez simplement le module, vous ferez votre propre modèle PDF (voir ci-dessous)
  
−
Note: already generated pdf files won't be affected, only generated PDF documents '''after the PDFTest module is activated''' will have a list of custom fields appended, and if you disable the module and generate again the PDF document, the appended page will disappear.
+
Note: les documents PDF déjà générés ne seront pas affectés, seulement les documents générés '''après l'activation du module PDFTest''' se verront octroyés cette page supplémentaire de champs personnalisés, et après désactivation du module, si vous générez à nouveau le document PDF, les pages supplémentaires disparaîtrons.
  
−
== Implementing in ODT templates ==
+
== Implémentation dans les modèles ODT ==
  
−
Custom fields are automatically loaded for ODT templates.
+
Les champs personnalisés sont automatiquement chargés pour les modèles ODT sans opération supplémentaire.
  
−
Just use the shown variable name ('''Variable''' column in the configuration page) as a tag enclosed by two braces.
+
Utilisez juste le nom de la Variable (colonne '''Variable''' dans le panneau admin) comme un tag, enclosé de deux accolades.
  
−
Eg: for a customfield named user_ref, you will get the Variable name cf_user_ref. In your ODT, to get the value of the field, just type
+
Ex: pour un champ personnalisé nommé user_ref, vous obtiendrez comme nom de Variable cf_user_ref. Dans votre ODT, pour obtenir la valeur de ce champ, il suffit de faire:
 
<pre>
 
<pre>
 
{cf_user_ref}
 
{cf_user_ref}
 
</pre>
 
</pre>
  
−
You can also get the raw value (without any preprocessing) by appending _raw to the variable name:
+
Vous pouvez également obtenir la valeur brute (sans aucun pré-traitement) en ajoutant le suffixe _raw au nom de variable:
 
<pre>
 
<pre>
 
{cf_user_ref_raw}
 
{cf_user_ref_raw}
 
</pre>
 
</pre>
  
−
There is also full support for constrained fields, so that if you have a constraint on this field, it will automatically fetch all the linked values of the referenced tables and you will be able to use them with tags.
+
Il y a également un support complet des champs contraints, ce qui fait que si vous avez une contrainte sur ce champ, les valeurs liées dans la table référencée seront automatiquement récupérées et vous serez en mesure de les utiliser avec de simples tags.
−
Eg: cf_user_ref is constrained on the '''llx_user''' table:
+
 
 +
Ex: cf_user_ref est contraint sur la table '''llx_user''':
 
<pre>
 
<pre>
 
{cf_user_ref} = rowid
 
{cf_user_ref} = rowid
Line 52: Line 175:
 
</pre>
 
</pre>
  
−
As you can see, you just need to append '_' and the name of the column you want to access to show the corresponding value.
+
Comme vous pouvez le voir, il suffit de rajouter le suffixe '_' et le nom de la colonne sql dont vous voulez obtenir la valeur.
  
−
For lines, it works just the same, you just have to put the variable name inside the table that handles the product's lines, between the tags [!-- BEGIN row.lines --] and [!-- END row.lines --]
+
Pour les lignes produits, cela fonctionne de la même façon, il suffit d'écrire le nom de Variable dans la table des lignes produits, entre les tags [!-- BEGIN row.lines --] et [!-- END row.lines --]
  
−
Note: an interesting use of custom fields is to use a TrueFalseBox with a conditional substitution, eg: with a custom fields cf_enablethis:
+
Note: un usage intéressant des champs personnalisés est d'utiliser un type Vrai/Faux avec une substitution conditionnelle, ex: avec un champ personnalisé cf_enablethis:
 
<pre>
 
<pre>
 
[!-- IF {cf_enablethis_raw} --]
 
[!-- IF {cf_enablethis_raw} --]
−
This is enabled and this will show.
+
Ce texte s'affichera si cf_enablethis est Vrai
 
[!-- ELSE {cf_enablethis_raw} --]
 
[!-- ELSE {cf_enablethis_raw} --]
−
Else this will show up when disabled.
+
Sinon, ce texte ci s'affichera si cf_enablethis est Faux
 
[!-- ENDIF {cf_enablethis_raw} --]
 
[!-- ENDIF {cf_enablethis_raw} --]
 
</pre>
 
</pre>
−
We need to use the raw value, because we need to have a 0/1 value for the conditional to work (or empty/non-empty, so this can also work for empty Textbox: if there's no text, you can avoid to show anything - this in fact works for any other sql datatypes).
+
Il est nécessaire d'utiliser la valeur brute, car il est fiable d'avoir une valeur 0/1 pour que la condition fonctionne. Sinon on peut aussi avoir vide/non-vide, ce qui fait que cette technique fonctionne aussi pour les types Text ou tout autre: si le texte est vide, vous pouvez ne rien afficher, par contre si le texte n'est pas vide vous pouvez mettre un préambule et la valeur du champ:
 +
<pre>
 +
[!-- IF {cf_mytextfield_raw} --]
 +
Mon champ texte n'est pas vide, voici sa valeur: {cf_mytextfield}
 +
[!-- ENDIF {cf_mytextfield_raw} --]
 +
</pre>
  
−
== Implementing in PDF templates ==
+
== Implémentation dans les modèles PDF ==
  
−
To use custom fields in your PDF template, you first need to load the custom fields datas, then you can use them wherever you want.
+
Pour utiliser vos champs personnalisés dans votre modèle PDF, vous devez tout d'abord charger les données des champs personnalisés, ensuite vous pourrez les utiliser comme bon vous semble.
  
−
* To load the custom fields:
+
* Pour charger les champs personnalisés:
 +
Placer le code suivant le plus haut possible dans votre modèle PDF:
 
<source lang="php">
 
<source lang="php">
 
// Init and main vars for CustomFields
 
// Init and main vars for CustomFields
−
dol_include_once(DOL_DOCUMENT_ROOT.'/customfields/lib/customfields_aux.lib.php');
+
dol_include_once('/customfields/lib/customfields_aux.lib.php');
  
 
// Filling the $object with customfields (you can then access customfields by doing $object->customfields->cf_yourfield)
 
// Filling the $object with customfields (you can then access customfields by doing $object->customfields->cf_yourfield)
Line 81: Line 210:
 
</source>
 
</source>
  
−
Note: you can place this just after:
+
Note: vous pouvez placer le code au-dessus juste en-dessous de cette ligne dans les modèles PDF:
 
<source lang="php">
 
<source lang="php">
 
$pdf=pdf_getInstance($this->format);
 
$pdf=pdf_getInstance($this->format);
 
</source>
 
</source>
  
−
* To access the field's value:
+
* Pour accéder à la valeur du champ personnalisé:
  
−
Beautified formatting:
+
Formattage beautifié:
 
<source lang="php">
 
<source lang="php">
 
$object->customfields->cf_myfield
 
$object->customfields->cf_myfield
 
</source>
 
</source>
−
or for the raw value:
+
ou pour la valeur brute:
 
<source lang="php">
 
<source lang="php">
 
$object->customfields->raw->cf_myfield
 
$object->customfields->raw->cf_myfield
 
</source>
 
</source>
  
−
* To access a product's line's value:
+
* Pour accéder aux champs personnalisés des lignes produits:
 
<source lang="php">
 
<source lang="php">
 
$lineid = $object->lines[$i]->rowid;
 
$lineid = $object->lines[$i]->rowid;
−
$object->customfields->lines->$lineid>cf_myfield
+
$object->customfields->lines->$lineid->cf_myfield
 
</source>
 
</source>
−
Where $lineid must be replaced by the id of the line you want to fetch (rowid of the product, so it does NOT necessary start at 0).
+
Où $lineid doit être remplacé par l'id de la ligne produit que vous voulez récupérer (rowid sql des produits, donc ça ne commence pas forcément par 0 et peut être n'importe quel nombre).
  
−
* To print it with FPDF (the default PDF generation library):
+
* Pour imprimer le champ dans votre PDF avec FPDF (librairie PDF par défaut):
 
<source lang="php">
 
<source lang="php">
 
$pdf->MultiCell(0,3, $object->customfields->cf_myfield, 0, 'L'); // printing the customfield
 
$pdf->MultiCell(0,3, $object->customfields->cf_myfield, 0, 'L'); // printing the customfield
 
</source>
 
</source>
  
−
* And if you want to print the multilanguage label of this field :
+
* Et si vous souhaitez imprimer le libellé en multilangue:
 
<source lang="php">
 
<source lang="php">
 
$outputlangs->load('customfields-user@customfields');
 
$outputlangs->load('customfields-user@customfields');
 
$mylabel = $customfields->findLabel("cf_myfield", $outputlangs); // where $outputlangs is the language the PDF should be outputted to
 
$mylabel = $customfields->findLabel("cf_myfield", $outputlangs); // where $outputlangs is the language the PDF should be outputted to
 
</source>
 
</source>
−
or if you want to do it automatically (useful for a loop):
+
ou si vous souhaitez le faire automatiquement (utile dans une boucle):
 
<source lang="php">
 
<source lang="php">
 
$outputlangs->load('customfields-user@customfields');
 
$outputlangs->load('customfields-user@customfields');
Line 121: Line 250:
 
</source>
 
</source>
  
−
== Implementing in php code (dolibarr core modules or your own module) ==
+
== Implémentation en code php (module core Dolibarr ou pour vos propres modules) ==
  
−
One of the main features of the CustomFields module is that it offers a generic way to access, add, edit and view custom fields from your own code. You can easily develop your own modules accepting user's inputs based on CustomFields.
+
Une des fonctionnalités principales du module CustomFields est qu'il offre un moyen générique d'accéder, d'ajouter, de modifier et d'afficher des champs personnalisés depuis votre propre code. Vous pouvez facilement développer votre propre module en utilisant uniquement des champs basés sur la classe CustomFields.
  
−
You can use a simplifier library that eases a lot the usage of custom fields in php codes:
+
Pour récupérer les valeurs des champs, vous pouvez utiliser la librairie simplificatrice qui facilite beaucoup l'utilisation des champs personnalisés vos codes php:
 
<source lang="php">
 
<source lang="php">
 
dol_include_once('/customfields/lib/customfields_aux.lib.php'); // include the simplifier library
 
dol_include_once('/customfields/lib/customfields_aux.lib.php'); // include the simplifier library
 
$customfields = customfields_fill_object($object, null, $langs); // load the custom fields values inside $object->customfields
 
$customfields = customfields_fill_object($object, null, $langs); // load the custom fields values inside $object->customfields
 +
</source>
 +
 +
Vous pouvez alors facilement accéder aux valeurs des champs personnalisés comme ceci:
 +
<source lang="php">
 +
print($object->customfields->cf_myfield);
 +
</source>
 +
 +
Pour charger les champs personnalisés des lignes produits, vous pouvez utiliser la fonction customfields_fill_object_line():
 +
<source lang="php">
 +
dol_include_once('/customfields/lib/customfields_aux.lib.php'); // include the simplifier library
 +
$customfields = customfields_fill_object_lines($object, null, $langs); // load the custom fields values inside $object->customfields
 +
</source>
 +
 +
Vous pouvez alors accéder aux champs des lignes produits comme ceci:
 +
<source lang="php">
 +
$object->customfields->lines->$lineid->cf_myfield
 +
</source>
 +
 +
Vous pouvez également obtenir (et bien plus) manuellement les valeurs des champs personnalisés en utilisant la classe CustomFields:
 +
 +
<source lang="php">
 +
// Init and main vars
 +
//include_once(DOL_DOCUMENT_ROOT.'/customfields/class/customfields.class.php'); // OLD WAY
 +
dol_include_once('/customfields/class/customfields.class.php'); // NEW WAY since Dolibarr v3.3
 +
$customfields = new CustomFields($this->db, $currentmodule); // where $currentmodule is the current module, you can replace it by '' if you just want to use printing functions and fetchAny.
 +
 +
//$records = $customfields->fetchAll(); // to fetch all records
 +
$records = $customfields->fetch($id); // to fetch one object's records
 
</source>
 
</source>

Latest revision as of 20:49, 27 March 2022

Retour index
Documentation Utilisateur
File Doc user.png

Retour index
liste des modules
Art.png

This module is not available for Dolibarr Version > 3 . For newer Dolibarr version use the native Extrafields feature, see the related page.

L'article n'a pas encore été entièrement traduit en français.

Veuillez lire le wiki en anglais qui est déjà complet (icône à gauche).

En verysmall.png Page waiting for translation. To translate, create an account, go back and clic on "Modify".
Fr verysmall.png Page en attente de traduction. Pour traduire, créez un compte, revenez et cliquez sur "Modifier".
Es verysmall.png Página a traducir. Para traducirla, cree una cuenta, vuelva a la página y haga clic en "editar".
It verysmall.png Pagina da tradurre. Per tradurla, crea un utente, torna indietro e clicca su "modifica".
Pt verysmall.png Página a aguardar por tradução. Para traduzir, crie uma conta, volte atrás e clique em "Modificar".
De verysmall.png Seite wartet auf Übersetzung. Um Übersetzung zu erstellen, richte einen Account ein, geh zurück und klicke auf "bearbeiten".
Zh verysmall.png 页面等待翻译。若要翻译本页，先创建一个帐户、登录并返回本页后单击“编辑”。

Informations

Module name
Editor / Editeur
Download or buy page / Page achat ou téléchargement External module - www.dolistore.com
Status / Statut / Estado Stable
Prerequisites / Prérequis Dolibarr <= 3.3.*

Dolibarr min version: See on Dolistore    Dolibarr max version: See on Dolistore

Last update date / Date mise à jour fiche / Fecha última actualización 2022-03-27
Note / Nota

Description

Ce module permet à l'utilisateur de créer et de manipuler facilement des champs personnalisés, et de les utiliser ensuite dans les documents PDF ou ODT, ainsi que dans le code PHP

Vous pouvez choisir le type de données, la taille, le libellé, les valeurs possibles, celle par défaut ainsi que des contraintes (liens vers d'autres tables) ou des requêtes SQL.

Le module CustomFields a été conçu pour vous permettre de :

  • créer facilement des champs personnalisés avec le type de données de votre choix
  • manipuler/créer/modifier/supprimer des listes de champs personnalisés
  • Utiliser facilement ces champs dans vos documents PDF ou ODT, ou dans n'importe quel morceau de code PHP

Ce module a pour philosophie :

  • Le respect des standards.
  • L'indépendance du code de dolibarr.
  • Etre réutilisable.

CustomFields a été conçu dans l'optique d'être le plus portable, souple, modulaire et réutilisable possible, ainsi il pourra être adapté à n'importe quel module Dolibarr, ainsi qu'à (presque) n'importe quel besoin utilisateur (même si ce besoin n'est pas encore codé, vous pourrez probablement simplement créer une requête SQL, le reste sera généré autumatiquement).

Comprendre CustomFields

Techniquement parlant, ce module est une coquille (wrapper) pour la base de données SQL. Il repsecte les standards SQL, et les manipule de façon standardisée.

Ceci signifie que vous pouvez modifier votre base de données avec un outil tel que phpMyAdmin et que ces changements seront reflétés dans le module de la même façon.

Fonctionnalités

- Implémenté nativement dans les modules : Factures, Propales et Produits/Services.

- Totalement multilingue :

  • Interface d'Administration (français et anglais pour l'instant, mais peut être traduit dans n'importe quel langue avec les fichier .lang)
  • Libellés des champs personnalisés multilingues
  • Valeurs des champs personnalisés multilingues (ex: Case à cocher oui/non qui peut être traduite vers n'importe quelle langue, idem pour les énumérations définies par l'utilisateur). Vous pouvez même traduire les valeurs de vos listes déroulantes ou vos champs contraints.

- Plusieurs types de données standards supportés :

  • Textbox
  • Areabox
  • YesNoBox
  • TrueFalseBox
  • DropdownBox (avec vos propores valeurs)
  • Date
  • DateTime
  • Integer
  • Float
  • Double
  • Contrainte (lien vers d'autres tables)
  • Autres (type personnalisé, défini par votre propre requête SQL)

Note : vous pouvez ajouter vos propres types de données SQL, voyez le chapitre adéquat. Le dernier type n'est pas un type de données standard à proprement parler, mais il permet d'utiliser tout type de données SQL qui n'est pas encore implémenté, il sera manipulé du mieux possible par le module (per défaut, il sera affiché comme une TextBox)

- Requêtes SQL personnalisées pour créer des champs complexes : ces requêtes seront exécutées après la création/modification de la définition du champ personnalisé.

- Mise à jour des champs personnalisés automatique par la base de données et par les Triggers.

- utilisable par tout module, qu'il soit natif (core) ou externe (voir le chaiptre correspondant).

- Détection et utilisation des contraintes automatique (recherche de la clé primaire, choix du même type et taille du champ) et gestion automatique de l'impression et de la modification (affichées comme une liste déroulante).

- remplacement des index par les valeurs d'une autre colonne pour les champs avec contraintes : indiquez quelle(s) colonne(s) vous souhaitez voir apparaitre, et le module affichera la colonne associée à la place de l'ID de l'enregistrement (voir le chapitre correspondant)

- possibilité de définir plusieurs champs personnalisés pour chaque module

- utilisation facile dans les templates PDF et ODT (voir le chapitre correspondant).

- Fonctionne sur mobiles et tablettes : pas d'AJAX, pas de javascript, uniquement du HTML standard.

- Présentation élégantes dans les feuilles de calcul.

- Supporte toutes les fonctions classiques des champs standards (création, édtion, duplication, etc.)

- Isolation du code : n'interfère pas avec le fonctionnement normal de Dolibarr, tout est séparé. Vous pouvez simplement supprimer les champs personnalisés, aucune donnée ne sera impactée, pas plus que votre installation de Dolibarr.

- Développez votre propres modules avec CustomFields : CF fournit de nombreuses méthodes de gestion des entrées des utilisateurs ainsi que de manipulation des valeurs depuis n'importe où dans le code (Natif ou vos modules), et même quelques fonctions génériques pour exécuter n'importe quelle requête SQL et vous aider à l'optimiser, avec gestion automatique des erreurs.

- Le code est très simple à modifier/customiser/réutiliser/porter... (Architecture modulaire totalement commentée, et aucune fonction en double).

- Utilisation stricte des standards SQL, garantissant ainsi le bon fonctionnement avec n'importe quelle base de données respectant ces standards (testé avec MySQL, fonctionne probablement avec PostgreSQL et SQLite).

- Sécurisé : seuls les utilisateurs autorisés peuvent éditer les champs personnalisés (ceux qui ont les droits Créer et Modifier pour ce module)

- Optimisé et rapide : utilisation du cache partout ou cela est possible, et requêtes SQL super optimisées. Code PHP rapide, avec aussi peu de boucles que possible.


Pré-requis

Ce module nécessite que votre base de données implémente les clés étrangères pour être totalement fonctionnel - par exemple utilisez InnoDB avec MySQL plutot que MyISAM qui ne supporte pas les clés étrangères et le contrôle d'intégrité référentielle.

Cependant, dans le cas où vous ne pouvez vraiment pas utiliser les clés étrangères dans votre base de données, CustomFields peut toujours fonctionner en mode de compatibilité: vous aurez la plupart des fonctions, dont les contraintes, mais votre base de données sera un peu moins propre.

pour de plus amples informations, référez-vous à la documentation Développeur au sujet du mode de compatibilité SQL.

Utilisation

Traduction du libellé d'un champ

Les champs peuvent être facilement renommé ou traduit dans plusieurs langues en éditant les fichiers de langues.

Ouvrez le fichier /customfields/langs/code_CODE/customfields-user.lang (où code_CODE est le code ISO de votre région, ex: en_US ou fr_FR) et ajoutez dedans le nom de la Variable de votre champ personnalisé (affiché dans le panneau administrateur, colonne Variable) suivi de la traduction (format: cf_monchamp= Mon Libellé).

Ex: disons que votre champ personnalisé est nommé "user_ref", et que le nom de Variable résultat est "cf_user_ref". Dans customfields-user.lang il vous suffit d'ajouter: 

cf_user_ref= Le libellé que vous voulez. Vous pouvez même écrire une très très longue phrase ici.<br />Et vous pouvez même insérer des retours à la ligne avec <br />.

Testez vos champs personnalisés avec le module PDFTest

Un module auxiliare appelé CustomFieldsPDFTest est fourni afin que que vous puissiez facilement et rapidement tester vos champs personnalisés dans vos documents PDF. Cela évite d'avoir à faire votre propre modèle PDF juste pour tester et risquer de faire des erreurs de code php.

Il suffit juste d'activer le module CustomFieldsPDFTest dans Accueil>Configuration>Modules et ensuite de générer un fichier PDF en utilisant n'importe quel modèle.

Une page sera rajouté à la fin du fichier PDF généré, contenant une liste extensive de tous les champs personnalisés disponibles ainsi que leurs valeurs, et leurs valeurs brut(=raw) (valeur raw = pas de beautification, pas d'encode html ni de traduction).

Vous pouvez ainsi vérifier qu'un champ personnalisé correspond bien à vos besoins et délivre toutes les informations dont vous aurez besoin dans votre futur modèle PDF.

Quand vous avez fini le test, désactivez simplement le module, vous ferez votre propre modèle PDF (voir ci-dessous)

Note: les documents PDF déjà générés ne seront pas affectés, seulement les documents générés après l'activation du module PDFTest se verront octroyés cette page supplémentaire de champs personnalisés, et après désactivation du module, si vous générez à nouveau le document PDF, les pages supplémentaires disparaîtrons.

Implémentation dans les modèles ODT

Les champs personnalisés sont automatiquement chargés pour les modèles ODT sans opération supplémentaire.

Utilisez juste le nom de la Variable (colonne Variable dans le panneau admin) comme un tag, enclosé de deux accolades.

Ex: pour un champ personnalisé nommé user_ref, vous obtiendrez comme nom de Variable cf_user_ref. Dans votre ODT, pour obtenir la valeur de ce champ, il suffit de faire: 

{cf_user_ref}

Vous pouvez également obtenir la valeur brute (sans aucun pré-traitement) en ajoutant le suffixe _raw au nom de variable: 

{cf_user_ref_raw}

Il y a également un support complet des champs contraints, ce qui fait que si vous avez une contrainte sur ce champ, les valeurs liées dans la table référencée seront automatiquement récupérées et vous serez en mesure de les utiliser avec de simples tags.

Ex: cf_user_ref est contraint sur la table llx_user: 

{cf_user_ref} = rowid
{cf_user_ref_firstname} = firstname
{cf_user_ref_user_mobile} = mobile phone
etc...

Comme vous pouvez le voir, il suffit de rajouter le suffixe '_' et le nom de la colonne sql dont vous voulez obtenir la valeur.

Pour les lignes produits, cela fonctionne de la même façon, il suffit d'écrire le nom de Variable dans la table des lignes produits, entre les tags [!-- BEGIN row.lines --] et [!-- END row.lines --]

Note: un usage intéressant des champs personnalisés est d'utiliser un type Vrai/Faux avec une substitution conditionnelle, ex: avec un champ personnalisé cf_enablethis: 

[!-- IF {cf_enablethis_raw} --]
Ce texte s'affichera si cf_enablethis est Vrai
[!-- ELSE {cf_enablethis_raw} --]
Sinon, ce texte ci s'affichera si cf_enablethis est Faux
[!-- ENDIF {cf_enablethis_raw} --]

Il est nécessaire d'utiliser la valeur brute, car il est fiable d'avoir une valeur 0/1 pour que la condition fonctionne. Sinon on peut aussi avoir vide/non-vide, ce qui fait que cette technique fonctionne aussi pour les types Text ou tout autre: si le texte est vide, vous pouvez ne rien afficher, par contre si le texte n'est pas vide vous pouvez mettre un préambule et la valeur du champ: 

[!-- IF {cf_mytextfield_raw} --]
Mon champ texte n'est pas vide, voici sa valeur: {cf_mytextfield}
[!-- ENDIF {cf_mytextfield_raw} --]

Implémentation dans les modèles PDF

Pour utiliser vos champs personnalisés dans votre modèle PDF, vous devez tout d'abord charger les données des champs personnalisés, ensuite vous pourrez les utiliser comme bon vous semble.

  • Pour charger les champs personnalisés:

Placer le code suivant le plus haut possible dans votre modèle PDF: 

// Init and main vars for CustomFields
dol_include_once('/customfields/lib/customfields_aux.lib.php');

// Filling the $object with customfields (you can then access customfields by doing $object->customfields->cf_yourfield)
$this->customfields = customfields_fill_object($object, null, $outputlangs, null, true); // beautified values
$this->customfields_raw = customfields_fill_object($object, null, $outputlangs, 'raw', null); // raw values
$this->customfields_lines = customfields_fill_object_lines($object, null, $outputlangs, null, true); // product lines' values

Note: vous pouvez placer le code au-dessus juste en-dessous de cette ligne dans les modèles PDF: 

$pdf=pdf_getInstance($this->format);
  • Pour accéder à la valeur du champ personnalisé:

Formattage beautifié: 

$object->customfields->cf_myfield

ou pour la valeur brute: 

$object->customfields->raw->cf_myfield
  • Pour accéder aux champs personnalisés des lignes produits:
$lineid = $object->lines[$i]->rowid;
$object->customfields->lines->$lineid->cf_myfield

Où $lineid doit être remplacé par l'id de la ligne produit que vous voulez récupérer (rowid sql des produits, donc ça ne commence pas forcément par 0 et peut être n'importe quel nombre).

  • Pour imprimer le champ dans votre PDF avec FPDF (librairie PDF par défaut):
$pdf->MultiCell(0,3, $object->customfields->cf_myfield, 0, 'L'); // printing the customfield
  • Et si vous souhaitez imprimer le libellé en multilangue:
$outputlangs->load('customfields-user@customfields');
$mylabel = $customfields->findLabel("cf_myfield", $outputlangs); // where $outputlangs is the language the PDF should be outputted to

ou si vous souhaitez le faire automatiquement (utile dans une boucle): 

$outputlangs->load('customfields-user@customfields');
$keys=array_keys(get_object_vars($object->customfields));
$mylabel = $outputlangs->trans($keys[xxx]); // where xxx is a number, you can iterate foreach($keys as $key) if you prefer

Implémentation en code php (module core Dolibarr ou pour vos propres modules)

Une des fonctionnalités principales du module CustomFields est qu'il offre un moyen générique d'accéder, d'ajouter, de modifier et d'afficher des champs personnalisés depuis votre propre code. Vous pouvez facilement développer votre propre module en utilisant uniquement des champs basés sur la classe CustomFields.

Pour récupérer les valeurs des champs, vous pouvez utiliser la librairie simplificatrice qui facilite beaucoup l'utilisation des champs personnalisés vos codes php: 

dol_include_once('/customfields/lib/customfields_aux.lib.php'); // include the simplifier library
$customfields = customfields_fill_object($object, null, $langs); // load the custom fields values inside $object->customfields

Vous pouvez alors facilement accéder aux valeurs des champs personnalisés comme ceci: 

print($object->customfields->cf_myfield);

Pour charger les champs personnalisés des lignes produits, vous pouvez utiliser la fonction customfields_fill_object_line(): 

dol_include_once('/customfields/lib/customfields_aux.lib.php'); // include the simplifier library
$customfields = customfields_fill_object_lines($object, null, $langs); // load the custom fields values inside $object->customfields

Vous pouvez alors accéder aux champs des lignes produits comme ceci: 

$object->customfields->lines->$lineid->cf_myfield

Vous pouvez également obtenir (et bien plus) manuellement les valeurs des champs personnalisés en utilisant la classe CustomFields: 

// Init and main vars
//include_once(DOL_DOCUMENT_ROOT.'/customfields/class/customfields.class.php'); // OLD WAY
dol_include_once('/customfields/class/customfields.class.php'); // NEW WAY since Dolibarr v3.3
$customfields = new CustomFields($this->db, $currentmodule); // where $currentmodule is the current module, you can replace it by '' if you just want to use printing functions and fetchAny.

//$records = $customfields->fetchAll(); // to fetch all records
$records = $customfields->fetch($id); // to fetch one object's records
Retrieved from "https://wiki.dolibarr.org/index.php?title=Module_CustomFields_FR&oldid=53248"