Listpages Module Prev

The ListPages module allows one to select pages based on various criteria and list them in a custom way. ListPages is a very general-purpose module for listing pages in a way similar to the FrontForum module. The module allows custom content formatting, ordering, pagination, support for tags and RSS feed generation.

As shown in the examples it can be used to create blogs, news systems etc. but also quick lists of recently edited or created pages. Thanks to the very flexible tag support one can even use it for content classification and online catalogs.

A new syntax for ListPages is in beta-testing.


attribute required allowed values default description
category no comma- or space-separated names current category names of the categories that pages would be fetched from, use category="*" to fetch pages from all categories; by default pages from the current category are selected (i.e. the category that the page containing the module belongs to); also aliased as categories
tags no comma- or space-separated tag names with + and - modifiers,
or @URL
none lists tags that are used as a criteria to select pages, the "+" before the tag makes it required, "-" means "without a tag" and tags without modifiers translate to "pages that have any of those tags";
a special tag "=" adds all the tags that are present in the current page
tagTarget no name of a landing page for clickable tags none if this parameter is set to a name of a wiki page, all tags (generated with %%tags%% will be clickable and will lead to this page
date no year or year.month
or last n unit where n - number (1 if skipped), unit - day(s), week(s), month(s)
or @URL
none adds a date criteria to selection, valid values are e.g. 2007 (to select only pages created in 2007), 2008.05 (to select only pages from May 2008)
parent no category:pagename none restricts results to children of specified page.
range no before, after, others none "before" means pages up to but not including current (in order), "after" means pages after current page (in order), "others" means pages except current page.
skipCurrent no true, false, yes, no or @URL no skips the current page from the list
perPage no number or @URL 20 number of items (pages) to display on one screen (when paginating)
limit no number or @URL none limits the total number of selected pages
order no dateCreatedDesc
or @URL
dateCreatedDesc selects ordering of the pages, the default one is: newest pages first; random gives you pages in random order, but the result is cached for 60s
separate no true, false, yes, no true if true page items are placed in individual containers, but if false — they are rendered without any breaks or splits, which allows to create e.g. simple lists containing titles of recently edited pages (see below)
prependLine no wiki-formatted string if separate="false", this line of wiki text will be prepended to the processed list of pages; one can use it e.g. to generate table headers
appendLine no wiki-formatted string if separate="false", this line of wiki text will be appended to the processed list of pages
urlAttrPrefix no any alphanumeric none prefix for the parameters passed via the URL; handy when more ListPages modules are on the page
rss no any text none title for the RSS feed; if not given, the corresponding RSS feed will not be linked; also aliased as rssTitle for compatibility
rssHome no any URL the main wiki page feed source page — you can use it with %%linked_channel_title%% variable in Feed module
rssDescription no any text description of the site feed description


Some of the attributes accept a special @URL value which tells the module to read the value of the parameter from the URL. This is an advanced use but is handy in many situations.

Parameters and their values in URL are delimited by slashes (/). So if there is a ListPages module on a page "blog" at a given wiki and you want to read date from the URL, you need to put

[[module ListPages date="@URL"]]

and the module will read the date parameter from the properly-constructed URL, e.g.

Several parameters can be combined in the URL like this:

The URLs need to be created manually at this point.

More than one module in the page

Since some of the parameters can be passed in the URL of the request there might be conflict when more than one ListPages module is present in the page. One most likely conflict can occur when both modules use pagination — clicking "next" on one of them would also affect the other.

To prevent such conflicts the urlAttrPrefix parameter can be used. It simply prepends a text (unique for each of the modules) to the parameter names in the URL. So the …/date/2008.7 would become …/prefix_date/2008.07. If you can set unique prefixes for each of the ListPages instances you would avoid any conflicts.

A very simple example follows:

[[module ListPages perPage="5" limit="15" urlAttrPrefix="prefix1"]]
[[module ListPages perPage="5" limit="15" urlAttrPrefix="prefix2"]]

Note Template In Modules

Listpages Module Prev

Page Selection

Note Template In Modules

Listpages Module Prev

Page Selection

Item format

A custom format for displaying news items can be chosen. To specify a custom format one should use module invocation:

[[module ListPages category="blog"]]
<custom format>

where the inner <custom format> element is any block of text following the wiki-syntax, where special variables can be used:

variable aliases description
%%title%% title of the page
%%linked_title%% %%title_linked%% title of the page linked to the page itself
%%page_unix_name%% %%full_page_name%% unix name of the page — the one that is displayed in the URL of a page
%%page_name%% name of the page without the category
%%category%% name of the category of the page
%%link%% URL pointing to the page
%%author%% prints author that created page
%%author_edited%% %%user_edited%% prints author that recently edited the page
%%date%% prints the date the page was created
%%date|format%% prints date with a custom format. Most tokens from php's strftime are accepted. You may find the howto contributed by community useful.
%%date_edited%% prints the date the page was recently edited
%%date_edited|format%% same as above, with custom formatting
%%description%% %%short%%, %%summary%% short summary of page, equivalent to %%content{1}%% if there is a separator (====) within the page, otherwise a short version will be automatically generated (e.g. by using the first paragraph)
%%first_paragraph%% displays the first paragraph of a page.
%%content{n}%% selects and displays the n-th content segment if the content is split using the ==== separator
%%content%% %%text%%, %%long%%, %%body%% full content of the page
%%preview%% first 200 characters of the post
%%preview(n)%% first n characters of the post (n — any positive integer number)
%%tags%% displays space-separated list of tags for a given page
%%rating%% displays a number — rating of the page
%%comments%% displays number of comments to the page

The default format is:

+ %%linked_title%%

by %%author%% %%date|%O ago (%e %b %Y, %H:%M %Z)%%


If separate is set to true (default), each page item is embedded in the HTML <div class="list-pages-item">…</div> element.


Blog-like front page

To make a front page for a blog structure, i.e. make a list of pages from the category blog ordered by "most recent first" and show only a short version of their content (i.e. first paragraph or first section if the ==== separator is used) one can do it with the code:

[[module ListPages category="blog" rss="My Blog Posts"]]

The default format might be just enough for it, but one can easily create a custom format using the formatting tags above:

[[module ListPages category="blog" rss="My Blog Posts" tags="technology news +apple -funny"]]
+++ %%linked_title%%

by %%author%% %%date%%


tags: %%tags%%

In both examples we are pointing to an RSS feed with recent pages from the blog: category and we are setting a title for this blog feed.

The tag string (i.e. tags="technology news +apple -funny") means:

  • select pages that have any of tags technology or news
  • AND pages must have the "apple" tag
  • AND pages must not have the "funny" tag applied

There is also a special tag: = (equal sign). It adds all the tags that are present in the current page, without +/-. So if a current page has tags: blog wikidot, the tags="=" is equivalent to tags="blog wikidot".

It can be used to create a list of similar pages. You can combine the = tag with other tags. If = is the only listed tag (i.e. explicitly tags="=") it implies skipCurrent="yes" so that you can use simply:

+ Similar pages

[[module ListPages tags="="]]

Short list of recently edited pages

[[module ListPages  category="*" limit="10" separate="false" order="dateEditedDesc"]]
* %%linked_title%% _
%%date_edited|%O ago%%

This piece of code selects pages from all categories, number of pages is limited to 10, it switches off the separate so that the list can be smoothly processed (if separate="true", each page item would create a separate, one-element list), we choose not to create an RSS feed for the selection and the pages are ordered by the date of last edit (most recent first).

The custom format should look familiar, and here is the result:

Advanced processing is possible thanks to the prependLine and appendLine parameters. When combined with separate="false", they allow creating a custom wiki-formatted block from the page elements. Look at an example:

[[module ListPages separate="false" prependLine="||~ Page||~ Date created||~ Created by ||" limit="5"]]
|| %%linked_title%% || %%date%% || %%author%% ||
Page Date created Created by
Note Template In Modules 02 Jun 2014 10:33 SquarkSquark
Listpages Module Prev 02 Jun 2014 10:31 SquarkSquark
Page Selection 29 Apr 2014 09:32 Anonymous

Random page(s)

Using order="random" one can easily pull a random page from a wiki, e.g.

Random pages

[[module ListPages  category="doc" limit="5" separate="false" order="random"]]
* %%linked_title%%

Single random page

[[module ListPages  category="doc" limit="1" order="random"]]

Result of random listing is cached for 1 minute, so if you are reloading a page every few seconds the random choice will not change. After a minute however a new result is picked up.