====== Index et recherches de pages ======

<WRAP center round todo 60%>
Traduction à relire pour corriger les coquilles et compléter ce qui n'est éventuellement pas clair.
</WRAP>


La gestion des index et des recherches de pages se fait grâce au plugin [[doku>plugin:pagequery|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 [[doku>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 :
  * Faire la liste de toutes les pages de votre wiki dans un bel index alphabétique, ou par année/mois
  * Faire une liste des pages récemment modifiées
  * Faire la liste des pages qui discutent d'un sujet particulier (grâce à la recherche dans le texte)
  * Faire la liste des pages créées par un utilisateur donné
  

===== 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 page((Ça fonctionne très bien avec le [[doku>plugin:columns|plugin columns]])).

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 :
<code>
{{pagequery>query;
  fulltext;
  sort=key:direction,key2:direction;
  group;
  limit=100;
  cols=6;
  spelldate;
  proper;
  border=inside;
  hidestart;
  case;
  natsort
}}
</code>

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ères//((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é)) dans les recherches de nom de page. Pour voir toutes les pages, utilisez * ou .* , ou laissez simplement à blanc((Tant que vous ne filtrez pas par espaces de nom : voir la note suivante !)). |''^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 [[doku>:search|la recherche dans le texte]], c'est-à-dire : ''^ ou -ns:'' signifie exclure, ''@ ou ns:'' signifie inclure. |''^:work @:home:games *''  |  //rien//  |
|       |Les [[doku>:namespaces|espaces de noms]] relatifs (.) et parent (..) sont aussi compatibles((Utilisez la syntaxe présentée dans la page des espaces de nom.)).  |||
|       |//**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 [[doku>: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 page((sans espace de nom)) //[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 tri((pas si utile que ça, mais pratique à utiliser dans l'option ''filter'' ci-dessous))|''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 [[http://www.php.net/manual/en/datetime.formats.php|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.((Pour une explication plus détaillée des regroupements, voir la note après ce tableau)) |''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 ''maxns''((voir ci-dessous)) |||
|        |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.((A voir si ça marche en français, ou seulement avec les noms anglais.)) |''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)((Là encore, ce sont les règles de la casse anglaise qui semblent s'appliquer : à vérifier comment ça se traduit en français.)). |  |  //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èle|''display={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 [[doku>devel:metadata|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-à-dire''1,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 navigateurs((par exemple, IE 6-10))  |''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 :
  * Année
    * Mois
      * Nom
      * Nom
    * Mois2
      * Nom
      * Nom
      * etc...

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?
  * Il faut désactiver les caches pour la page contenant la liste. Ajoutez <code> ~~NOCACHE~~ </code> n'importe où dans la page, et vous devriez voir les mises à jour instantanément.

:?: J'ai plein de pages 'start' que je ne veux pas voir quand je fait la liste du contenu des espaces de noms...
  * Utilisez l'option ''hidestart''. Et vérifiez que l'option //start// de votre configuration correspond bien aux noms de page start que vous utilisez !((Et lisez le tableau ci-dessus. C'était écrit dedans. Si, si, cherchez bien... :-P))

:?: Je préfère voir le titre des pages plutôt que leur nom. C'est possible ?
  * Ajoutez l'option ''display=title'' quelque part dans votre pagequery.((Et lisez le tableau ! A quoi ça sert de faire une doc si personne ne la lit ? :-P))

:?: 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.
  * Utilisez le [[doku>plugin:searchindex|plugin SearchIndex]] pour reconstruire l'index de votre wiki, ou vérifiez que vous avez copié les index en même temps que le contenu.((Ceci n'a rien à voir avec pagequery.))


===== Quelques exemples =====
  * Afficher toutes les pages d'un espace de nom par ordre alphabétique :

  {{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).

   * Pour voir le résultat sur 3 colonnes et avoir les liens en "Casse de phrase" sans soulignement :

  {{pagequery>@namespace *;sort=a,name;group;cols=3;proper}}

   * Grouper par //année// puis //mois de création//, et ensuite par //nom//, sur 2 colonnes, en affichant le vrai nom du mois, plus les liens en "Casse de phrase" sans soulignement, et pour couronner le tout : une bordure autour des colonnes du tableau :

  {{pagequery>@namespace *;sort=cyear,cmonth,name;group;spelldate;proper;cols=2;border}}

   * La même chose, mais en ne ramenant maintenant que les pages avec le mot "help" (NOTE : ''fulltext'' signifie qu'on cherche dans le contenu de la page, et pas seulement dans son nom) :

  {{pagequery>@namespace help;fulltext;sort=cyear,cmonth,name;group;spelldate;proper;cols=2}}

   * Chercher toutes les pages de l'espace de nom "brouillon", en ne ramenant que les fichiers dont le nom commence par un nombre, et triés par nom :

  {{pagequery>@brouillon [0-9]+.*;sort=name}}

   * Et si c'est dans l'espace de nom "happy:go:lucky", en triant par année puis date de création, dans la jolie casse, sur 2 colonnes, et en affichant le //titre// de la page plutôt que le //nom// :

  {{pagequery>@happy:go:lucky *;sort=cyear,cdate;group;proper;display={title};cols=2}}




{{tag>Wiki Syntaxe}}