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 |
