Extension:Page Forms/Input types/fr

Cette page couvre les différents types d'entrées possibles pour Page Forms, ainsi que les paramètres et les autres adaptations qu'il est possible de leur appliquer.

text
Type d'entrée par défaut; correspond à l'entrée text de HTML.

Paramètres spéciaux :
 * size - Indique la largeur de la saisie, en nombre de caractères.
 * maximum length - Indique la longueur maximale autorisée pour l'entrée.
 * placeholder text - Indique le texte d'aide affiché à l'entrée jusqu'à ce que l'utilisateur clique dessus.

textarea
Correspond à la balise HTML.

Paramètres spéciaux :
 * num rows - Indique le nombre de rangées.
 * num cols - Indique le nombre de colonnes.
 * maximum length - Indique la longueur maximale autorisée pour l'entrée.
 * - Définit la zone de texte comme redimensionnable automatiquement en hauteur, afin de recevoir le contenu entier sans avoir besoin d'ascenseur.
 * editor type - Ajoute un éditeur basé sur JavaScript à la zone de texte pour faciliter l'édition de son contenu. Les valeurs suivantes sont prises en charge :
 * - utilise l'extension qui doit être installée. Malheureusement, à cause d'une limitation dans l'extension WikiEditor, une seule entrée du formulaire peut être associée à WikiEditor. Si vous voulez ajouter tout  à WikiEditor, vous devez les ajouter dans le JavaScript à , comme ils existent pour.
 * - utilise l'extension qui doit être installée.
 * - utilise l'extension qui doit être installée. Une autre extension  doit aussi être installée. Si vous souhaitez que la barre d'outils s'affiche en haut du champ d'édition plutôt qu'en bas (par défaut), vous devrez également ajouter


 * maximum height - Si VisualEditor est utilisé, cela indique une hauteur maximum (en pixels) pour la zone de texte, car VisualEditor utilise autgrow. Par défaut, cette valeur est de 400.
 * placeholder text - Indique le texte d'aide affiché à l'entrée jusqu'à ce que l'utilisateur clique dessus.

text et textarea avec autocomplétion
Ces deux entrées sont affichées de la même manière que les types d'entrée  et , et ils peuvent être configurés de la même manière, mais ils fournissent aussi l'autocomplétion - aucune ou plusieurs valeurs. Voir les sections sur l' initialisation des paramètres et l' autocomplétion ci-dessous sur la manière de personnaliser l'autocomplétion.

combobox
Le type d'entrée combobox fournit une interface de style liste déroulante : une entrée qui fonctionne comme un champ régulier avec autocomplétion, mais avec une icône supplémentaire de flèche vers le bas, comme celle d'un dérouleur, pour permettre à l'utilisateur de voir d'un seul coup toutes les valeurs possibles. Il est implémenté en utilisant la bibliothèque JavaScript Select2.

Paramètres spéciaux :


 * size - Indique la largeur de la saisie, en nombre de caractères.
 * - Refuse les valeurs arbitraires dans le champ.
 * placeholder text - Indique le texte d'aide affiché à l'entrée jusqu'à ce que l'utilisateur clique dessus.
 * namespace - Préfixe la valeur sélectionnée en ajoutant l'espace de noms spécifié.

tokens
Ce type d'entrée réalise le marquage des valeurs du champ en plaçant chacune d'elles dans un bloc (un token) pour en faire autant d'unités séparées au lieu d'une chaîne de caractères. Ces jetons peuvent ensuite être réarrangés. Comme pour combobox, cette entrée est implémentée en utilisant la bibliothèque JavaScript Select2.

Paramètres spéciaux :


 * size - Indique la largeur de la saisie, en nombre de caractères.
 * max values - Indique le nombre maximum de valeurs autorisées.
 * - Refuse les valeurs arbitraires dans le champ.
 * placeholder text - Indique le texte d'aide affiché à l'entrée jusqu'à ce que l'utilisateur clique dessus.
 * namespace - Préfixe chaque valeur sélectionnée en ajoutant l'espace de noms spécifié.

