Extension:Page Forms/Valeurs, mapping et autocomplétion

Page Forms offre de nombreuses options liées à la fois à la définition et à l'affichage des valeurs possibles pour les entrées, à la fois pour les types d'entrées qui offrent un ensemble fini d'options (tels que les listes déroulantes et les cases à cocher) et ceux qui offrent une entrée des données de forme libre (comme les combox et les tokens).

Définition des valeurs et des correspondances

Certains types d'entrée fournissent à l'utilisateur des valeurs prédéfinies. Cela peut être des valeurs parmi lesquelles l'utilisateur doit choisir (comme le type d'entrée dropdown), ou des valeurs d'exemple pour guider l'utilisateur (comme combobox, bien que là aussi ces options peuvent être rendues obligatoires en ajoutant le paramètre existing values only).

Dans les deux cas, l'ensemble des paramètres pour spécifier les valeurs affichées à l'utilisateur est presque le même. Voici les paramètres de la balise de champ (field) qui peuvent être utilisés dans tous les cas :

cargo table= + cargo field=	Si Cargo est installé sur votre wiki, cet ensemble de paramètres sera automatiquement utilisé si le type d'entrée utilise l'autocomplétion, comme le fait combobox . Le code trouvera la table Cargo et le champ correspondant du modèle ou du formulaire, et utilisera toutes les valeurs qui ont été attribuées à ce champ. Ou vous pouvez utiliser ces paramètres pour spécifier toute combinaison de la table et du champ que vous souhaitez.
property=	Si Semantic MediaWiki est installé, ce paramètre sera automatiquement utilisé si le type d'entrée utilise l'autocomplétion. Le code trouvera la propriété ad'hoc et utilisera toutes ses valeurs, ou vous pouvez utiliser ce paramètre pour spécifier une propriété différente.
values from property=	Fonctionnellement, ce paramètre travaille de la même manière que property= ci-dessus, bien qu'il lui manque certains des effets secondaires : property= peut également impacter la taille et même le type d'entrée du champ.
values from category=	Tire ses valeurs à partir des noms de toutes les pages appartenant à une catégorie spécifique.
values from namespace=	Tire ses valeurs à partir des noms de un ou plusieurs espaces de noms spécifiques. Pour récupérer les valeurs de plusieurs espaces de noms, séparez-les par des virgules. Pour obtenir les valeurs à partir de l'espace de noms principal, utilisez Main ou laissez vide simplement.
values from concept=	Tire ses valeurs à partir du nom de toutes les pages appartenant à un concept SMW spécifique.
values from query=	Tire ses valeurs à partir d'une requête Semantic MediaWiki qui inclut le texte actuel dans l'entrée. Les substitutions suivantes doivent être faites selon la syntaxe standard des requêtes SMW : Au lieu de [ et ], utilisez ( et ) Au lieu de |, utilisez % Dans le texte actuel, placez @
values from url=, values from external data=, values from wikidata=	voir Autocomplétion sur des valeurs externes, ci-dessous.
values=	Enfin, vous pouvez simplement spécifier manuellement l'ensemble des valeurs affichées à l'utilisateur; un exemple serait values=Red,Yellow,Blue. Cet ensemble de valeurs doit être séparé par des virgules par défaut, mais le délimiteur peut être modifié en utilisant le paramètre delimiter=.

Il y existe quelques options supplémentaires pour les entrées basées sur l'autocomplétion; voir ci_dessous.

Correspondance

Il est possible que l'ensemble des valeurs affichées à l'utilisateur soit différent de l'ensemble des valeurs qui apparaissent actuellement dans le wikicode de la page. Si les valeurs sont des noms de pages et que ces pages ont un ensemble de titres d'affichage (display title) différent du nom réel de la page, le formulaire affichera par défaut ce display title au lieu du nom de page. Si vous le souhaitez, vous pouvez faire afficher le nom de la page lui-même en ajoutant ceci à LocalSettings.php :

$wgPageFormsUseDisplayTitle = false;

Vous pouvez activer d'autres correspondances similaires en utilisant les paramètres suivants :

