Extension:Page Forms/Types d'entrées
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.
Les types d'entrées
text
Type d'entrée par défaut; correspond à l'entrée text de HTML.
Paramètres spéciaux :
size=taille
|
Indique la largeur de la saisie, en nombre de caractères. |
maxlength=longueur maximale
|
Indique la longueur maximale autorisée pour l'entrée. |
placeholder=texte à remplacer
|
Indique le texte d'aide affiché à l'entrée jusqu'à ce que l'utilisateur clique dessus. |
autocapitalize=valeur
|
le paramètre autocapitalize de la balise HTML correspondante est utilisé quelque soit sa valeur pour initialiser ce paramètre; les exemples incluent on, off, sentences, etc.
|
textarea
Correspond à la balise HTML <textarea>.
Paramètres spéciaux :
rows=nombre de rangées
|
Indique le nombre de rangées. |
cols=nombre de colonnes
|
Indique le nombre de colonnes. |
maxlength=longueur maximale
|
Indique la longueur maximale autorisée pour l'entrée. |
autogrow
|
Définit la zone de texte comme redimensionnable automatiquement en hauteur, afin de recevoir le contenu entier sans avoir besoin d'ascenseur. |
editor=type d'éditeur
|
Ajoute un éditeur basé sur JavaScript à la zone de texte pour faciliter l'édition de son contenu. Les valeurs suivantes sont prises en charge :
|
max height=hauteur maximale
|
Si VisualEditor est utilisé, cela indique une hauteur maximale (en pixels) de la zone de texte, car VisualEditor utilise autgrow. La valeur par défaut est définie par la variable $wgPageFormsVisualEditorMaxHeight qui vaut 400 par défaut.
|
placeholder=texte à remplacer
|
Indique le texte d'aide affiché à l'entrée jusqu'à ce que l'utilisateur clique dessus. |
text et textarea avec autocomplétion
C'était autrefois des types d'entrée réels, mais depuis la version 5.0 on en a fait des alias pour "combobox" et "tokens" (selon que l'entrée contient une liste de valeurs ou une seule).
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 OOUI.
Paramètres spéciaux :
size=taille
|
Indique la largeur de la saisie, en nombre de caractères. |
height=hauteur
|
Indique la hauteur de la combobox, en pixels. |
existing values only
|
Refuse les valeurs arbitraires dans le champ. |
placeholder=texte à remplacer
|
Indique le texte d'aide affiché à l'entrée jusqu'à ce que l'utilisateur clique dessus. |
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. Cette entrée est implémentée en utilisant la bibliothèque JavaScript Select2.
Paramètres spéciaux :
size=taille
|
Indique la largeur de la saisie, en nombre de caractères. |
max values=valeurs maximales
|
Indique le nombre maximum de valeurs autorisées. |
existing values only
|
Refuse les valeurs arbitraires dans le champ. |
placeholder=texte à remplacer
|
Indique le texte d'aide affiché à l'entrée jusqu'à ce que l'utilisateur clique dessus. |
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 class à la balise du champ, tel que |class=ClassName, puis ajoutez à MediaWiki:Common.css quelque chose similaire à :
.ClassName, .ClassName .select2-choices {
min-height:60px;
}
Si vous voulez que cela s'applique à toutes les entrées tokens du wiki, ajoutez à MediaWiki:Common.css quelque chose similaire à :
#pfForm .select2-container-multi .select2-choices {
min-height: 60px;
}
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 <select>. 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 $wgPageFormsCheckboxesSelectAllMinimum, dont la valeur par défaut est 10, bien qu'elle puisse être changée dans LocalSettings.php.
Paramètres spéciaux :
hide select all
|
masquer les liens « Selectionner tous » et « Selectionner aucun » pour cette entrée, quelque soit le nombre de valeurs |
show select all
|
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 <select> , avec l'attribut « multiple » ajouté. Cela affiche une liste verticale d'options, dans laquelle l'utilisateur peut faire une sélection multiple.
Paramètres spéciaux :
size=taille
|
Indique la hauteur de la listbox en tant que nombre de lignes affichées |
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.
top category=- définit le nom de la catégorie qui se trouve à la racine de l'arbre.structure=- 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 :
{{{field|Location|input type=tree|structure=*Universe
**Milky Way Galaxy
***Solar system
**Andromeda Galaxy
...etc.
}}}
Vous pouvez également initialiser les paramètres facultatifs suivants :
height=- définit la hauteur de la boîte en pixels, dans laquelle l'arborescence est affichéewidth=- définit la largeur de la boîte en pixels, dans laquelle l'arborescence est affichéedelimiter=- définit le délimiteur utilisé quand le champ contient une liste de valeurs. Par défaut une virgule ','.hideroot- cache le nom de la catégorie de la racine.depth=- 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 à :
{{#arraymap:{{{Categories|}}}|,|x|[[Category:x]] |<nowiki> </nowiki>}}
...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 :
label=
|
permet d'attribuer un libellé à la checkbox, qui sera placé dans une balise <label> . |
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 :
include timezone
|
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.
Special parameters:
date format=
|
définit un format de date personnalisé, utilisé uniquement pour le champ d'entrée. Un exemple serait DD-MM-YYYY.
|
first date=
|
définit la première date que l'utilisateur est autorisé à sélectionner. |
last date=
|
fixe la dernière date que l'utilisateur est autorisé à sélectionner. |
Le premier jour de la semaine (par exemple, samedi, dimanche ou lundi) est fixé en fonction de la langue du wiki; il ne peut malheureusement pas être fixé indépendamment de la langue. Si votre wiki est en anglais et que vous souhaitez que les semaines de l'entrée du calendrier commencent le lundi au lieu du dimanche (qui est la valeur par défaut), vous pouvez le faire en définissant la langue de votre wiki comme "en-gb" au lieu de "en".
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 aaaa/mm/jj hh:mn.
Ses paramètres sont tous ceux de « datepicker » plus les suivants :
mintime=
|
heure minimale autorisée |
maxtime=
|
heure maximale autorisée |
interval=
|
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 :
star width
|
indique la largeur (et la hauteur) de chaque étoile. Par défaut 24 pixels. |
num stars
|
indique le nombre d'étoiles à afficher. Par défaut 5. |
allow half stars
|
permet aux utilisateurs de sélectionner une demi-étoile. Par défaut false ; fixer à yes (ou tout autre valeur) pour le mettre à true.
|
googlemaps, leaflet, openlayers
Les types d'entrée « googlemaps » « leaflet » et « openlayers » vous permettent d'afficher une carte pour obtenir la valeur des coordonnées en utilisant respectivement les services Google Maps, Leaflet ou OpenLayers .
Si vous utilisez l'entrée googlemaps, vous aurez probablement besoin d'avoir une clé d'accès à l'API Google Maps, et la déclarer dans LocalSettings.php via le paramètre $wgPageFormsGoogleMapsKey , pour que l'entrée puisse s'afficher.
Vous pouvez aussi définir (facultatif) ces paramètres pour les types d'entrées suivants :
height=
|
définit la hauteur de la carte en pixels. |
width=
|
définit la largeur de la carte en pixels.
Il faut à la fois height et width pour définir la dimension.
|
starting bounds=
|
utilise une paire de coordonnées pour délimiter les limites de la carte à afficher ; ce paramètre ne s'applique seulement si l'entrée n'a pas de valeur; exemple de valeur pour ce paramètre : "-20,-15;50,55" . |
Le type d'entrée leaflet permet un paramètre supplémentaire :
image=
|
définit l'image spécifiée (qui doit avoir été téléversée sur le wiki) en tant qu'image de fond de la carte, plutôt qu'une carte géographique. |
Toutes les entrées de la carte vous permettent de saisir plus facilement une adresse dont vous souhaitez localiser les coordonnées.
Mais si le formulaire contient déjà un ou plusieurs champs pour entrer l'addresse, alors il est possible que l'utilisateur doive la rentrer deux fois - une fois pour enregistrer les données actuellement, et une seconde fois pour les localiser.
Pour éviter que les utilisateurs aient à faire ce double travail, il est possible de faire en sorte que tous les champs d'addresse fournissent leur valeur directement à la carte lorsque le point est recherché.
Vous pouvez faire cela en utilisant le paramètre feeds to map= - voir ici.
Tous ces formats par défaut, dépendent du code JavaScript externe. Néanmoins, simplement en installant l'extension OpenLayers, il est possible de faire que le format openlayers utilise du code JavaScript local.
Désactivation
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 :
$wgPageFormsDisableOutsideServices = true;
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.
Types d'entrée autorisés selon le type de données
Lorsque vous utilisez Cargo ou Semantic MediaWiki, chaque type de données défini possède un type d'entrée par défaut et également selon le cas, une longueur d'entrée par défaut. En plus, certains types de données sont gérés d'une manière particulière quand le champ contient une liste de valeurs délimitées au lieu d'une seule valeur.
Voici les types par défaut et les autres types d'entrée permis pour chaque type de données, et cela pour des valeurs seules :
| Type de donnée Cargo | Type de donnée SMW | Type d'entrée par défaut | Taille par défaut | Autres types d'entrée autorisés |
|---|---|---|---|---|
| Page | Page | combobox | 35 | text, dropdown, textarea, tree |
| String | N/A | text | 35 | combobox, textarea |
| Text | Text, Code | textarea | 5 x 30 | text |
| URL | URL | text | 100 | textarea |
| Integer, Float | Number | text | 10 | textarea |
| Date, Start date, End date | Date | date | datetime, year, datepicker | |
| Datetime, Start datetime, End datetime | N/A | datetime | datetimepicker, date, year | |
| Boolean | Boolean | checkbox | dropdown, radiobutton | |
| Coordinates | Geographic coordinate | openlayers | googlemaps, leaflet | |
| Rating | N/A | rating | ||
| Enumeration (tout champ Cargo avec une liste de valeurs autorisées) | Enumeration (toute propriété SMW avec des valeurs autorisées définies) | dropdown | radiobutton | |
| Hierarchy (tout champ Cargo avec un ensemble hiérarchique de valeurs autorisées) | N/A | tree |
Voici les types d'entrée par défaut et les autres types d'entrée autorisés pour les listes délimitées d'un type de donnée particulier :
| Type de donnée Cargo | Type de donnée SMW | Type d'entrée par défaut | Taille par défaut | Autres types d'entrée autorisés |
|---|---|---|---|---|
| Page | Page | tokens | 100 | text, textarea, tree, checkboxes |
| String | Text | text | 100 | textarea, tokens |
| Enumeration | Enumeration | checkboxes | listbox | |
| Hierarchy | N/A | tree |
Téléversement de fichiers
Si un champ du formulaire doit contenir le nom d'un fichier à téléverser (par exemple une image), vous pouvez permettre aux utilisateurs de faire le téléversement directement via le formulaire. Ceci se fait simplement en ajoutant le paramètre uploadable (téléversable) à la déclaration du champ dans la définition du formulaire. Ceci va ajouter dans le formulaire un lien de téléversement, à côté de ce champ; si l'utilisateur clique sur ce lien, une fenêtre de style « lightbox » va s'ouvrir (en utilisant la bibliothèque JavaScript) pour qu'il puisse téléverser le fichier. Une fois cela fait, la fenêtre se ferme et le champ contient le nom du fichier téléversé. Si le champ est configuré pour contenir une liste de valeurs, le nouveau nom de fichier sera ajouté à ce qu'il y avait déjà dans le champ; sinon le nom du fichier viendra remplacer ce contenu.
Notez que le paramètre uploadable ne peut être utilisé que dans les champs de type text, text avec autocomplétion, combobox et tokens.
Pour les champs avec téléversement, vous pouvez aussi définir le nom du fichier par défaut à téléverser, en initialisant le paramètre « default filename= » dans la définition du champ. La valeur de ce paramètre peut inclure des fonctions d'analyse syntaxique, des mots magiques et similaire. Il peut également inclure la variable <page name>, qui est substituée par le nom de la page devant être ajoutée ou modifiée. Donc en ajoutant à la définition du champ le paramètre default filename=Image for <page name>, par exemple pour la page Abc, vous initialisez le nom par défaut du fichier à téléverser à Image for Abc. Notez que si vous voulez simplement spécifier un fichier par défaut à utiliser tel que « Imageneeded.png » , le paramètre régulier « default=Imageneeded.png » fera l'affaire.
Vous pouvez voir une démonstration de téléversement de fichier ici.
Notez que la fenêtre de téléversement ne fonctionnera pas si $wgBreakFrames est iniialisé à true dans votre fichier LocalSettings.php.
Vous pouvez également déclarer que les champs avec téléversement utilisent directement le téléversement du système d'exploitation, au lieu de passer par celui de MediaWiki - ce qui donne à l'utilisateur moins de possibilités, mais le processus est plus simple et sur les appareils mobiles cela peut présenter des options intéressantes comme de pouvoir téléverser des photos juste après qu'elles aient été prises. Pour réaliser cela, ajoutez la ligne suivante au fichier LocalSettings.php :
$wgPageFormsSimpleUpload = true;
Les paramètres spéciaux pour les champs téléversables sont :
uploadable- Indique que c'est un champ avec téléversement.image preview- Indique qu'une vignette de l'image téléversée doit être placée sous le champ dans le formulaire.default filename=nom de fichier - Indique le fichier par défaut pour les fichiers téléversés à l'aide de ce champ.