Par défaut, les tokens apparaissent comme une entrée sur une seule ligne et sont listés verticalement si nécessaire, au fur et à mesure que des valeurs supplémentaires sont ajoutées. Dans certains cas vous voudrez que cette entrée apparaisse plus grande qu'une rangée lorsqu'elle commence, afin qu'elle soit plus évidente pour les utilisateurs qui voudront la dérouler. Pour faire cela avec une entrée unique, ajoutez un paramètre  à la balise du champ, tel que , puis ajoutez à MediaWiki:Common.css quelque chose similaire à :

Si vous voulez que cela s'applique à toutes les entrées tokens du wiki, ajoutez à MediaWiki:Common.css quelque chose similaire à :

radiobutton
L'entrée radiobutton correspond aux boutons radio du HTML. Elle affiche un ensemble de valeurs parmi lesquelles l'utilisateur ne peut en choisir qu'une.

Par défaut, la valeur du premier bouton radio est None, permettant ainsi à l'utilisateur de choisir la valeur vide. Pour empêcher d'afficher « None », vous devez indiquer que le champ est « mandatory », et choisir une des valeurs autorisées en tant que valeur par défaut dans le champ « default= ».

dropdown
L'entrée dropdown correspond à la balise HTML &lt;select&gt;. Elle affiche une liste déroulante de valeurs, parmi lesquelles l'utilisateur ne peut en sélectionner qu'une.

checkboxes
Les entrées checkboxes affichent des cases à cocher permettant à l'utilisateur de choisir tout nombre de valeurs. S'il y a plus qu'un nombre donné de cases à cocher, les liens « Selectionner tous » et « Selectionner aucun » vont automatiquement apparaître au-dessus de l'ensemble des cases, pour permettre automatiquement aux utilisateurs de les cocher toutes ou aucune. Ce nombre est fixé par la variable, dont la valeur par défaut est 10, bien qu'elle puisse être changée dans LocalSettings.php.

Paramètres spéciaux :


 * - masquer les liens « Selectionner tous » et « Selectionner aucun » pour cette entrée, quelque soit le nombre de valeurs
 * - afficher les liens « Selectionner tous » et « Selectionner aucun » pour cette entrée, quelque soit le nombre de valeurs

listbox
L'entrée listbox correspond à la balise HTML &lt;select&gt;, avec l'attribut with the « multiple » ajouté. Cela affiche une liste verticale d'options, dans laquelle l'utilisateur peut faire une sélection multiple.

Paramètres spéciaux :


 * size - Indique la hauteur de la listbox.

tree
Le type d'entrée tree accepte des données hiérarchiques présentées sous forme d'arbre, où toutes les valeurs ont soit des boutons radio soit des cases à cocher à leur côté, en fonction du champ qui est soit multiple, soit mono élément. Les valeurs peuvent provenir d'un arbre des catégories du wiki, ou être déclarées manuellement dans la définition du formulaire.

Comment cette entrée sait-elle qu'elle peut accepter une ou plusieurs valeurs et avoir des boutons radio ou bien des cases à cocher ? Elle regarde simplement si le champ dans le modèle est défini comme supportant une liste de valeurs (en utilisant #arraymap) ou pas. Ce contrôle n'est pas parfait, quoique. Si l'entrée tree affiche des boutons radio au lieu de cases à cocher, ajoutez simplement le paramètre « |list » à la balise du champ dans la définition du formulaire, pour déclarer la liste.

En fonction de la source des valeurs, vous devez spécifier l'un de ces deux paramètres supplémentaires.


 * - définit le nom de la catégorie qui se trouve à la racine de l'arbre.
 * - déclare la structure complète de l'arbre; vous devez utiliser les puces de style wikicode pour définir le niveau de profondeur.

Le paramètre structure vous permet d'obtenir l'équivalent de ceci :

Vous pouvez également initialiser les paramètres facultatifs suivants :


 * - définit la hauteur de la boîte en pixels, dans laquelle l'arborescence est affichée
 * - définit la largeur de la boîte en pixels, dans laquelle l'arborescence est affichée
 * - définit le délimiteur utilisé quand le champ contient une liste de valeurs. Par défaut une virgule ','.
 * - cache le nom de la catégorie de la racine.
 * - définit le nombre de niveaux de l'arborescence affichés au début. Par défaut 10.

