View source for Extrafields : ajouter dans l’init du descripteur de module

Quelques repères sur la création (ou la mise à jour) d’un extrafield (ef) dans le descripteur de module.

==Création d’un nouvel ef==

Dans l’<code>init</code> du descripteur, on va charger la class, puis générer un nouvel ef<span> </span>:

<syntaxhighlight lang="php">
		include_once DOL_DOCUMENT_ROOT . '/core/class/extrafields.class.php';
		$extrafields = new ExtraFields($this->db);

		$res1 = $extrafields->addExtraField(
			'my_extrafield',  // attrname (nom de la colonne qui sera ajoutée dans la table llx_elementtype_extrafields, également répertorié dans la table llx_extrafields
			'MyExtrafieldName', // label (chaîne de traduction)
			'link', // type
			'123456', // pos (ordre d’emplacement sur la fiche et dans la liste, il est pertinent d’utiliser des numéros qui se suivent pour les champs d’un même module)
			'', // size''
			'product', // elementtype
			0, // unique
			0, // required
			'', // default_value''
			array('options' => array('Product:product/class/product.class.php::(e.another_extrafield:=:1)' => null)), // param
			1, // alwayeditable
			'$user->hasRight("product", "creer")', // perms
			-1, // list
			'', // help (chaîne de traduction s’affiche dans une infobulle si renseigné)''
			'', // computed (cf https://wiki.dolibarr.org/index.php/Extrafield_Champ_Calcul%C3%A9<nowiki/>)''
			$conf->entity, // entity
			'mymodule@mymodule, // langfile
			'isModEnabled("mymodule")', // enabled
            0, // $totalizable
            0, // $printable (sur PDF)
            array(), // $moreparams
            '', // $aiprompt''
            0, // $emptyonclone (ne pas reprendre la valeur pour un objet cloné)
		);
</syntaxhighlight>

===Point d’attention===

====Attribut attrname====

La paire nom-type d’élément doit être unique dans la table <code>llx_extrafields</code>. Préfixer le nom avec celui du module est donc une bonne pratique.

Il est important que les paramètres jusqu’à <code>enabled</code>, soient définis, celui-ci permettant de ne pas afficher l’extrafield si le module qui l’utilise est désactivé, sans pour autant perdre les valeurs enregistrés en bdd, dans la table des ef de l’objet.

====Attribut type====

L’attribut stratégique.

'''ATTENTION<span> </span>:''' le type conditionne les valeurs attendues dans l’attribut param.

Le champ param sera stocké, dans la table llx_extrafields, sous la forme d’une chaîne sérialisée. On peut donc mettre cette chaîne directement en param, mais c’est beaucoup moins lisible/ facile à écrire.

L’array PHP <code>array('options' => array('Product:product/class/product.class.php::(e.product_is_container:=:1)' => null))</code> deviendra par exemple <code><nowiki>a:1:{s:7:"options";a:1:{s:69:"Product:product/class/product.class.php::(e.product_is_container:=:1)";N;}}</nowiki></code>

Les valeurs reconnues pour le type sont<span> </span>:

======separate======
champ spécial qui ne créera pas de colonne dans la table des extrafields de l’objet mais seulement une entrée dans <code>llx_extrafields</code>. Affiche un texte de séparation qui peut masquer et démasquer les champs dont le l’attribut <code>pos</code> a une valeur supérieur au sien param nécessaire <code>array('options' => array(1 => null))</code> ou <code>array('options' => array(2 => null))</code> Une clé à 1 signifie que le champ sera replié par défaut (puis gardera les réglages utilisateur en mémoire). Une clé à 2, le contraire (déplié par défaut)

======boolean======
type int et taille fixées à 1 en bdd, pas de param

=====int=====
taille maxi 10 (dans la création d’ef via Dolibarr, en tout cas), pas de param

=====price=====
ne demande pas de valeur de taille (24,8 en bdd soit 24 chiffres dont 8 après la virgule), pas de param

=====pricecy=====
prix avec devise, champ texte (taille fixée à 64 char en bdd), pas de param

=====phone=====
chaîne de caractères, taille fixée à 20 en bdd, pas de param

=====email, mail, ip, icon=====
chaîne de caractère, taille fixée à 128 en bdd, pas de param

=====url=====
chaîne de caractère, taille fixée à 255 en bdd, pas de param

=====select, sellist, radio, checkbox, chkbxlst=====
chaîne de caractère, taille fixée à 255 en bdd, ''demandent que param soit renseigné''

