1PageQuery Plugin
2======
3
4
5Overview
6------
7There are many different page listing / navigation plugins on the [[:plugin]] page, all trying to serve different needs.  Pagequery tries to unify many of the ideas into a compact all-in-one method of listing your wiki pages, by name, title, a-z index, by date, by year, month, day, by namespace or by creator; ...and do it quickly.
8
9On the surface it may appear to fill a similar role to the really excellent [[plugin:indexmenu|IndexMenu]], however pagequery's aspirations are not as lofty or elaborate.  IndexMenu focuses on displaying namespaces, and the pages within.  allowing you to sort the namespaces and files by many options, and actively navigate and manipulate this index.  Pagequery's purpose is __displaying lists of pages__: yes, you can sort by namespace if you wish, however the main goal is to search for and list pages in any order, and then neatly display them in groups (A-Z, by year, by month, etc...) and in addition in columns — to make best use of space.  If you try both of them you'll quickly see that they //"scratch different itches."//
10
11**Features**
12  * Create all sorts of indexes for your wiki: A-Z, recent, created by, authored by, start pages
13  * Search all the pages in your wiki
14  * Or limit your search to a specific namespace
15  * Search for words in the page content as well--fulltext!
16  * Search by page name using //regular expressions//
17  * Sort lists by A-Z, by name, by year, by month, by day, by author, and many other options
18  * Split your list into groups, with headers above each one: A..Z, 2010...2009, Jan..Dec, author's name
19  * Display links based on the page's title instead of page name
20  * See a useful content preview tool-tip when you hover over each page link
21  * OR create a great blog-like start page, where links are followed by a neat snippet of the page content
22  * Make full use of space: display your list of links in up to six columns
23  * Put borders around the columns for clarity
24
25Nothing worthwhile is built in isolation: pagequery has been built on the shoulders of giants — i.e. the DokuWiki core functions.  Under the skin it makes shamefaced use of the excellent built-in page and full-text [[:search]] functions available in DokuWiki, so there's no new search syntax to learn.  However it does bring a little something new to the mix by providing powerful sorting and grouping options.
26
27Some possible uses:
28  * Listing all the pages in your wiki in a nice A-Z index, or a By Year/Month index
29  * A recently modified list of pages
30  * Listing pages that discuss a particular subject (via full-text search)
31  * Listing all pages created by a certain user
32
33Here's an example of all the pages in a namespace listed by date modified, and grouped by year and month:
34
35"http://pagequery.googlecode.com/files/pagequery%20screenshot.png"An example of a navigation page
36
37Syntax and Usage
38------
39
40Insert the pagequery markup in a page wherever you want your list to appear. You can have more than one ''pagequery'' list on one page((works well with the [[plugin:columns|columns plugin]])).
41
42It could be simple:
43  {{pagequery>}}
44
45Or complicated:
46  {{pagequery>[query];fulltext;sort=key:direction,key2:direction;group;limit=10;cols=2;inwords;proper}}
47
48Or just plain ol' __too__ complicated:
49  {{pagequery>[query];fulltext;sort=key:direction,key2:direction;group;limit=100;cols=6;inwords;proper;snippet=5;border=inside;nostart;case;natsort}}
50
51
52Examples
53------
54
55For example, if you want to list all the pages in a certain namespace by A-Z, the following should do the trick:
56  {{pagequery>@namespace;fulltext;sort=a,name;group}}           [fulltext version]
57Or:
58  {{pagequery>@namespace *;sort=a,name;group;proper;cols=2}}    [pagename version: allows regex's]
59
60This 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).
61
62If you wanted to see the results in 3 columns and to have the links in "Sentence Case" with no underscores, then add this:
63
64  {{pagequery>@namespace *;sort=a,name;group;cols=3;proper}
65
66Another 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:
67
68  {{pagequery>@namespace *;sort=cyear,cmonth,name;group;inwords;proper;cols=2;border}}
69
70The same query, but now searching for pages contenting the word "help" (NOTE: ''fulltext'' means search in the page "content" not just its "name":
71
72  {{pagequery>@namespace help;fulltext;sort=cyear,cmonth,name;group;inwords;proper;cols=2}}
73
74**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.
75
76E.g. Search for all pages in the "drafts" namespace, listing only files beginning with a number, sorted by name:
77
78  {{pagequery>@drafts [0-9]+.*;sort=name}}
79
80Or, all files in the "happy:go:lucky" namespace, sorted by year, then date created, in proper case, in 2 columns, and use the page title, not the name in the listing:
81
82  {{pagequery>@happy:go:lucky *;sort=cyear,cdate;group;proper;cols=2;title}}
83
84Hopefully these examples will help to understand the workings of pagequery.
85
86
87