mapping template=nom de modèle	Prend dans le nom d'un "mapping template" (un modèle qui prend un seul paramètre non nommé, par exemple {{{1|}}}, et affiche une chaîne associée en conséquence), et utilise ce modèle pour faire correspondre chaque valeur potentielle, de sorte que les alias des valeurs apparaissent à l'écran, et non pas les valeurs elles-mêmes.
mapping property=nom de la propriété	Utilisé pour les champs qui sélectionnent des pages avec les types d'entrée 'combobox', 'tokens', 'listbox', et 'dropdown'. Pour chaque valeur possible, affiche une propriété SMW de cette page plutôt que le titre de la page, mais enregistre le titre de la ou des pages sélectionnées comme valeur du champ. Utilisé en conjonction avec les paramètres values... pour obtenir la liste des valeurs possibles.
mapping cargo table=nom de table/mapping cargo field=nom de champ	Similaire à mapping property= sauf qu'il est utilisé pour les champs Cargo. Utilisé en conjonction avec values=, values from namespace=,values from category= et cargo table=/cargo field=. Vous pouvez également utiliser le paramètre mapping cargo value field=, qui indique quel champ de la table servant pour la correspondance, doit être utilisé comme le champ value (par défaut il s'agit de _pageName).
mapping using translate	Si l'extension Translate est installée, on appelle le mot magique {{int:}} de Translate sur chaque valeur pour obtenir la valeur correspondante.

Exemple 1 : modèle de correspondance

Un formulaire peut contenir une balise de champ telle que :

{{{field|status|values=Prospective,Live,Retired|mapping template=StatusLabel }}}

Le modèle sur Template:StatusLabel peut ensuite contenir quelque chose comme :

