Table des matières

Index et recherches de pages

Traduction à relire pour corriger les coquilles et compléter ce qui n'est éventuellement pas clair.

La gestion des index et des recherches de pages se fait grâce au plugin pagequery : il s'agit d'un outil de navigation polyvalent pour créer des pages d'index, faire des recherches ou des filtres sur du texte ou des noms de page, et afficher les résultats, regroupés et/ou triés, en colonnes. Il propose même des info-bulles pour prévisualiser le contenu.

Comme pagequery a fait un usage éhonté des excellentes fonctions disponibles dans DokuWiki (en particulier search), il n'y a pas de nouvelle syntaxe à apprendre. Mais il apporte un petit quelque chose en plus dans l'arrangement des puissantes options de tri et de regroupement.

Quelques utilisations possibles :

Syntaxe et utilisation

Insérer la mention pageguery dans le texte de la page là où vous voulez que la liste apparaisse. Vous pouvez avoir différentes listes pagequery dans la même page1).

Il peut s'agir d'une version simple :

{{pagequery>}}

Ou, plus compliquée :

{{pagequery>[query];fulltext;sort=key:direction,key2:direction;group;limit=10;cols=2;spelldate;proper}}

Ou alors à l'ancienne, et vraiment trop compliquée… :

{{pagequery>[query];fulltext;sort=key:direction,key2:direction;group;limit=100;cols=6;spelldate;proper;snippet=5;border=inside;hidestart;case;natsort}}

Remarque : la syntaxe peut être affichée sur plusieurs lignes pour améliorer la lisibilité. Les espaces sont alors tout simplement ignorés. Par exemple :

{{pagequery>query;
  fulltext;
  sort=key:direction,key2:direction;
  group;
  limit=100;
  cols=6;
  spelldate;
  proper;
  border=inside;
  hidestart;
  case;
  natsort
}}

La règle générale est que les options sont séparées par des points-virgules (;), les valeurs (par exemple dans un tri ou un filtre) sont séparées par une virgule (,), et les valeurs multi-parties par deux points (:).

Tableau de la syntaxe complexe

