Help:Requêtes intégrées
Semantic MediaWiki comporte un langage de requête de recherche sémantique qui permet aux utilisateurs de rechercher directement certaines informations du wiki. Les lecteurs qui ne souhaitent pas apprendre cette syntaxe de requête peuvent cependant en bénéficier : les requêtes intégrées insèrent directement les résultats des requêtes dans les pages. Ainsi, les requêtes créées par peu de rédacteurs peuvent être utiles à beaucoup de lecteurs.
Les requêtes intégrées sont similaires aux autres fonctions sémantiques et peuvent donc être inactivées sur certains sites pour y garantir des performances satisfaisantes. Parce que les requêtes intégrées utilisent les méchanismes de cache existants de MediaWiki, beaucoup des requêtes d'une page avec de tels contenus dynamiques peuvent cependant être exécutées sans impact sur les performances.
Introduction[edit]
On met une requête intégrée dans sur le texte wiki d'une page en utilisant la fonction d'analyse ask implémentée par Semantic MediaWiki. Comme les autres fonctions d'analyse des extensions, sa syntaxe se présente sous la forme
{{#ask:argument 1 | argument 2 | … }}
dans laquelle les arguments … décrivent la requête.
(Notez que dans les versions de MediaWiki antérieures à 1.0, une autre syntaxe de requête intégrée existait, avec la balise <ask>. Elle fonctionne encore et est documentée à la fin de cette page.)
L'argument le plus important de la fonction #ask est la condition pour l'affichage, décrite dans la page d'aide sur la recherche sémantique. Par exemple, on peut écrire
{{#ask: [[Category:City]] [[located in::Germany]] }}
pour obtenir la liste de toutes les villes situées en Allemagne. À l'endroit où se trouve cette requête dans le texte wiki, une liste simple de tous les titre des pages correspondantes s'affichera à l'intérieur de la page.
Faisons le ici : Resultat : Aalen, Amberg, Andernach, Ansbach, Aschaffenburg, Augsburg, Aurich, Backnang, Bad Oeynhausen, Bamberg, Bayreuth, Berlin, Bielefeld, Bochum, Bonn, Braunschweig, Bremen, Burghausen, Calw, Chemnitz, Coburg, Cologne, Cottbus, Darmstadt, Deggendorf, Dinslaken, Dortmund, Dresden, Duesseldorf, Duisburg, Ebersberg, Einbeck, Erfurt, Erlangen, Essen, Esslingen am Neckar, Flensburg, Frankfurt, Freiburg, Fürth, Georgsmarienhütte, Gera, Gerlingen, Gerolzhofen, Goettingen, Gotha, Greifswald, Halle, Hamburg, Hannover... further results
Remarquez que tous les arguments à la fonction #ask: sont ignorés par l'analyse des pages. En conséquence, l'exemple ci-dessus n'ajoute aucune catégorie ou annotation de la proprité « Situé en » à la page considérée.
Pour afficher d'autres propriétés de la page remplissant les conditions, ajoutez d'autres arguments sous la forme ?nom de la propriété, par exemple
{{#ask: [[Category:City]] [[located in::Germany]]
| ?Population
}}
Résultat :
}}
Notez certaines choses :
- Nous utilisons le symbole barre verticale | pour séparer les conditions de la propriété à afficher ;
- Les conditions d'affichage sont un argument simple à la fonction ask, c'est pourquoi il n'y a pas de symbole '|' entre elles ;
- Comme vous pouvez le voir, vous pouvez ajoutez des espaces vides dans la fonction #ask, l'analyse est très flexible&nbps;;
- Le format de l'affichage des résultats change lorsque vous demandez l'affichage de propriétés supplémentaires. SMW sélectionne par défaut le format approprié aux résultats de la requête, mais vous pouvez un large contrôle de l'apparence des résultats d'une requête.
Arguments des requêtes intégrées[edit]
En général, une requête intégrée est une requête pour trouver un nombre de de pages répondant à certaines conditions. Cette requête doit répondre à trois conditions :
- Quelles pages sont demandées ?
- Quelles informations sur ces pages doivent être affichées ?
- Comment doivent être formatés les résultats à l'intérieur de la page ?
Les deux premiers points font souvent partie de la requête et ont été exposés dans Help:Recherche sémantique. Le troisième point est important afin de pouvoir commodément incorporer les résultats de requêtes dans beaucoup de page. Dans l'exemple ci-dessus, nous pourrions vouloir une liste avec puces des pays avec la population de chacun d'eux imprimé entre parenthèses après leur nom. On peut y arriver en choisissat le format ol :
{{#ask:
[[Category:City]]
[[located in::Germany]]
|?Population
| format=ol
}}
Résultat :
- Aalen
- Amberg
- Andernach
- Ansbach
- Aschaffenburg
- Augsburg
- Aurich
- Backnang
- Bad Oeynhausen
- Bamberg
- Bayreuth
- Berlin
- Bielefeld
- Bochum
- Bonn
- Braunschweig
- Bremen
- Burghausen
- Calw
- Chemnitz
- Coburg
- Cologne
- Cottbus
- Darmstadt
- Deggendorf
- Dinslaken
- Dortmund
- Dresden
- Duesseldorf
- Duisburg
- Ebersberg
- Einbeck
- Erfurt
- Erlangen
- Essen
- Esslingen am Neckar
- Flensburg
- Frankfurt
- Freiburg
- Fürth
- Georgsmarienhütte
- Gera
- Gerlingen
- Gerolzhofen
- Goettingen
- Gotha
- Greifswald
- Halle
- Hamburg
- Hannover
Cette troisième étape est indépendante des deux autres et un grand nombre de formats de sortie sont possibles aux requêtes intégrées. En plus du format, les requêtes intégrées acceptent un grand nombre de paramètres, par exemple pour trier les résultats ou pour limiter le nombre de résultats.
Paramètres standards[edit]
Beaucoup de paramètres standards sont déjà disponibles pour configurer les résultats des requêtes intégrées. Ce sont :
| Paramètre | Valeurs possibles | Description |
|---|---|---|
| limit | nombre non négatif | nombre maximal de page sélectionnées (dans le cas d'une table : rangées) |
| offset | nombre | à partir de quel chiffre démarrer |
| sort | nom de la propriété | nom de la propriété à utiliser pour trier les résultats |
| order | ascending/asc, descending>/desc/reverse | définit comment les résultats doivent être triés. Ne s'applique que si sort est utilisé. Le choix par défaut est ascending |
| headers | show, hide | affiche ou masque les en-têtes utilisées dans certains formats de sortie tels que table. hide est le choix par défaut |
| mainlabel | texte plein | titre de la première collone, celle contenant les titres des pages) |
| link | aucune | définit quel noms d'articles seront liés dans les résultats. all est le choix par défaut |
| default | texte plein | Si, pour une raison quelconque, la requête ne retourne aucun résultat, ceci sera affiché à la place |
| intro | texte plein | texte préliminaire qui précède la sortie, s'il y a des résultats |
| searchlabel | texte plein | texte pour continuer la recherche (par défaut« … autres résultats ») |
| debug | true | [seulement sur SMW≤0.6] retourne un rapport de débogage SQL au lieu des résultats de la requête |
| format | nom de format (voir infra) | format de sortie sélectionnée ; certains formats autorisent des paramètres supplémentaires (voir #Formats de sortie) |
Limites des résultats et résultats supplémentaires[edit]
Vous pouvez fixer le paramètre limit pour restreindre le nombre maximal de résultats retournés. Par exemple, la requête
{{#ask:
[[Category:City]]
[[located in::Germany]]
| limit=3
}}
affiche les trois plus grandes villes d'Allemagne. Même si vous n'assignez aucune valeur à limit, SMW applique toujours une limite semblable aux résultats d'une requête. Selon les réglages du site, il est être possible d'augmenter le nombre de résultats affichés en déterminant une valeur supérieure à limit. Cependant, il y a une limite maximale qui ne peut être franchie, établie par l'administrateur du site et basée sur des considérations de performances.
Lançons la requête ci-cessus; Résultat : Aalen, Amberg, Andernach... further results
Comme vous pouvez le constater, lorsqu'une requête n'affiche pas tous ses résultats en raison d'une limite, elle offrira souvent un lien vers d'« autres résultats ». Le texte de ce lien peut être modifié grâce au paramètre searchlabel. Si la valeur de searchlabel est "", alors aucun lien vers d'autres résultats n'apparaît. Certains formats de sortie (voir infra) n'affichent jamais le lien « autres résultats » ou ne l'affichent que si searchlabel a été configuré.
Une application de limit et searchlabel est de n'afficher que un lien vers les résultats d'une recherche sans afficher aucun résultat dans le corps du texte. Vous y parvenez en fixant limit à "0". Par exemple, la requête
{{#ask: [[Category:City]] | limit="0" | searchlabel=Cliquez pour parcourir un liste de villes}}
affiche Résultat : Cliquez pour parcourir un liste de villes.
Aucun résultat, rien n'apparaît[edit]
Si aucun article ne satisfait les conditions d'une requête, rien n'apparaît. Ceci peut être utile, mais plus souvent encore, une requête intégrée passe à côté de notations sémantiques sur le wiki et personne ne remarque que cette requête sur une page travaille pour ne rien afficher. Pour être sûr qu'une requête affiche toujours quelque chose, vous devriez assigner un texte au paramètre default, par exemple
{{#ask: [[Category:City]] [[Located in::Antarctica]]
| intro=Tout sur les villes en Antarctique |?Population |?Localisation
| default:Il semble ne pas y avoir de ville en Antarctique
}}
Résultat :
{{#ask: [[Category:City]] [[Located in::Antarctica]]
| intro=Tout sur les villes en Antarctique |?Population |?Localisation
| default:Il semble ne pas y avoir de ville en Antarctique
}}
Tri des résultats[edit]
Par défaut, les résultats d'une recherche sémantique sont en ordre alphabétique, croissant, de leurs titres de page. Le formulaire d'entrée Special:Ask comporte un champ supplémentaire d'entrée afin de spécifier une colonne de tri et l'alignement. Dans les requêtes intégrées, cette collone de tri est déterminée par le paramètre sort et l'ordre avec le paramètre order. La valeur de order peut être « ascending » ou « descendng » (ou les formes abrégées « asc » et « desc », ou « reverse »).
Trier par une propriété pose implicitement la condition que les pages doivent avoir une valeur pour cette propriété (une condition que vous pouvez également poser par [[Prop name::+]]). Par exemple, la requête des villes triées par surface n'affiche que les villes ayant une valeur pour Property:Area :
{{#ask:
mainlabel=Villes triées par surface
| [[Category:City]]
| ?Population
| sort=Area]]
}}
Résultat :
{{#ask:
mainlabel=Villes triées par surface
| [[Category:City]]
| ?Population
| sort=Area]]
}}
Formats de sortie[edit]
Le paramètre format détermine comment les résultats d'une requête sont affichés dans l'article. S'il est omis, toutes les requêtes dans un tableau (format table), à moins qu'il n'y ait qu'une seule colonne, auquel cas les résultats sont affichés dans une liste avec une virgule comme virgule (format list). Les formats suivants sont disponibles :
| Format | Description | Paramètres supplémentaires |
|---|---|---|
| list | Liste avec virgules comme séparateur avec les autres champs affichés entre parenthèses | sep, templates |
| ol | Liste ordonnée avec les autres champs affichés entre parenthèses | sep, template |
| ul | Liste à puces avec les champs supplémentaires affichés entre parenthèses | sep, template |
| tableau | affichage en tableau | |
| broadtable | Affichage en tableau, de la largeur de l'article | |
| timeline | Utilise les dates dans la sortie pour afficher un axe temporel | timelinestart, timelineend, timelinesize (default "300px"), timelinebands, timelinestart (par défaut "middle") |
| eventline | Non stable. Utilise les dates des sorties pour afficher un axe temporel comportant plus de deux dates par article | timelineposition (par défaut "middle") |
| embedded | Non stable. embarque les articles sélectionnés | embedonly (si choisi, n'affiche pas l'article), embedformat (peut être ol, ul, h1, h2, …, h6) |
| template | Non stable. Affiche les résultats en passant les champs des résultats comme paramètre à un modèle donné | template (obligatoire) |
| count | Seulement le nombre de résultats au lieu des résultats eux même | |
| debug | Informations de débogage pour analyser les problèmes dans les réponses aux requêtes | |
| rss | Affiche des liens RSS vers les résultats des requêtes | rsstitle, rssdescription |
Utilisation de modèles[edit]
Dans une requête intégrée, lorsque format=template ou format=list, les modèles peuvent être utilisés pour formater ce qui est retourné par une requête, en utilisant la syntaxe suivante :
- <ask format=modèle modèle=nom du modèle> … </ask> ou
- <ask format=list modèle=nom du modèle> … </ask.
Le modèle peut utiliser beaucoup d'arguments : ils se rapportent aux résultats qui seront produits par la requête intégrée pour chaque page sélectionnée (y compris la page elle-même si cela doit normalent être le cas) dans le même ordre. Ainsi, si la page sélectionnée est elle-même normalement produite, celle-ci se réfère à {{{1}}} et les autres résultats se réfèrent en conséquence à {{{2}}}, {{{3}}}, … Voir infra.
La fonction modèle ajoute une grande flexibilité dans la sortie de la requête, notamment :
- Modifier l'ordre dans lequel les résultats seront afficher, ôter ou dupliquer des résultats ;
- Afficher des images selon les résultats des requêtes ;
- Créer des liens pour les attributs ;
- Utiliser des styles CSS pour faire varier la taille des polices, l'alignement, la couleur d'arrière-plan, ec. dans chaque colonne des tableaux.
N.B.
- Lorsque les résultats sont limités, le format du modèle ne sera pas reporté vers le lien de continuation.
- Les fonctions d'analyse appliquées aux paramètres (par exemple pour le calcul et les embranchements).
- Si les pages sélectionnées ont été normalement produites, la page sélectionnée se réfère elle-même à {{{1}}} et les autres résultats se réfèrent par conséquent à {{{2}}}, {{{3}}}, … Si la page sélectionnée n'est pas elle-même normalement produite, {{{1}}} se réfère au premier résultat sur la page. Ainsi, normalement, différents modèles de format sont nécessaires dans les deux cas. …
Utiliser une requête pour produire des informations[edit]
Lorsque l'on fait une requête sur une propriété, SMW ne recherche (actuellement) pas les popriétés inverses ou transitives. Les pages doivent à coup sûr contenir la propriété de la requête qui est faite. Par exemple, s'il y a des pages sur les architectes avec la propriété architect of, vous devez encore annoter la page des constructions avec a pour architecte pour faire apparaître la propriété inverse sur la page et dans les requêtes.
Si vous savez qu'il existe une annotation précise, vous pouvez utiliser la forme de la fonction dans l'annotation pour rechercher l'inverse. Par exemple, sur la page d'un bâtiment, vous pouvez ajouter
Son architecte est [[A pour architecte::{{#ask: [[Architecte de::{{PAGENAME}}]]|link=none}} ]]
S'il existe plus d'une propriété inverse, cela ne marchera pas. Par exemple, s'il y a plusieurs pages avec la propriété located in:=California. Cependant, on peut mettre une requête intégrée dans une page de brouillon, qui générera une liste de ces propriétés ayant l'apparence de texte wiki et la coller dans la page. Par exemple, écrivez
[ [location of:=<ask sep="| ]][[location of:=">[[located in::California]]</ask>| ]],
, ce qui donne
- [ [location of:=<ask sep="| ]]"">[[located in" contains a listed "[" character as part of the property label and has therefore been classified as invalid.</ask>| ]],
et copiez le dans la page Germany (ôtez l'espace entre les deux premiers crochets après avoir collé ce texte).
Format de l'ancienne balise <ask>[edit]
Avant la version 1.0 de SMW, vous pouviez écrire des requêtes intégrées à l'intérieur d'une balise ask.
<ask paramètres>…</ask>
dans laquelle les … décrivent la requête.
Cette forme fonctionne encore, mais n'est plus recommandée.
La partie entre les deux balises ask peuvent être toute requête, comme décrite sur la page relative à la semantic search. Par exemple, on peut écrire
<ask>[[Category:City]] [[located in::Germany]]</ask>
À la différence de la fonction {{#ask:}},
- vous spécifiez les propriétés supplémentaires à afficher en les mentionnant dans le format des annotations avec un astérisque à la place des conditions
- vous spécifiez les paramètres supplémentaires dans la balise ask ouvrante.
Par exemple, pour afficher la liste de la population de ces villes, triées par population en ordre décroissant et limitée aux cinq plus grandes, on peut écrire,
<ask sort=Population order=desc limit=5> [[Category:City]] [[located in::Germany]] [[Population:*]] </ask>
Résultat : <ask sort=Population order=desc limit=5> Germany Population:*</ask>
