Généralités sur les paramètres

Définition
Illustration par un cas complexe

Définition

Les paramètres sont utilisées pour:

les paramètres de configuration générales
les paramètres de configuration de site
les métadonnées d'un type de contenu
les paramètres de services

Quelque soit son utilisation, un paramètre est définit par :

un identifiant unique
un type : string, long, date, ...
un libellé
une description
une valeur par défaut (optionnelle)
un widget (optionnel)
une ou des règles de validation (optionnelles)
une liste de valeurs énumérée (optionnelle)

Illustration par un cas complexe

Pour illustrer les paramètres, voici ci-après un cas complexe de déclaration d'un paramètre.

La déclaration d'un paramètre se fait dans un fichier plugin.xml en respectant le schema XML suivant:

Exemple de déclaration d'un paramètre

<param id="languages" type="string" multiple="true">
    <label i18n="true">PLUGINS_WEB_PARAM_LANG</label>
    <description i18n="true">PLUGINS_WEB_PARAM_LANG_DESC</description>    
    <enumeration>
        <entry>
            <label i18n="true">PLUGINS_WEB_PARAM_LANG_FR</label>
            <value>fr</value>
        </entry>
        <entry>
            <label i18n="true">PLUGINS_WEB_PARAM_LANG_EN</label>
            <value>en</value>
        </entry>
        <entry>
            <label i18n="true">PLUGINS_WEB_PARAM_LANG_ES</label>
            <value>es</value>
        </entry>
		<entry>
            <label i18n="true">PLUGINS_WEB_PARAM_LANG_DE</label>
            <value>de</value>
        </entry>	
	</enumeration>
    <default-value>fr</default-value>
    <widget>sorted-multiselect</widget>
    <validation>
        <mandatory/>
    </validation>
</param>

La déclaration d'un paramètre peut différée quelque peu suivant le cas d'utilisation (métadonnée, paramètre de configuration, paramètre de service, ...).
Rendez-vous sur la page du paramètre correspondant à votre cas d'utilisation pour connaitre la déclaration exacte.

Libellé et description

Tout paramètre possède un libellé et une description. La description est utilisée pour l'aide à la saisie.

Le libellé et la description peuvent être des clés i18n (internationalisation) ou non. Utilisez l'attribut i18n pour internationalisé ou non le paramètre.

Ex: Libellé et description internationalisés

<label i18n="true">plugin.web:PLUGINS_WEB_PARAM_LANG</label>
<description i18n="true">plugin.web:PLUGINS_WEB_PARAM_LANG_DESC</description>

Ex: Libellé et description non internationalisés

<label i18n="false">Langues</label>
<description i18n="true">Sélectionnez une ou une plusieurs langues</description>

Si vous souhaitez internationaliser ces libellés, alors un catalogue i18n doit exister :

soit il est associé directement au fichier de configuration
soit vous devez préciser le catalogue de skin : skin.[nom_skin]:I18n_KEY
soit vous devez préciser le plugin: plugin.[nom_plugin]:I18n_KEY

Veuillez consulter la page Internationalisation pour plus de détails.

Les types

Le type d'un paramètre définit son format de stockage.

7 types sont supportés, listés ci-dessous.

Type	Description
string	Texte simple
long	Nombre entier
double	Nombre décimal
date	Date
binary	Fichier binaire
boolean	Valeur booléenne (true ou false)
password	Mot de passe

Par exemple, pour les métadonnées de type de contenus, le type "rich-text" pour les champs riches et le type "composite" sont également supportés.Rendez-vous sur la page du paramètre correspondant à votre cas d'utilisation pour connaitre la liste exacte des types supportés.

Les énumérations

Les valeurs possibles pour un paramètre peuvent être restreintes à une liste de valeurs = énumération. Dans ce cas le choix de la valeur se fera dans une liste déroulante.

Pour définir une énumération, il faut utiliser la balise <enumeration>.

Énumération statique

La liste des valeurs d'une énumération statique se déclare directement dans la déclaration du paramètre.

Déclarartion d'une énumération statique : 4 valeurs possibles

<enumeration>
	<entry>
        <value>fr</value>
    	<label i18n="true">PLUGINS_WEB_PARAM_LANG_FR</label>
    </entry>
	<entry>
        <value>en</value>
    	<label i18n="true">PLUGINS_WEB_PARAM_LANG_EN</label>
    </entry>
	<entry>
        <value>es</value>
    	<label i18n="true">PLUGINS_WEB_PARAM_LANG_ES</label>
    </entry>
	<entry>
        <value>de</value>
    	<label i18n="true">PLUGINS_WEB_PARAM_LANG_DE</label>
	</entry>	