*pour '''select''', ce doit être de la forme <code>array('options' => array('1' =>' tructruc', '2' => 'machinmachin'))</code>
*pour '''sellist''' et '''chkbxlst''', on attend <code>array('options' => array('table:ref|label:rowid::filtre sql' => null))</code> où <code>table</code> est une table de Dolibarr, <code>ref</code> le ou les champs uniques qu’on va afficher, <code>rowid</code> la clé primaire. Le filtre sql doit être au format Univeral Search Filter de Dolibarr la différence entre les deux étant que chkbxlst permet une sélection multiple
*pour '''radio''' ou '''checkbox''' <code>array('options' => array('1' =>' tructruc', '2' => 'machinmachin'))</code> la valeur 0 n’est pas autorisée ! checkbox permet une sélection multiple. Le choix proposé peut reprendre des clés-valeurs issues de champs ou ef de l’objet, suivant la syntaxe<span> </span>: <code>array('options' => array('1' =>' tructruc|options_nom_du_champ:valeur_du_champ', '2' => 'machinmachin|options_nom_du_champ:autre_valeur_du_champ'))</code>pour les ef et  <code>array('options' => array('1' =>' tructruc|nom_du_champ:valeur_du_champ', '2' => 'machinmachin|nom_du_champ:autre_valeur_du_champ'))</code> pour les champs de l’objet

=====link=====
lien vers un objet de Dolibarr, chaîne de caractère, type int et taille 11 en bdd, param doit être renseigne sous la forme <code>array('options' => array('Objet:objet/class/objet.class.php::filtre sql' => null))</code> exemple pour un lien vers les produits avec filtre sur un ef<span> </span>: <code>array('options' => array('Product:product/class/product.class.php::(e.another_extrafield:=:1)' => null))</code>  Comme on le voit dans l’exemple ci-dessus, la table des ef de l’objet est identifiée comme <code>e</code>, alors que pour sellist/chkbxlst, ce sera <code>extra</code> !

=====duration=====
type int en bdd, longueur 11. Durée en seconde ?

=====point, multipts, linestrg, polygon=====
données géométriques dont j’ignore l’usage dans Dolibarr, respectivement typées point, multipoint, linstring, polygon, pas de taille. Aucune idée de paramètres qui seraient pertinents (je soupçonne pas de paramètres du tout)

=====html=====
type text en bdd, pas de param

=====password=====
type varchar et taille 128 en bdd, pas de param

=====stars=====
pour attribuer des notes. Type varchar et taille 128 en bdd, pas de param, mais nécessite en taille le nombre d’étoiles !

=====autre valeur=====
doit correspondre à un type de champ reconnu par la base de données. Si on met varchar, la taille sera de 255 si non précisée par ailleurs

====Attribut alwayeditable====
Si positionné à 1, rend les champs non modifiables sur un objet validé. '''NE PAS METTRE 1 SUR UN PRODUIT''', le champ devient non modifiable, puisque le produit n’a pas de statut brouillon.

====Attributs perms et enabled====
Les permissions utilisateurs  pour voir et modifier l’ef (perms) et l’activation ou non de l’ef (enabled). La condition doit être une chaîne de caractère qui sera interprétée lors de l’affichage. Attention à l’imbrication des quotes<span> </span>: <code>'$user->hasRight("product", "creer")'</code> ou <code>'$user->hasRight(\'product\', \'creer\')'</code>, mais pas <code>'$user->hasRight('product', 'creer')'</code>

Si la valeur perms n’est pas précisée, ce sont les droits sur l’objet qui s’appliquent.

====Attribut entity====
Contrairement aux précédents, ce n’est pas la chaîne mais bien la variable <code>$conf->entity</code> qui doit être appelée, permettant à l’ef d’être créé pour chaque entité dans la table des extrafields

====Attribut list====
Détermine la visibilité<span> </span>:

0 => Jamais visible

1 => Visible sur les listes et les formulaires créer/mettre à jour/afficher

2 => Visible sur les listes uniquement

3 => Visible sur les formulaires créer/mettre à jour/afficher uniquement (pas les listes)

4 => Visible sur les listes et formulaires de

mise à jour/affichage uniquement (pas en création)

5 => Visible sur la liste et le formulaire de consultation uniquement (pas en création, pas en mise à jour).

L'utilisation d'une valeur négative signifie que le champ n'est pas affiché par défaut sur la liste mais peut être sélectionné pour la visualisation).

On peut utiliser des conditions pour la valeur<span> </span>:

<code>'preg_match("/public/", $_SERVER["PHP_SELF"]) ? 0<span> </span>: 1'</code> (si l’url de la page contient /public, on n’affiche jamais le champ, sinon on l’affiche toujours. Utile pour des tickets, par exemple)

<code>'$user->hasRight("holiday", "define_holiday") ? 1<span> </span>: 5'</code> (si l’utilisateur a les droits sur la création de jours fériés, on l’affiche en tout contexte, sinon uniquement en lecture)

Là encore, attention aux imbrications de quotes.

===Mise à jour===
Depuis Dolibarr 20, on dispose dans la class <code>Extrafields</code> d’une méthode <code>updateExtrafield()</code> qui permet de mettre à jour la définition d’un extrafield ''avec les mêmes paramètres dans le même ordre que la méthode <code>createExtrafields()</code> ci-dessus.'' Les méthodes historiques ''<code>update()</code>'' (pour la table des ''extrafields'') et ''<code>update_label()</code>'' (pour la table des ef de l’objet) existent toujours (et sont appelées par <code>createExtrafields()</code>) mais les paramètres ne sont pas dans le même ordre, ce qui n’est pas follement pratique !