Vous pouvez voir un formulaire d'exemple utilisant ce type d'entrée ici.

Pour les noms de catégorie
Si vous utilisez le type d'entrée « tree » pour afficher une arborescence de catégorie, notez que cette entrée va afficher uniquement les noms des catégories sélectionnées mais sans le préfixe de l'espace de noms Category: ; donc si vous voulez qu'il s'affiche aussi sur la page, le modèle devra l'ajouter.

Si le champ spécifie plusieurs catégories, et que le modèle utilise #arraymap pour le proposer, l'appel à #arraymap devrait ressembler à :

...en d'autres termes, vous devez spécifier le paramètre « delimiter » final pour #arraymap, et en faire un espace, un blanc ou quelque chose de similaire, pour éviter d'imprimer, les virgules entre les balises des catégories.

checkbox
Une case à cocher unique, utilisée pour les valeurs booléennes.

Paramètres spéciaux :


 * - permet d'attribuer un libellé à la checkbox, qui sera placé dans une balise &lt;label&gt;.

date
Cette entrée contient trois éléments séparés, pour l'année, le mois et le jour.

datetime
L'entrée « datetime » est similaire à l'entrée « date » mais inclut des entrées supplémentaires pour les heures, les minutes, les secondes et l'indication AM/PM.

Paramètres spéciaux :


 * - indique qu'une entrée de fuseau horaire doit aussi être incluse.

year
year est le texte qui représente seulement l'année dans le champ d'une date.

datepicker
« datepicker » permet à l'utilisateur de choisir une date avec l'aide d'une fenêtre séparée comportant un calendrier basé sur JavaScript. Cette entrée possède plusieurs paramètres optionnels; voir la liste complète ici.

datetimepicker
« datetimepicker » est un type d'entrée basé sur Javascript très similaire à « datepicker » et contenant des fenêtres pour sélectionner à la fois la date et l'heure. Par défaut. Ses paramètres sont tous ceux de « datepicker » plus les suivants :


 * - heure minimale autorisée
 * - heure maximale autorisée
 * - intervalle (en minutes) entre les options affichées à l'utilisateur

rating
Le type d'entrée « rating » affiche un ensemble d'étoiles pour permettre à l'utilisateur de formuler une évaluation.

Paramètres spéciaux :


 * - indique la largeur (et la hauteur) de chaque étoile. Par défaut 24 pixels.
 * - indique le nombre d'étoiles à afficher. Par défaut 5.
 * - permet aux utilisateurs de sélectionner une demi-étoile. Par défaut false ; fixer à   (ou tout autre valeur) pour le mettre à true.

googlemaps, leaflet, openlayers
The "googlemaps", "leaflet" and "openlayers" input types let you display a map to get a coordinate value, using the Google Maps, Leaflet or OpenLayers services, respectively.

If you are using the "googlemaps" input, you may need to get a Google Maps API key, then set it in LocalSettings.php via the  setting, for the input to display.

You can also optionally set these parameters for these input types:


 * - sets the height, in pixels, of the map.
 * - sets the width, in pixels, of the map.
 * - takes in a pair of coordinates to set the bounds of the map displayed; this parameter only applies if the input does not have a value. (Example value for this parameter: "-20,-15;50,55".)

The "leaflet" input type allows one additional parameter:


 * - sets the specified image (which must be an image that was uploaded to the wiki) as the background for the map, instead of a geographical map.

The "googlemaps" input lets you enter an address to locate the coordinates more easily. But if the form already contains one or more fields to enter the address, then the user may have to enter it twice - once to actually store the data, and the second to locate the coordinates. To avoid users having to do this double work, you can have the address field(s) feed their values directly to the map when locating the point. You can do that using the "feeds to map=" parameter - look for "feeds to map" here.

All of these formats, by default, rely on external JavaScript code. However, you can have the "openlayers" format use local JavaScript code instead, by just installing the OpenLayers extension.