Option Description Exemples de syntaxe Valeur par défaut
query Place l'expression de recherche immédiatement après le >, par exemple {{ pagequery>help;... }}
Par défaut, il cherche seulement dans les noms de pages (ou les identifiants). Pour faire une recherche dans le contenu des pages du wiki, utiliser l'option fulltext ci-dessous.
*
help
test
toutes les pages
Vous pouvez utiliser des expressions régulières2) dans les recherches de nom de page. Pour voir toutes les pages, utilisez * ou .* , ou laissez simplement à blanc3). ^p.+
[mots commençants par p]
Note : * en lui-même est juste une commodité. Dans n'importe quelle autre regex, il vous faudra suivre les règles de la regex.
namespaces La recherche sur les noms de page accepte les mêmes options d'espaces de noms que la recherche dans le texte, c'est-à-dire : ^ ou -ns: signifie exclure, @ ou ns: signifie inclure. ^:work @:home:games * rien
Les espaces de noms relatifs (.) et parent (..) sont aussi compatibles4).
Note : si vous utilisez l'option namespace, il vous faudra également fournir une requête de nom de page (au minimum *), parce que, par exemple, la fonction regex ne peut pas distinguer ^work (espace de nom) et ^work (noms de pages commençant par “work”).
fulltext Utilise une recherche sur tout le texte, ce qui autorise toutes les options de recherche DokuWiki. Cette option vous permet de faire tout un tas de recherches compliquées : reportez vous à la page :search pour plus de détails. fulltext
fullregex Vous permet de faire une recherche sur l'identifiant complet de la page (c'est-à-dire y compris son espace de nom) à l'aide d'expressions régulières. C'est un mode brut pour utilisateurs avancés… mais ça ne fonctionne que sur les identifiants de page. fullregex
sort Clés à utiliser pour le tri, par ordre d'application dans le tri. Chaque clé peut être suivie par un ordre de tri préféré : sort=key:direction,key2:direction sort=a:asc,name:asc
sort=cyear,cmonth,name
rien
Clés de tri :
a, ab, abc Sur la 1ère, les 2 premières ou les 3 premières lettres. sort=a
sort=ab
name, pagename Par nom de page5) [non groupé] sort=name
title, heading Par titre de page (ou première ligne d'en-tête) [non groupé] sort=title:desc
id, pageid Par identifiant complet de page, y compris l'espace de nom [non groupé] sort=id:asc
ns Par espace de nom (sans nom de page) sort=ns
mdate, cdate Par date de création/modification (complète) [non groupé]sort=mdate
m[year][month][day]Par [année][mois][jour] de [m]odification ; toutes les combinaisons sont acceptées sort=myearmonthday
sort=mmonthday
c[year][month][day]Par [année][mois][jour] de [c]réation; toutes les combinaisons sont acceptées sort=cyearmonthday
creator Par auteur de page sort=creator
contributor Par contributeur(s) à la page. Note : seul le prénom affecte l'ordre de tri6)sort=contributor:asc
sort=contrib
links Par une liste des liens présents dans cette page (essentiellement pour le filtrage). Les noms (ou identifiants) de toutes les pages liées sont jointes dans une chaîne séparée par des espaces, qui peut être analysée par regex dans l'option filter ci-dessous.
backlinks Par une liste des rétro-liens pointant sur cette, ou ces, page(s). A utiliser comme link ci-dessus.
Sens de tri :
asc, a Ordre ascendant, c'est-à-dire a → z, 1 → 10 sort=name:asc asc
desc, d Ordre décroissant, c'est-à-dire z → a, 10 → 1 sort=mdate:desc
Note : par défaut, les dates sont triées par ordre décroissant (les dates les plus récentes en haut), et les textes par ordre ascendant (A - Z)
filter Filtre la liste de résultats par n'importe laquelle des clés de tris ci-dessus, à l'aide d'expressions régulière pour inclure ou exclure certaines pages
include La syntaxe est identique à celle du sort ci-dessus : filter=<key>:<expression>,<key2>:<expression2> filter=creator:harry
filter=contrib:.*(harry|sally).*
exclude Pour exclure des pages des résultats, mettre un ^ ou un ! devant la clé : filter=!<key>:<expression> filter=!creator:harry
dates filter= l'option reconnait désormais les dates réelles et vous permet de les filtrer correctement. Par exemple : filter=cdate:3 years ago->3 months ago
Une date de début et/ou de fin peut être donnée, séparée par le symbole flèche ->. Ceci utilise la fonction PHP strtotime qui accepte une grande variété de formats, se reporter aux fonctions php de date pour plus d'information.
Depuis une date donnée jusqu'à maintenant filter=mdate:24.1.2009->
Seulement jusqu'à une date donnée filter=mdate:->24.12.2012
Seulement les trois derniers mois filter=mdate:3 months ago->
group Affiche un en-tête de groupe pour chaque changement dans la clé de tri.7) group non groupé
Par exemple, si vous avez trié par [myear] (c'est-à-dire année de modification) alors l'en-tête du groupe sera inséré à chaque fois que l'année change
(2010…2009…2008…etc…)
Les espaces de noms sont groupés par tous les sous-espaces de noms jusqu'à la limite maxns8)
Note : les clés qui sont toutes uniques ne peuvent pas être groupées (c'est-à-dire les noms, les identifiants de page, la date de modification (mdate) ou de création(cdate) )
limit Nombre maximum de résultats à ramener. 0 = ramener tout (défaut) limit=10 tout
spelldate Utilise le vrai nom du mois ou du jour à la place de dates numériques.9) spelldate dates numériques
cols Nombre de colonnes dans la liste affichée (max = 6) cols=3 1
proper Affiche les noms des pages et/ou les espaces de noms avec la casse correcte (c'est-à-dire une majuscule à chaque mot et pas de _'s)10). rien
name Affiche les noms de page dans la casse correcte proper=name
header Affiche les en-têtes de groupe dans la casse correcte proper=header
proper=hdr
both Les deux options ci-dessus ! proper=both
proper
Note : ceci est différent de l'option UseHeading dans DokuWiki et de nombreux autres plugins (voir l'option display ci-dessous)
border Affiche une bordure autour des colonnes du tableau rien
none N'affiche aucune bordure (défaut) border=none
inside Affiche des bordures seulement entre les colonnes border=inside
outside Affiche une bordure autour de tout le tableau pagequery border=outside
both Affiche des bordures à la fois autour du tableau et des colonnes border=both
border
hidestart Ignore toutes les pages start par défaut dans les espaces de nom. hidestart montres les pages start
Note : les pages start doivent être nommées en accord avec les paramètres de votre configuration pour que cette option fonctionne correctement !
display Comment afficher les liens des pages. Par exemple, vous pouvez afficher juste le nom de la page, le titre de la page, l'identifiant de la page, la date de la page, ou toute autre combinaison des méta-données de la page.
L'option display= accepte les chaînes de remplacement de style-modèledisplay={name} ({cdate})
“Name-of-page (20 Jan 2013)”
Note : tous les noms de méta-données doivent être entre accolades {}, ou ils seront considérés comme de simples mots !
Tous les champs de méta-données de DokuWiki sont acceptés, plus toute méta-colonne pagequery en cours d'utilisation. Pour utiliser les méta-données imbriquées de DokuWiki, utiliser key:subkey.display={date:created} {title}
Voir les métadonnées pour une liste des noms de champ que vous pouvez utiliser.
snippet Contrôle comment la page de coupures (aperçu) est affichée : tooltip
tooltip Comme un pop-up/une info-bulle sur le lien de chaque page snippet=tooltip
snippet
Les trois prochaines options utilisent la syntaxe suivante : <format>,<count>,<extent>
<format>: l'un des formats listés ci-dessous : inline, plain, quoted
<count>: pour afficher les premiers <count> objets dans la liste avec un aperçu tout
<extent>: peut être un choix entre les [c]aractères, [w]mots, [l]ignes, ou [~]<s'arrêter à>
par exemple : c? = ? caractères, w? = ? mots, l? = ? lignes, ~? = chercher jusqu'au caractère/texte/symbole ?
tout
inline afficher sur la même ligne que le lien snippet=inline,5,c20
plain affiche comme du texte simple en-dessous du lien (mise en forme minimale) snippet=plain,10,w30
quoted afficher dans boite de citation ordonnée snippet=quoted,3,l3
maxns Le nombre de niveaux d'espaces de noms à afficher. affiche tout
N'affiche pas plus de 3 niveaux d'espace de noms, c'est-à-dire un:deux:trois maxns=3
maxns=0 ⇒ affiche tous les niveaux (valeur par défaut)
case Tient compte de la casse pendant le tri, c'est-à-dire a..z puis A..Z case non sensible à la casse
natsort Utiliser les fonctions de tri naturelles de PHP, c'est-à-dire1,2,10,12 plutôt que 1,10,12,2 natsort tri normal
underline afficher un léger soulignement entre chaque lien pour plus de lisibilité underline rien
label Une étiquette à afficher en haut de la liste PageQuery label=A-Z of All Pages rien
hidemsg Cache n'importe quel message de résultat hidemsg visible
hidejump Cache le lien “Retour en haut de la page” hidejump visible
showcount Affiche le nombre total de liens de page en bas de la liste showcount caché
layout choisir entre l'affichage en tableau ou en colonne
tableau : basé sur un tableau html, compatible avec la plupart des navigateurs
colonne : utilise la nouvelle fonctionnalité de mise en page de colonne CSS3, ne fonctionne pas avec les plus anciens navigateurs11)
layout=column mise en page = tableau
fontsize Fixe la taille de base pour la police de la liste pagequery. Vous pouvez utiliser n'importe qu'elle unité de taille CSS, c'est-à-dire 12px, 1.2em, 80%, etc… fontsize=80% 90%
bullet Style des puces pour les objets de listes (liens)
Choisissez entre aucune, disque, cercle, ou carré (none, disc, circle, square)
bullet=square aucun
Note : Toutes les options sont optionnelles et, laissé à lui-même, le plugin va se rabattre sur
une longue, et très ennuyeuse, liste sur une colonne… donc ça vous intéressera peut-être de prendre les choses en main !

