THIS PLUGIN IS NO LONGER MAINTAINED If you would like to take over as the maintainer please contact me.

VERY IMPORTANT: the plugin requires PHP 5.3 or higher to function. Refer to Plugins on how to install plugins manually.

NEWS—2013-10-07: new popup syntax “cheatsheet” now available from the Edit Toolbar via a new button! New language also: Dutch.

NEWS—2013-10-06: new filtering options: links (page links), and backlinks (backlinks to the page). These are space delimited lists of page ids that can be filtered using the filter= regex feature (see below for details).

2013-03-27: Weatherwax compatible; group header bugfix

2013-03-08: significant update

• compatible with Adora Belle and PHP 5.4.
• display option: further changes. All metadata/sorting fields can be used to create the displayed page link. Put fields in {}. E.g. “{name} ({mdate})” would produce: “Page-name (01-Jan-1970)” where mdate is the modified date of the page.
• new layout option: choose between table or column.
  • table: old-school html tables are used to create the multiple columns.
  • column: CSS3 column-layout is used instead. This requires a more up-to-date browsers, but works better when the window is re-sized.
  • quite a few smaller options have been re-named for clarity (see syntax table below).
• filter option now handles date more elegantly. You can filter the list based on dates, before, after, between, using real numeric dates, or even time periods in words (last week, 2 days ago, etc…)
• Many small tweaks, and overall code clean up.

Development history on GitHub:

• Merge pull request #51 from pacobyte/php7_array_declaration_fix (2018-01-22 10:51)
• Increase compatibility with PHP 7 (2018-01-22 02:37)
• Merge pull request #35 from topical/master (2015-03-19 18:40)
• fix caching (2015-03-19 15:06)
• Update plugin.info.txt (2014-11-18 06:39)
• Merge pull request #33 from sawachan/ja-lang (2014-08-16 09:56)
• Create lang.php (2014-08-04 08:04)
• Merge pull request #32 from gamma/master (2014-07-16 12:06)
• Fix for PHP Strict (2014-07-15 11:55)
• Fix for PHP Strict (2014-07-15 11:55)

If you are not running PHP 5.3, then you can still use the previous version; the options are not as extensive but useful nonetheless. There will be no further updates to this version.

Please report any bugs and problems on GitHub if possible, if not on the pagequery discussion page or the forum. Just follow the instructions at the top.

There 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.

On the surface it may appear to fill a similar role to the really excellent 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.”

Features

• Create all sorts of indexes for your wiki: A-Z, recent, created by, authored by, start pages
• Search all the pages in your wiki
• Or limit your search to a specific namespace
• Search for words in the page content as well–fulltext!
• Search by page name using regular expressions
• Sort lists by A-Z, by name, by year, by month, by day, by author, and many other options
• Split your list into groups, with headers above each one: A..Z, 2010…2009, Jan..Dec, author's name
• Display links based on the page's title instead of page name
• See a useful content preview tool-tip when you hover over each page link
• OR create a great blog-like start page, where links are followed by a neat snippet of the page content
• Make full use of space: display your list of links in columns
• Put borders around the columns for clarity

Nothing 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.

Some possible uses:

• Listing all the pages in your wiki in a nice A-Z index, or a By Year/Month index
• A recently modified list of pages
• Listing pages that discuss a particular subject (via full-text search)
• Listing all pages created by a certain user

Here's an example of all the pages in a namespace listed by date modified, and grouped by year and month:

Insert the pagequery markup in the page text wherever you want your list to appear. You can have different pagequery lists on the same page¹⁾.

It could be simple:

{{pagequery>}}

Or complicated:

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

Or just plain ol' too complicated…:

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

NEW: the syntax can now be spread over multiple lines for clarity, rather like a programming language. Any whitespace is simply ignored. E.g.

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

Yes, I know the syntax table below is overly long and looks intimidating—hopefully if you persevere and start learning how to use it you'll soon be asking if it can be adapted to your particular needs…as many people already have on the discussion page. Well, it's become pretty flexible over time, but all these options need to be defined somewhere, hence the long list below… However they all have default values so you can start using them only when you realise a specific need.

As a general rule the different options are separated by semi-colons (;), different values (e.g. within the sort or filter) are separated by comma (,); multi-part values by colon (:).

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.

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.

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.

See the separate discussion page.