Disabling
Notez bien que tous ces types d'entrée envoient les données de votre wiki (c'est à dire les données qui sont le résultat des requêtes), aux services externes. Ce sont les seules parties de code de Page Forms qui envoient les données à l'extérieur, autres que l'autocomplétion sur des valeurs externes, bien que cette dernière demande une configuration supplémentaire pour fonctionner. Si vous avez un wiki privé et que vous êtes très préoccupé de ne pas voir vos données s'extérioriser, vous pouvez ajouter le code suivant dans LocalSettings.php :

Ceci va bloquer l'utilisation de tout service externe par Page Forms - ce qui à cet instant signifie interdire ces trois types d'entrée.

regexp
Le type d'entrée regexp n'est pas réellement un type d'entrée, mais plutôt la possiblité d'afficher l'entrée réelle (le plus souvent de type text) en appliquant une validation supplémentaire basée sur une expression régulière. Voir ici l'explication plus détaillée de ce type d'entrée et de ses paramètres.

Allowed input types for data types
Each defined data type, when using either Cargo or Semantic MediaWiki, has a default input type, and, when applicable, a default input size as well. Additionally, some data types have special handling if the field holds a delimited list of values, instead of just a single value.

Here are the defaults and the other allowed input types for each data type, for single values:

And here are the default and other allowed input types for delimited lists of a certain data type:

Setting values and mappings
Some input types provide the user with pre-defined values. These can be values that the user is required to choose among (like with the  input type), or values that are only meant to serve as a guide to the user (like with , although there too these options can be made mandatory, if you add the   parameter).

For both cases, the set of parameters for specifying the values shown to the user is nearly the same. Here are the parameters for the "field" tag that can be used in all cases:
 * +  – If you have Cargo installed on the wiki, this set of parameters will be automatically used if the input type uses autocompletion, like   does. The code will find the Cargo table and field that this template/form field corresponds to, and use all the values that have been set for that field. Or you can use these parameters to specify any combination of table and field you want.
 * – If you have Semantic MediaWiki installed, this parameter will be automatically used if the input type uses autocompletion. The code will find the relevant property and use all of its values, or you can use this parameter to specify a different property.
 * – Functionally, this parameter works the same as, above, though it lacks some of the side effects:   can also impact the size and even input type of the field.
 * – Gets its values from the names of all pages belonging to a specific category.
 * – Gets its values from the names of all pages belonging to one or more specific namespaces. To get values from more than one namespace, separate the names with commas. To get values from the main namespace, use "Main", or just leave it blank.
 * – Gets its values from the names of all pages belonging to a specific SMW concept.
 * – Finally, you can simply manually specify the set of values shown to the user; an example would be . This set of values should be separated by commas by default, but the delimiter can be modified using the   parameter.

There are several more options for the autocompletion-based inputs; see "Autocompletion", below.

Mapping
You can have the set of values displayed to the user be different from the set of values that actually show up in the page's wikitext. If the values are page names, and those pages have a "display title" set that is different from their real page name, then by default the form will display the display title instead of the page name. If you want, you can have the page name itself displayed, by adding the following to LocalSettings.php:

You can enable other such mappings using the following parameters:


 * template name - Takes in the name of a "mapping template" (a template that takes in a single, unnamed parameter, i.e., and displays a "mapped" string as a result), and uses that template to map every potential value, so that the values' "aliases" appear on the screen, and not the values themselves.
 * property name - Used for fields that select pages with 'combobox', 'tokens', 'listbox', and 'dropdown' input types. For each possible value, displays a SMW property from that page rather than the title of the page, but saves the title of the selected page(s) as the field value. Used in conjunction with the  parameters to get the list of possible values.
 * table name/ field name - Similar to  except it is used for Cargo fields. Used in conjunction with ,  ,  , and  /.
 * - If the Translate extension is installed, calls Translate's magic word on each value to get the mapped value.

For example, a form could contain a field tag like this:

The template at Template:StatusLabel could then contain something like:

You could then use that same "mapping template" to display the label of the value on regular, non-form pages. Within the template that contains the field "status", you could have the following:

Autocomplétion
Four of the input types (, ,   and  ) use autocompletion — as the user starts typing, the input shows a dropdown list of possible completions.