Trier et Regrouper

Quelques conseils pour trier et grouper avec succès : pagequery propose de très nombreuses options de tri, dont la plupart sont prévues pour pouvoir être regroupées. Donc si vous avez l'intention de grouper votre liste sur ses principaux en-têtes, il est plus intéressant de trier de la catégorie la plus large à la plus restreinte.

Par exemple : année ⇒ mois ⇒ nom. L'algorithme de tri va trier d'abord les pages par année, puis à l'intérieur de chaque année par mois, et enfin à l'intérieur de chaque mois par nom. Trier dans l'autre sens ne serait pas très intéressant, car tous les noms sont uniques : donc il n'y aurait pas de “groupes” !

Si vous regroupez le tri ci-dessus, vous obtiendrez le résultat suivant :

La règle de base est : commencez par l'option la moins spécifique et progressez vers la plus précise.

Trucs et astuces

:?: J'ai ajouté de nouvelles pages, mais elles n'apparaissent pas dans ma mâââââgnifique nouvelle liste pagequery. Pourquoi ?I've added new pages but they do not show up in my nice new pagequery list. Why?

:?: J'ai plein de pages 'start' que je ne veux pas voir quand je fait la liste du contenu des espaces de noms…

:?: Je préfère voir le titre des pages plutôt que leur nom. C'est possible ?

