- Definition
- A complex case study
Definition
Parameters are used for:
- general configuration parameters
- site configuration parameters
- content type metadata
- service parameters
- view parameters
Whatever its use, a parameter is defined by :
- a unique identifier
- a type: string, long, date, ...
- a wording
- a description
- a default value (optional)
- a widget (optional)
- one or more validation rules (optional)
- a list of enumerated values (optional)
A complex case study
To illustrate parameters, here's a complex case of parameter declaration.
A parameter is declared in a plugin.xml in accordance with the following diagram XML :
Example of a parameter declaration
<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> <default-value>en</default-value> <widget>sorted-multiselect</widget> <validation> <mandatory/> </validation> </param>
The declaration of a parameter may differ slightly depending on the use case (metadata, configuration parameter, service parameter, etc.).
Go to the parameter page corresponding to your use case to find out the exact declaration.
Wording and description
Every parameter has a label and a description. The description is used as an input aid.
The label and description can be keyed i18n (internationalization) or not. Use the i18n attribute to internationalize or not the parameter.
Ex: Internationalized label and description
<label i18n="true">plugin.web:PLUGINS_WEB_PARAM_LANG</label> <description i18n="true">plugin.web:PLUGINS_WEB_PARAM_LANG_DESC</description>
Ex: Non-internationalized label and description
<label i18n="false">Langues</label> <description i18n="true">Sélectionnez une ou une plusieurs langues</description>
If you wish to internationalize these labels, then a i18n catalog must exist:
- or it is associated directly with the configuration file
- or specify the skin catalog: skin.[nom_skin]:I18n_KEY
- or specify plugin: plugin.[nom_plugin]:I18n_KEY
Please see the Internationalization page for more details.
The types
The type of a parameter defines its storage format.
7 types are supported, listed below.
| Type | Description |
|---|---|
| string | Simple text |
| long | Whole number |
| double | Decimal number |
| date | Date |
| binary | Binary file |
| boolean | Boolean value (true or false) |
| password | Password |
For example, for content type metadata, the "rich-text" type for rich fields and the "composite" type are also supported. Go to the parameter page corresponding to your use case for the exact list of supported types.
Enumerations
The possible values for a parameter can be restricted to a list of values = enumeration. In this case, the value is selected from a drop-down list.
To define an enumeration, use the <enumeration>.
Static enumeration
The list of values for a static enumeration is declared directly in the parameter declaration.
Static enumeration declaration: 4 possible values
<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> corresponds to the stored value
- <label> corresponds to the displayed value
Dynamic enumeration
You can define your own Java class for more complex enumeration purposes, such as reading possible values from an external XML configuration file.
The Java class must implement the org.ametys.runtime.util.parameter.Enumerator
Example of enumeration in 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> to make the parameter mandatory
- <regexp> to define a regular expression
- <invalidText> to personalize the message in the event of incorrect input (regular expression not respected)
- <custom-validator> java class implementing the org.ametys.runtime.util.parameter.Validator to define your own validator
-
For example org.ametys.runtime.plugins.core.util.parameter.TextValidator or org.ametys.runtime.plugins.core.util.parameter.RichTextValidator support a sub-tag
- <maxlength> for a maximum number of supported characters
-
Here are a few examples.
Validation of a mandatory " mail address" field
Declaration
<validation> <custom-validator class="org.ametys.runtime.plugins.core.util.parameter.TextValidator"> <maxlength>60</maxlength> </custom-validator> <mandatory/> <regexp>^.+@.+$</regexp> <invalidText i18n="true">PLUGINS_WEB_REGEXP_INVALID_MAIL</invalidText> </validation>
Validation of a text field, mandatory, with a maximum of 200 characters
Declaration
<validation> <custom-validator class="org.ametys.runtime.plugins.core.util.parameter.TextValidator"> <mandatory /> <maxlength>200</maxlength> </custom-validator> </validation>
The validator TextValidator accepts parameters <mandatory>, <regexp>, <invalidText> and <maxlength> for the maximum number of characters allowed.
In editing mode, the text zone is limited to 200 characters. A counter displays the number of characters entered vs. the number of characters allowed.
Validation of a mandatory rich field with a maximum of 800 characters
Declaration
<validation> <custom-validator class="org.ametys.runtime.plugins.core.util.parameter.RichTextValidator"> <mandatory /> <maxlength>800</maxlength> </custom-validator> </validation>
The validator RichTextValidator accepts parameters <mandatory>, <regexp>, <invalidText> and <maxlength> for the maximum number of characters allowed.
In editing mode, if the maximum number of characters is exceeded, the character counter turns red. It will not be possible to validate the form until the number of characters has been respected.
Editing widgets
A parameter can use a "widget"for modification. A widget is an advanced form field, used as an input aid.
For example,
- a "string" parameter can use widget "textarea" to edit the parameter on several lines.
- an enumeration can use the widget "sorted-multiselect" to allow multiple selection where values are sorted alphabetically.
The widget tag is used for this purpose. <widget> :
<param name="description" type="string"> <label i18n="true">PARAM_DESCRIPTION_LABEL</label> <description i18n="true">PARAM_DESCRIPTION_DESC</description> <widget>textarea</widget> </param>
By default, each type (string, data, long, ...) has its own widget (e.g. a calendar for date).
Go to the parameter page corresponding to your use case for the exact list of supported widgets.
Here is the list of widgets used by default for each type of parameter
| Type | Widget | Rendering |
|---|---|---|
| string | Text field or drop-down list for enumerations |
|
| date | Calendar |  |
| long | Text field accepting integers only |  |
| double | Text field accepting only integers or decimal numbers |  |
| boolean | Check box |  |
| password | Double field for password confirmation |
|
| binary | File" field for selecting a file on the disk |
Default values
A parameter can have a default value.
In the case of multiple parameters, it is possible to enter several default values (see complex case).
If the parameter defines an enumeration, the default values must be among those proposed by the enumeration. For example, in the complex case, the enumeration proposes the 4 values fr, en, es and de; the default values are fr and en.
Example:
<param name="List" type="string"> <label i18n="true">PARAM_LIST_LABEL</label> <description i18n="true">PARAM_LIST_DESC</description> <widget>edition.boxselect</widget> <enumeration> <entry> <label>fr</label> <value>fr</value> </entry> <entry> <label>en</label> <value>en</value> </entry> <entry> <label>es</label> <value>es</value> </entry> <entry> <label>de</label> <value>de</value> </entry> </enumeration> <default-value>fr</default-value> <default-value>en</default-value> </param>
The default values of a parameter can also take the value of a configuration parameter. To do this, enter the "config" type and the configuration parameter identifier. The parameter type must correspond to the type of configuration parameter used.
Example with the value of a configuration parameter :
<param name="privacy" type="boolean"> <label i18n="true">PARAM_PRIVACY_LABEL</label> <description i18n="true">PARAM_PRIVACY_DESC</description> <default-value type="config">runtime.ametys.public</default-value> </param>
Back to top