Si un champ représente une propriété de Semantic Mediawiki, ou un champ Cargo, de type «  », l'autocomplétion sera activée par défaut — le champ se complétera automatiquement avec le nom de toutes les pages qui utilisent déjà cette propriété ou ce champ. For any other type, there is no default autocompletion, but you can achieve this same effect simply by setting the input type to one of the four types that have autocompletion.

You can manually set a field to autocomplete on the set of values from an SMW property, a Cargo field, a category, a namespace, a "concept", or a manually-set list, by using one of the "values ..." parameters - see "Setting values and mappings", above.

You can also autocomplete based on values outside the wiki, contained in web pages, databases, files, etc.; see "Autocompleting on outside values" below for the various ways to do this.

If a field is specified to hold multiple values, autocompletion will, by default, support multiple values: after a value is entered, and a delimiter placed, a new autocompletion will start for the next value. You can manually specify that a field should have multiple-value autocompletion, by adding the "list" parameter to the field's definition. You can also specify the delimiter for this list of values, using the "delimiter=..." parameter (the default is a comma).

By default, the maximum number of autocompletion possibilities that a field will offer is 1,000; this is for performance reasons. To change this number, change the value of  in LocalSettings.php.

Désactivation
You can disable autocompletion, if it's enabled by default for a field, by setting the input type to be simply "text" or "textarea".

Autocomplétion distante
The set of a field's possible values for autocompletion is, by default, contained right within the form's HTML page, in a JavaScript declaration. Par soucis de performance, il y existe une limite sur le nombre de valeurs placées sur la page; par défaut la limite est fixée à 100. After that number is reached, remote autocompletion is done instead, where autocompletion happens through an Ajax call to the server, based on what the user has typed. Ce type d'autocomplétion est plus lent, mais il permet beaucoup plus de résultats d'autocomplétion.

You can change the default by adding something like the following to LocalSettings.php:

Matching on every character
By default, Page Forms autocompletion matches on the beginning of every word in the set of possible values. However, you can change autocompletion to instead match on every character, by adding the following line to LocalSettings.php: This feature is especially important for wikis that have values with non-ASCII characters, such as wikis in languages with non-Roman alphabets; since the default, word-based autocompletion doesn't yet work with non-ASCII characters.

Autocompletion on characters with accents
Flexible autocompletion for characters with accents is supported by the combobox and tokens input type.

Accent-folding has its limitations but it can help make some important yet overlooked user interactions work better. An accent-folding function essentially maps Unicode characters to ASCII equivalents. With accent-folding, it doesn’t matter whether users search for cafe, café or even çåFé; the results will be the same.

Autocompleting on outside values
There are two ways to have a field autocomplete using data from outside the wiki - one is from a URL that takes in a substring and returns data in JSON format similar to JSON returned by MediaWiki API and the other is to use External Data extension to fetch data from some external/internal source.

From an outside URL
You can have a field autocomplete on values from outside the wiki,using the following parameter:
 * URL identifier

To do so, take the following steps:


 * 1) Create a page/web service that takes in a substring via the query string, and displays a set of completion values. Page Forms expects to get a JSON format response with a toplevel key of "pfautocomplete" and an array of objects with the "title" key marking the values of possible completions.  You can see a brief example of this from this API call on semantic-mediawiki.org.
 * For example, if you had a list of three countries -- Uruguay, Germany, and Japan -- and were asked for a list of possible completions for "an", you would return:
 * This also makes it easy to autocomplete on the values from another wiki.
 * 1) Decide on a short string to represent this URL.
 * For example, the service providing lookups in our list of countries could be called " ".
 * 1) Add the short string to the array in   in your LocalSettings.php to configure Page Forms to use your URL when it sees the string.  Put " " where you want the user's input will go.
 * In our example, if we want Page Forms to feed the user's keystrokes to the url  via the url parameter " ", we'd put:
 * 1) Add the parameter "values from url=URL-identifier-string" to the relevant field in the form definition.
 * For our country example, we might have a field that looks like
 * 1) Add the parameter "values from url=URL-identifier-string" to the relevant field in the form definition.
 * For our country example, we might have a field that looks like