:?: J'ai migré le contenu de mon wiki sur une nouvelle version de DokuWiki, et pagequery ne me ramène aucune page, ou seulement après que j'aie modifié les pages.

Quelques exemples

{{pagequery>@namespace;fulltext;sort=a,name;group}}           [version texte entier]

Ou :

{{pagequery>@namespace *;sort=a,name;group;proper;cols=2}}    [version nom de page : permet l'utilisation de regex]

Ceci ramènera les résultats uniquement dans @namespace, et la liste sera triée alphabétiquement sur la première lettre ('sort=a'), puis alphabétiquement ('sort=name') à l'intérieur de chaque lettre. L'option group ne groupera que sur la première lettre (on ne peut pas grouper par nom, puisque chacun est unique).

{{pagequery>@namespace *;sort=a,name;group;cols=3;proper}}
{{pagequery>@namespace *;sort=cyear,cmonth,name;group;spelldate;proper;cols=2;border}}
{{pagequery>@namespace help;fulltext;sort=cyear,cmonth,name;group;spelldate;proper;cols=2}}
{{pagequery>@brouillon [0-9]+.*;sort=name}}
{{pagequery>@happy:go:lucky *;sort=cyear,cdate;group;proper;display={title};cols=2}}
1)
Ça fonctionne très bien avec le plugin columns
2)
On dit aussi “regex”. Faites une recherche Google pour en savoir plus sur les expressions régulières si ça vous intéresse d'utiliser cette puissante fonctionnalité
3)
Tant que vous ne filtrez pas par espaces de nom : voir la note suivante !
4)
Utilisez la syntaxe présentée dans la page des espaces de nom.
5)
sans espace de nom
6)
pas si utile que ça, mais pratique à utiliser dans l'option filter ci-dessous
7)
Pour une explication plus détaillée des regroupements, voir la note après ce tableau
8)
voir ci-dessous
9)
A voir si ça marche en français, ou seulement avec les noms anglais.
10)
Là encore, ce sont les règles de la casse anglaise qui semblent s'appliquer : à vérifier comment ça se traduit en français.
11)
par exemple, IE 6-10
12)
Et lisez le tableau ci-dessus. C'était écrit dedans. Si, si, cherchez bien… :-P
13)
Et lisez le tableau ! A quoi ça sert de faire une doc si personne ne la lit ? :-P
14)
Ceci n'a rien à voir avec pagequery.