{{#switch: {{{1}}} | Retired=Label for Retired |Live=Label for Live | Prospective=Label for Prospective }}

Vous pouvez ensuite utiliser le même mapping template pour afficher le libellé de la valeur sur les pages classiques qui ne sont pas des formulaires. Dans le modèle qui contient le champ état, vous pouvez avoir ceci :

{{StatusLabel|{{{status|}}} }}

Exemple 2: correspondances basées sur Cargo

Supposons que, dans une entreprise, chaque employé ait un numéro d'identification. Dans le wiki, la page de chaque employé a pour nom l'identifiant de l'employé. Il existe aussi des pages sur les projets, et à l'intérieur de chaque page de projet on trouve un champ Membres du projet, qui contient la liste des identifiants des employés. Dans le formulaire "Projet", dans l'entrée "Membres du projet", vous voulez que les gens saisissent les noms réels des employés, mais que ce sont les identifiants des employés qui apparaissent sur la page. Vous pouvez le faire avec la balise de champ suivante :

{{{field|Project members|input type=tokens|mapping cargo table=Employees|mapping cargo field=Employee_name}}}

Maintenant si le nom de chaque page d'employé n'est pas l'identifiant de l'employé (ni son vrai nom) mais plutôt un nom attribué au hasard, comme "Employé 12345" ? Ensuite, vous pouvez faire l'association en utilisant le paramètre supplémentaire "mapping cargo value field" comme ceci :

{{{field|Project members|input type=tokens|mapping cargo table=Employees|mapping cargo field=Employee_name|mapping cargo value field=Employee_ID}}}

Autocomplétion

Quatre des types d'entrée (tokens, combobox, plus text with autocomplete et textarea with autocomplete pour les versions antérieures à la 5.0) utilisent l'autocomplétion - à mesure que l'utilisateur commence à taper, l'entrée affiche une liste déroulante des possibilités de complétion.

Si un champ représente une propriété de Semantic MediaWiki, ou de champ Cargo, de type Page, l'autocomplétion sera activée par défaut — le champ se complètera automatiquement pour les noms de toutes les pages qui sont déjà marquées par cette propriété ou ce champ. Pour tous les autres types, il n'existe pas d'autocomplétion par défaut, mais vous pouvez réaliser cela simplement en déclarant ce type d'entrée comme étant l'un des quatre possèdant l'autcomplétion.

Vous pouvez définir manuellement un champ à autocomplétion sur l'ensemble des valeurs à partir d'une propriété SMW, d'un champ Cargo, d'une catégorie, d'un espace de noms, d'un concept, ou d'une liste définie manuellement, en utilisant l'un des paramètres valeurs ... - voir ci-dessus.

Vous pouvez aussi appliquer l'autocomplétion basée sur des valeurs hors du wiki, contenues dans des pages web, des bases de données, des fichiers, etc.; voir ci-après pour les différentes manières de réaliser cela.

Si un champ est désigné comme contenant des valeurs multiples, l'autocomplétion prendra en charge par défaut les valeurs multiples : après avoir saisi une valeur et placé le délimiteur, une nouvelle autocomplétion va recommencer avec la valeur suivante. Vous pouvez spécifier manuellement qu'un champ doit avoir une complétion automatique à valeurs multiples, en ajoutant le paramètre "list" à la définition du champ. Vous pouvez également spécifier le délimiteur de cette liste de valeurs, en utilisant le paramètre « delimiter=... » (valeur par défaut : une virgule ',').

Par défaut, le nombre maximum de possibilités d'autocomplétion qu'un champ peut offrir est de 1 000; c'est pour des raisons de performance. Pour modifier ce nombre, modifiez la valeur de $wgPageFormsMaxAutocompleteValues dans LocalSettings.php.

Désactivation

Vous pouvez désactiver l'autocomplétion si elle a été déclarée par défaut sur un champ, en indiquant que le type d'entrée est simplement « text » ou « textarea ».

Autocomplétion distante

L'ensemble des valeurs possibles d'autocomplétion d'un champ est par défaut contenu directement dans la page HTML du formulaire, dans une déclaration JavaScript. 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. Une fois cette valeur atteinte, l'autocomplétation à distance est réalisée à l'endroit, où l'autocompletation se produit par un appel Ajax au serveur, en fonction de ce que l'utilisateur a saisi. Ce type d'autocomplétion est plus lent, mais il permet beaucoup plus de résultats d'autocomplétion.

Vous pouvez modifier la définition par défaut en ajoutant quelque chose comme ceci à LocalSettings.php :

$wgPageFormsMaxLocalAutocompleteValues = 200;

Correspondance de chaque caractère

Par défaut, l'autocomplétion dans Page Forms détecte le début de chaque mot dans l'ensemble des valeurs possibles. Vous pouvez par contre modifier l'autocomplétion afin qu'elle coïncide avec chaque caractère, en ajoutant la ligne suivante à LocalSettings.php :

$wgPageFormsAutocompleteOnAllChars = true;

Cette fonctionnalité est particulièrement importante pour les wikis qui ont des valeurs avec des caractères non ASCII, comme les wikis dans les langues avec des alphabets non romains; puisque la complétion automatique par défaut, basée sur les mots ne fonctionne pas encore avec des caractères non ASCII.

Autocomplétion sur les caractères accentués

Autocomplétion avec des caractères accentués

L'autocomplétion des inflexions pour les caractères accentués, est prise en charge pour les types d'entrée combobox et tokens.

Le repli d'accents a ses limites mais il peut aider à ce que certaines interactions importantes quoique négligées, avec l'utilisateur fonctionnent mieux. Une fonction réalisant le repli d'accents associe essentiellement les caractères Unicode à leur équivalent ASCII. Avec le repli d'accents, il n'est pas important de savoir si vous cherchez cafe, café ou çåFé; le résultat sera le même.

Autocomplétion sur les valeurs externes

Il existe quelques façons d'avoir un champ complété automatiquement en utilisant des données provenant de l'extérieur du wiki :

• à partir d'une URL similaire à celle d'une API qui prend une sous-chaîne et renvoie les données au format JSON nécessaire
• à partir de Wikidata
• à partir de toute source externe, en utilisant l'extension External Data/fr .

A partir d'une URL externe

Vous pouvez obtenir l'autocomplétion d'un champ sur des valeurs venant de l'extérieur du wiki, en utilisant le paramètre suivant :

• values from url=identifiant d'URL

Pour réaliser cela, suivez ces étapes :

1. Créez une page ou un service web qui recupère une sous-chaîne via la chaîne de requête, et qui affiche un ensemble de valeurs de complétion. Page Forms attend un format JSON dans la réponse avec une clé « pfautocomplete » à la racine et un tableau d'objets avec la clé « title » marquant les valeurs des complétions possibles. Un court exemple de ceci est disponible à partir de cet appel d'API sur semantic-mediawiki.org.

   Par exemple, si vous aviez une liste de trois pays -- Uruguay, Germany et Japan -- et que l'on vous demande la liste des résultats possibles pour "an", vous renverrez :

   {"pfautocomplete":[{"title":"Germany"},{"title":"Japan"}]}

   Ceci facilite aussi l'autocomplétion des valeurs provenant d'un autre wiki.

2. Décidez d'une chaîne courte pour représenter cette URL.

   Par exemple, le service qui fournit des recherches dans notre liste de pays pourrait être appelé countryLookup.

3. Ajoutez la chaîne abrégée dans le tableau de $wgPageFormsAutocompletionURLs du fichier LocalSettings.php pour configurer Page Forms et utiliser votre URL lorsqu'il détecte la chaîne. Mettez « <substr> » là où vous voulez envoyer la saisie de l'utilisateur.

   Dans notre exemple, si nous voulons que Page Forms alimente le texte tapé par l'utilisateur vers l'URL http://example.dom/countryLookup.php via le paramètre d'URL « c », nous écrivons :

   $wgPageFormsAutocompletionURLs['countryLookup'] = 'http://example.dom/countryLookup.php?c=<substr>';
   

4. Ajoutez le paramètre « values from url=URL-identifier-string » au champ ad'hoc dans la définition du formulaire.

   Pour notre exemple des pays, le champ peut ressembler à :

   {{{field|country|input type=tokens|values from url=countryLookup}}}

A partir de Wikidata

Vous pouvez avoir un formulaire de saisie et compléter automatiquement les valeurs de Wikidata, en utilisant le paramètre values from wikidata=. La valeur de ce paramètre est structurée comme une mini-requête, comme P31=Q860861&P17=Q38 ("instance of" = "sculpture", "country" = "Italy"). Les valeurs "Q" peuvent également être remplacées par des noms de champs, pour permettre une version basée sur Wikidata de "show on select", par exemple P31=Q860861&P17=Location[Country], où "Location" est un modèle, et "Country" est un champ, au-dessus de celui actuel.

Utiliser l'extension External Data

Images d'icônes associées aux valeurs d'autocomplétion, en utilisant valeurs provenant de données externes

L'extension External Data (ED) prend en charge la récupération des données à partir d'un certain nombre de sources qui incluent les URL externes, les pages régulières de wiki, les fichiers téléversés, les fichiers du serveur local, les bases de données et les répertoires LDAP.

Pour compléter automatiquement en utilisant ED, vous devez d'abord appeler l'une des fonctions #get_..._data d'analyse de ED dans la définition du formulaire (de préférence en bas de la définition du formulaire, pour éviter les passages à la ligne inutiles). Cela permettra de récupérer les données qui peuvent ensuite être utilisées dans les balises des champs. (Voir la documentation de External Data pour savoir comment les appeler). La balise de champ peut alors utiliser ces paramètres :

• values from external data=nom de variable ED (obligatoire)
• image=nom de variable ED (optionnel)
• description=nom de variable ED (optionnel)

Voici un exemple d'appel à #get_web_data pour récupérer les données d'une URL :

{{#get_web_data:url=URL |format=csv with header |data=title_variable_name=external_variable_name1,image_variable_name=external_variable_name2, description_variable_name=external_variable_name3}}

En supposant qu'une définition de formulaire contienne un tel appel, une balise de champ peut ensuite utiliser les valeurs récupérées pour l'autocomplétion - non pas simplement pour définir les valeurs d'autocomplétion en elles-mêmes, mais également, si le type d'entrée est « combobox » ou « tokens » , pour définir une image de la vignette correspondante et la description de chacunes d'elles.

En supposant que l'appel de External Data récupère trois colonnes de valeurs comme ci-dessus, la balise du champ qui utilise ces données est similaire à :

{{{field|...|values from external data=title_variable_name|image=image_variable_name|description=description_variable_name}}}

Autocomplétion dépendante

Vous pouvez définir les valeurs d'autocomplétion d'un champ en fonction de la valeur déjà définie par l'utilisateur d'un autre champ du formulaire. Ceci se fait à l'aide du paramètre values dependent on= dont la syntaxe est la suivante :

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

Il spécifie que l'ensemble actuel de valeurs autorisées pour ce champ comprend toutes les valeurs prises par ce même champ à partir de pages où 'field name' est égal à la valeur sélectionnée pour 'field name' dans la forme actuelle.

Est-ce gênant ?

Eh bien, cet exemple peut vous aider: si un modèle s'appelle "Restaurant" et qu'il contient des champs de modèle (pas des propriétés) nommés "Country" et "City" et que vous voulez que l'ensemble des villes utilisées pour l'autocomplétion soit uniquement celui des villes "dans le pays que l'utilisateur a sélectionné", alors la balise de champ pour le champ City doit ressembler à : {{{field|City|input type=combobox|values dependent on=Restaurant[Country]}}}

Paramètre show on select

Pour les entrées de type 'checkbox', 'checkboxes', 'radiobutton', 'dropdown' et 'listbox', le paramètre show on select= spécifie qu'un ou plusieurs éléments de la page ne doivent être affichés que si certaines valeurs sont sélectionnées dans cette entrée.

La syntaxe de ce paramètre est :

• show on select=valeur 1=>ID d'élément 1;valeur 2=>ID d'élément 2;valeur 3=>ID d'élément 3;...

Une valeur peut être fournie avec plus d'un ID d'élément :

• show on select=valeur A=>ID d'élément 1;valeur B=>ID d'élément 1;valeur B=>ID d'élément 2;valeur C=>ID d'élément 3;...

Si vous utilisez show on select avec un modèle de correspondance, utilisez comme valeurs, les étiquettes définies dans le modèle de correspondance (et non pas les vrais noms des paramètres).

Pour les entrées de type 'checkbox', il suffit d'utiliser « show on select=element ID ». Notez que les identifiants d'éléments ne peuvent pas contenir d'espaces ni de caractères multi-octets et ne peuvent pas commencer par un nombre.

Pour un exemple de cette fonctionnalité utilisée, voir ce formulaire, et observez ce qui se passe lorsque vous sélectionnez différentes valeurs de la liste déroulante Publication type. Vous pouvez voir comment cela a été mis en œuvre dans cette définition de formulaire.