Ceci est une ancienne révision du document !
Index et recherche de pages
Traduction à terminer
La gestion des index et recherche 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 en colonnes, regroupés, triés. 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 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 page apparaisse. Vous pouvez avoir différentes listes pagequery
dans la même page1).
Il peut s'agir de la version simple :
{{pagequery>}}
Ou, plus compliqué :
{{pagequery>[query];fulltext;sort=key:direction,key2:direction;group;limit=10;cols=2;spelldate;proper}}
Ou alors à l'ancienne, et vraiment trop compliqué… :
{{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 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, utiliser * ou .* , ou laissez le simplement à blanc.3) | ^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 * | none |
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 | none |
sort keys: | |||
a, ab, abc | Par 1ère lettre, 2 premières lettres ou 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 | By namespace (without page name) | sort=ns | |
mdate, cdate | By modified/created dates (full) [not grouped] | sort=mdate | |
m[year][month][day] | By [m]odified [year][month][day]; any combination accepted | sort=myearmonthday sort=mmonthday | |
c[year][month][day] | By [c]reated [year][month][day]; any combination accepted | sort=cyearmonthday | |
creator | By page author | sort=creator | |
contributor | By page contributor(s). Note: only first name affects sort order6) | sort=contributor:asc | |
links | By a list of links contained on this page (mainly for filtering). The names (or ids) of all linked pages are joined in one space-delimited string, which can be searched via regex in the filter option below. | ||
backlinks | By a list of backlinks pointing to this page or these pages. Use as per links above. |
||
sort directions: | |||
asc, a | Ascending, e.g. a → z, 1 → 10 | sort=name:asc | asc |
desc, d | Descending, e.g. z → a, 10 → 1 | sort=mdate:desc | |
Note: dates default to a descending sort (most recent date at top), text to ascending sort (A - Z) | |||
filter | Filter the result list by any of the above sort keys, using regular expressions, to include or exclude certain pages | ||
include | Syntax is similar to the sort above: filter=<key>:<expression>,<key2>:<expression2> | filter=creator:harry filter=contrib:.*(harry|sally).* |
|
exclude | To exclude pages from the results put a ^ or ! before the key instead: filter=!<key>:<expression> | filter=!creator:harry |
|
dates | filter= option now recognises real dates and allows you to filter by them correctly. E.g. filter=cdate:3 years ago->3 months ago |
||
A begin and/or end date can be provided, separated by the -> arrow symbols. It uses the PHP strtotime function which accepts a wide array of formats, check the php function for information. | |||
From a certain date until now | filter=mdate:24.1.2009-> |
||
Up to a certain date only | filter=mdate:->24.12.2012 |
||
Last three months only | filter=mdate:3 months ago-> |
||
group | Show a group header for each change in sort keys.7) | group | not grouped |
For example, if you sorted by [myear] (i.e. modified year) then a group header will be inserted every time the year changes (2010…2009…2008…etc…) |
|||
Namespaces are grouped by all sub-namespaces up to the maxns limit8) |
|||
Note: keys that are all unique cannot be grouped (i.e. name, page/id, mdate, cdate) | |||
limit | Maximum number of results to return. 0 = return all (default) | limit=10 | all |
spelldate | Use real month and day names instead of numeric dates. | spelldate | numeric dates |
cols | Number of columns in displayed list (max = 6) | cols=3 | 1 |
proper | Display page names and/or namespaces in Proper Case (i.e. every word capitalised, and no _'s). | none | |
name | Display page names in proper-case | proper=name | |
header | Display group headers in proper-case | proper=header proper=hdr | |
both | Both the above options! | proper=both proper | |
Note: this is different from the UseHeading option in DokuWiki and many other plugins (see display option below) |
|||
border | Show a border around table columns | none | |
none | do not show any borders (default) | border=none | |
inside | show borders between the columns only | border=inside | |
outside | show a border around the whole pagequery table | border=outside | |
both | show borders around both table and columns | border=both border | |
hidestart | Ignore any default start pages in the namespace(s). | hidestart | show start pages |
Note: start pages must be named as per the start setting in your configuration for this option to work correctly! | |||
display | How to display the page links. For example you can display just the page name, page title, page id, page date, or other combination of the page's metadata. | ||
The display= option accepts template-style replacement strings | display={name} ({cdate}) “Name-of-page (20 Jan 2013)” |
||
NOTE: all metadata names must be in curly braces {}, otherwise they are just considered as normal words! | |||
All of the Dokuwiki meta data fields are accepted, plus any pagequery meta columns in use. To get at the nested Dokuwiki metadata use key:subkey. | display={date:created} {title} |
||
See metadata for a list of field names you can use. | |||
snippet | Controls how the page snippet (preview) is displayed: | tooltip | |
tooltip | As a pop-up/tool-tip on each page link | snippet=tooltip snippet | |
The next three options use the following syntax: <format>,<count>,<extent> | |||
<format>: one of the formats listed below: inline, plain, quoted | |||
<count>: to show 1st <count> items in list with an preview | all | ||
<extent>: can be choice of [c]hars, [w]ords, [l]ines, or [~]<stop at> e.g. c? = ? chars, w? = ? words, l? = ? lines, ~? = search up to ? text/char/symbol | all | ||
inline | show in-line with the link | snippet=inline,5,c20 | |
plain | show as simple text below the link (mimimal formatting) | snippet=plain,10,w30 | |
quoted | show in tidy quotation box | snippet=quoted,3,l3 | |
maxns | The number of namespace levels to display. | show all | |
Display no more than 3 namespace levels, e.g. one:two:three | maxns=3 | ||
maxns=0 ⇒ show all levels (default) | |||
case | Honour case when sorting, i.e. a..z then A..Z | case | case insensitive |
natsort | Use PHP's natural sorting functions, e.g. 1,2,10,12 rather than 1,10,12,2 | natsort | normal sorting |
underline | show a faint underline between each link for clarity | underline | none |
label | A label to be displayed at the top of the PageQuery list | label=A-Z of All Pages | nothing |
hidemsg | Hide any empty result messages | hidemsg | visible |
hidejump | Hide the “Jump To Top” link | hidejump | visible |
showcount | Show the total count of page links at bottom of list | showcount | hidden |
layout | choose between table or column layout table: based on html table, compatible with most browsers column: uses new CSS3 column-layout feature, doesn't work in older browsers9) | layout=column | layout=table |
fontsize | Set the base font size for the pagequery list. You can use any CSS size unit, e.g. 12px, 1.2em, 80%, etc… | fontsize=80% | 90% |
bullet | Bullet style for list items (links) Choose from none, disc, circle, or square | bullet=square | none |
Note: All options are optional, and left to its own devices the plugin will default to a long, boring, 1-column list… so you might want to take charge! |
Sorting and Grouping
A few pointers about sorting and grouping successfully. Pagequery offers many sorting options, most of which are designed to be grouped. So if you intend to group your list by its main headers then it makes the most sense to sort from the broadest category to the narrowest.
For example: year ⇒ month ⇒ name
. The sorting algorithm will first sort the list of pages by year
, then the pages within each year will be sorted by month
, and finally the pages within each month will be sorted by name
. Sorting the other way around would not make much sense, as all names are unique: hence there would be nothing to “group”!
If you grouped the above sort it would result in the following arrangement:
- Year
- Month
- Name
- Name
- Month2
- Name
- Name
- etc…
The basic rule is: start with the least specific and work your way to the most specific options.
FAQ and Tips
I've added new pages but they do not show up in my nice new pagequery list. Why?
- You need to turn off page caching for the page containing the list. Put
~~NOCACHE~~
somewhere on the page and you should then see instant updates.
I have many default 'start' pages in my wiki and I don't want to see them when I list the contents of namespaces; how can I make them disappear?
- Just add the
hidestart
option. Make sure that the start option in your configuration corresponds to the start page name you are using!
I would much rather see the page title instead of the page name. How can I enable that?
- Put the
display=title
option somewhere in your pagequery markup
After migrating my wiki contents to a new dokuwiki version, pagequery doesn't list any pages. Only after editing the pages, they show up in pagequery again.
- Use the SearchIndex plugin to rebuild the index of your wiki, or make sure that you copy over the indexes as well as the content. This problem has nothing to do with pagequery itself.
Examples
For example, if you want to list all the pages in a certain namespace by A-Z, the following should do the trick:
{{pagequery>@namespace;fulltext;sort=a,name;group}} [fulltext version]
Or:
{{pagequery>@namespace *;sort=a,name;group;proper;cols=2}} [pagename version: allows regex's]
This would retrieve results from @namespace only (as there is no other search query you would get all the pages), and the list would be sorted by the first letter ('sort=a') then alphabetically ('sort=name') within each letter. The group option will then cause the list to be grouped by the first letter only (you cannot group by name as each one is unique).
If you wanted to see the results in 3 columns and to have the links in “Sentence Case” with no underscores, then add this:
{{pagequery>@namespace *;sort=a,name;group;cols=3;proper}}
Another example, grouping by year created, then month created, then by name, in 2 columns, and displaying the real month name, plus having the links in “Sentence Case” with no underscores, and to top it off: a border around the table columns:
{{pagequery>@namespace *;sort=cyear,cmonth,name;group;spelldate;proper;cols=2;border}}
The same query, but now searching for pages contenting the word “help” (NOTE: fulltext
means search in the page “content” not just its “name”:
{{pagequery>@namespace help;fulltext;sort=cyear,cmonth,name;group;spelldate;proper;cols=2}}
Update: Namespaces are now supported when searching by pagename (pageid) only. Use the same syntax as fulltext search, i.e. @namespace|^namespace. I haven't provide support for relative namespaces yet. In addition, you can use regular expressions when searching by pagename.
E.g. Search for all pages in the “drafts” namespace, listing only files beginning with a number, sorted by name:
{{pagequery>@drafts [0-9]+.*;sort=name}}
Or, all files in the “happy:go:lucky” namespace, sorted by year, then date created, in proper case, in 2 columns, and display the page's title, not the name in the listing:
{{pagequery>@happy:go:lucky *;sort=cyear,cdate;group;proper;display={title};cols=2}}
Hopefully these examples will help to understand the workings of pagequery.
filter
option below