Using the External Data extension


The External Data extension (ED) supports retrieving data from a number of sources which include external URLs, regular wiki pages, uploaded files, files on the local server, databases and LDAP directories.

To autocomplete using ED, you need to first call any of ED's "#get_..._data" parser functions within the form definition (preferably at the bottom of the form definition, to avoid unnecessary line breaks). This will fetch data that can then be used in the field tags. (See the External Data documentation for how to call these.) The field tag may then use these parameters:
 * ED variable name (mandatory)
 * ED variable name (optional)
 * ED variable name (optional)

Here is a sample call to #get_web_data to fetch data from some URL:

Assuming a form definition contains a call like that, a field tag can then use the values retrieved for autocompletion - not just to set the autocomplete values themselves, but also, if the input type is "combobox" or "tokens", to set a corresponding thumbnail image and description for each one.

Assuming our External Data call retrieved three "columns" of values, as the one above does, the field tag using this data could look like:

Dependent autocompletion
You can set a field's autocompletion values to be based on the value a user has already set of another field in the form. This is done with the parameter, which has this syntax:

{{{field ... |values dependent on= template name [ field name ]

It specifies that the current set of allowed values for this field are all the values taken by this same field from pages where 'field name' is equal to the value selected for 'field name' in the current form.

Is that confusing?

Well, this example may help: if a template is called "Restaurant" and it has template fields (not properties) named "Country" and "City", and you want the set of cities that are used for autocompletion to be only those cities in the country that the user selected, then the field tag for the City field should look something like:.

Uploading files
If a field in the form is meant to hold the name of an uploaded file (say, an image), you can allow users to upload this file directly through the form. This is done simply by adding the parameter "uploadable" to that field's declaration in the form definition. This will add a link reading "Upload file" next to this field in the form; if the user clicks on this link, it will pop up a "lightbox"-style window (using the FancyBox JavaScript library) that lets the user upload a file. Once the user has done so, the window will close, and the field will contain the name of the uploaded file. If the field is configured to contain a list of values, the new file name will be appended to whatever was there before; otherwise, the file name will overwrite whatever the field contained before.

Note that the "uploadable" parameter can only be used in fields of type "text", "text with autocomplete", "combobox" or "tokens".

For uploadable fields, you can also set the default filename of the uploaded files, by setting the "default filename=" parameter in the field definition. The value of this parameter can include parser functions, magic words and the like. It can also include the variable "&lt;page name>", which gets substituted with the name of the page being added or edited. So adding to the field definition the parameter "default filename=Image for &lt;page name>", for instance, for a page called "Abc", would set the default name of any uploaded file to "Image for Abc". Note that if you simply want to specify a default file to use such as "Imageneeded.png" the regular "default=Imageneeded.png" parameter will do.

You can see a demonstration of file uploading here.

Note that the upload window will not work if  is set to   in your LocalSettings.php.

You can also set uploadable fields to use the operating system's own uploading directly, instead of using MediaWiki's uploading system - this gives the user fewer options, but it is a simpler process, and on mobile devices it can present some interesting options, like uploading photos right after they are taken. To do this, add the following line to LocalSettings.php:

The special parameters for uploadable fields are:
 * - Specifies that this is an uploadable field.
 * - Specifies that a thumbnail of the uploaded image should be placed under the field in the form.
 * filename - Specifies the default filename for files uploaded with this field.

"show on select"
For inputs of type 'checkbox', 'checkboxes', 'radiobutton', 'dropdown' and 'listbox', the parameter  specifies that one or more elements on the page should only be displayed if and when certain value(s) are selected within that input.

The syntax for this parameter is:
 * value 1 element ID 1;value 2 element ID 2;value 3 element ID 3;etc.

A value can be provided with more than one element-id:
 * value A element ID 1;value B element ID 1;value B element ID 2;value C element ID 3;etc.

For inputs of type 'checkbox', simply " element ID" should be used. Note that the element IDs cannot contain spaces and/or multibyte characters and cannot start with a number.

For an example of this feature in use, see this form, and observe what happens when you select different values for the "Publication type" dropdown. You can see how that was implemented in this form definition.