</enumeration>

<value> correspond à la valeur stockée
<label> correspond à la valeur affichée

Énumération dynamique

Il est possible de définir sa propre classe Java pour une énumération à fin de traitements plus complexe, comme par exemple la lecture des valeurs possibles dans un fichier XML de configuration externe.

La classe Java doit implémenter l'interface org.ametys.runtime.util.parameter.Enumerator

Exemple d'énumératione en Java

<enumeration>
	<custom-enumerator class="org.ametys.cms.contenttype.ContentTypeEnumerator"/>
</enumeration>

Validation

Le tag <validation> permet de définir des règles de validation sur le paramètre

<mandatory> pour rendre la paramètre obligatoire
<regexp> pour définir une expression régulière
<invalidText> pour personnaliser le message en cas de saisie incorrecte (expression régulière non respectée)
<custom-validator> classe java implémentant l'interface org.ametys.runtime.util.parameter.Validator pour définir son propre validateur
- Par exemple org.ametys.runtime.plugins.core.util.parameter.TextValidator ou org.ametys.runtime.plugins.core.util.parameter.RichTextValidator supportent une sous balise
  - <maxlength> pour un nombre de caractères maximums supportés

Voici quelques exemples.

Validation d'un champ "adresse mail" obligatoire

Déclaration

<validation>
	<custom-validator class="org.ametys.runtime.plugins.core.util.parameter.TextValidator"> 
       <maxlength>60</maxlength>
    </custom-validator>
    <mandatory/>
    <regexp>^(\w+)([\-+.][\w]+)*@(\w[\-\w]*\.){1,5}([A-Za-z0-9][A-Za-z0-9]+)$</regexp>
	<invalidText i18n="true">PLUGINS_WEB_REGEXP_INVALID_MAIL</invalidText>
</validation>

Validation d'un champ texte, obligatoire, avec un maximum de 200 caractères

Déclaration

<validation>
    <custom-validator class="org.ametys.runtime.plugins.core.util.parameter.TextValidator">
         <mandatory />
         <maxlength>200</maxlength>
    </custom-validator>
</validation>

Le validateur TextValidator accepte les paramètres <mandatory>, <regexp>, <invalidText> et <maxlength> pour le nombre maximum de caractères autorisés.

En édition, le remplissage de la zone de texte est bloquée à 200 caractères. Un compteur affiche le nombre de caractères saisis vs le nombre de caractères autorisés.

Validation d'un champ riche obligatoire avec un maximun de 800 caractères

Déclaration

<validation>
    <custom-validator class="org.ametys.runtime.plugins.core.util.parameter.RichTextValidator">
         <mandatory />
         <maxlength>800</maxlength>
    </custom-validator>
</validation>

Le validateur RichTextValidator accepte les paramètres <mandatory>, <regexp>, <invalidText> et <maxlength> pour le nombre maximum de caractères autorisés.

En édition, si le nombre de caractères maximum est dépassé, le compteur de caractère passe en rouge. Il ne sera pas possible de valider le formulaire tant que le nombre de caractères n'est pas respecté.

Les widgets d'édition

Un paramètre peut utiliser un "widget" en édition. Un widget est un champ de formulaire avancé, constituant une aide à la saisie

Par exemples,

un paramètre de type "string" peut utiliser le widget "textarea" pour éditer le paramètre sur plusieurs lignes.
une énumération peut utiliser le widget "sorted-multiselect" pour permettre une sélection multiple où les valeurs seront triées par ordre alphabétiques

L'utilisation d'un widget se fait au travers de la balise <widget> :

<param name="description" type="string">
 	<label i18n="true">PARAM_DESCRIPTION_LABEL</label>
    <description i18n="true">PARAM_DESCRIPTION_DESC</description>
    <widget>textarea</widget>
</param>

Par défaut chaque type (string, data, long, ..) possède un widget adapté (ex: un calendrier pour date)

Rendez-vous sur la page du paramètre correspondant à votre cas d'utilisation pour connaitre la liste exacte des widgets supportés.

Voici la liste des widgets utilisés par défaut pour chaque type de paramètres

Type	Widget	Rendu
string	Champ texte ou liste déroulante pour les énumérations
date	Calendrier
long	Champ texte n'acceptant que les entiers
double	Champ texte n'acceptant que les entiers ou des nombres décimals
boolean	Case à cocher
password	Champ doublé pour confirmer le mot de passe
binary	Champ de type "file" permettant de sélectionner un fichier sur son disque