Naming conventions

Older argument names are inMixedCase. Newer argument names are in_lower_case, and this style will be used more systematically in Wikidot. Dates are always something_at and user names are always someone_by. Linked fields are always somefield_linked.

Selecting pages

Specify one or more of these selectors to refine the set of pages you select. Each selector adds additional constraints:

Argument

Meaning

pagetype

Select by type of page

category

Select by category

tags

Select by tags

parent

Select by parent page

link_to

Select by outgoing links

created_at

Select by date of creation

updated_at

Select by date of update

created_by

Select by original author

rating

Select by rating

votes

Select by number of votes

offset

Start list after an offset of pages

range

Select a range of pages

name

Select by page name

fullname

Select by fullname

_<data-form-field-name>

Select by a field's value in a data form

Page type selector:

"normal" means pages without underscore in name (default)

"hidden" means pages starting with underscore

"*" means all pages, with or without underscores

Category selector:

"." means current category (default)

"*" means all categories

else, a list of space/comma delimited categories

categories are by default additive (category OR category OR category)

"-category" means exclude pages in this category (AND NOT)

"%%category%%" means the same category as the current page ( if used on a _template page)

Tags selector:

"-" means pages with no tags, visible or invisible

"=" means pages with any of the same visible tags as this page

"==" means pages with the exact same visible tags as this page

else, a list of space/comma delimited tags

tags are by default additive (tag OR tag OR tag)

"-tag" means pages without the tag (AND NOT)

"+tag" means pages with the tag (AND)

Parent page selector:

"-" means pages with no parent page

"=" means siblings of current page (same parent)

"-=" means with different parent than current page

"." means children of current page (parent is this page)

else specifies a single full page name

Outgoing links selector:

enter a single full name of an existing page to select pages that link to that page

Caution: When listing pages from many categories, where some categories have rating type set to + or +/- and others to "stars" (in Site Manager), selecting and ordering by rating may not funtion properly. The solution is to list and order pages from categories having the same rating mode.

"before" means pages up to but not including current (in order after sorting)

"after" means pages after current page (in order after sorting)

"others" means pages except current page

Name selector:

enter a single name (means the name part without the category!) of an existing page to select exact this page of a given category - or pages of different categories if also selected. You can use a dataform field of the current page

"=" means pages that have exact the same name as the current page ( makes sence only with other selected categories)

"s%" means all pages starting with given character "s" or

"s*" means all pages starting with given character "s"

Fullname selector:

enter a single fullname of an existing page to select exact this one page (you can use a dataform field of the current page)

Data Form selector:

Select by a field's value in a data form

Syntax: _data-form-field-name="data-form-field-value"

Example: _gender="m" - select all pages that have 'm' set as the 'gender' field's value in the Data Form

Ordering pages

To order the pages, use:

Argument

Meaning

order

Specify order criteria

Order criteria:

"property" means "ascending by this property"

optionally followed by " desc" meaning "descending"

optionally followed by " desc desc" meaning "ascending", which makes "desc" safe to add after any sort order

default is "created_at desc"

Property

Meaning

name

Order by page name

fullname

Order by category and page name

title

Order by page title

created_by

Order by author screen name

created_at

Order by date created

updated_at

Order by date updated

size

Order by number of characters in page

rating

Order by rating

votes

Order by number of votes

revisions

Order by number of revisions

comments

Order by number of comments

random

Order randomly, cached for 60 seconds

_data-form-field-name

Order by a field in a data form

For example to order by rating in descending order:

order="rating desc"

Caution: When listing pages from many categories, where some categories have rating type set to + or +/- and others to "stars" (in Site Manager), selecting and ordering by rating may not funtion properly. The solution is to list and order pages from categories having the same rating mode.

This example shows how to order pages using a data form field. Note that you must prefix the data form field name with an underscore. This lists all pages from the dictionary category and sorts them by the data form's mainword field (a wiki field type in this example). The body of the module then lists the contents of the mainword field and creates a link to the page.

[!--
Note: Use %%form_raw{fieldname}%% for wiki field types,
%%form_data{fieldname}%% for other field types
--]
[[module ListPages category="dictionary" order="_mainword"]]
%%form_raw{mainword}%%@<&nbsp;>@@<&nbsp;>@([/%%fullname%% see dictionary entry])
[[/module]]

Note that "property asc" is not allowed and unknown order criteria give you the default order, which is "created_at desc".

Type casting for Data Forms fields:
Default order method is sort by text. You can enforce numerical sorting.

Pagination

To control how many items (wiki pages) will be shown in total, and how these are paginated (confusingly, also into 'pages'), use any of:

Argument

Meaning

limit

Limit total items

perPage

Limit per pagination

reverse

Show pages in reversed order

Total limit:

"number" - means limit the total number of selected pages.

by default all pages matching criteria are listed

Pagination limit:

"number" - means limit the number of page items shown on per pagination.

default is 20, maximum is 250.

Reversed display:

"yes" - means show wiki pages from last to first on given page.

Module body

The body of the module allows you to specify how page properties and content is formatted. To control this formatting, you can use these module arguments:

Argument

Meaning

separate

Separation specifier

wrapper

Wrapper specifier

prependLine

Header specifier

appendLine

Footer specifier

Separation specifier:

"yes" means place each page item into a separate container (divs).

"no" means put all items into one container, so they can become a single list, for example.

default is "yes".

With separate set to true, each of the page is compiled (converted from wiki source to HTML) separately. While it is false, wiki compiler is invoked only once on a combined source from all selected pages.

As a result, some page-specific variables and constructs such as iftags can generate different results. iftags, with separate="yes", will be aware of tags of individual pages, while with separate="no" it will read tags of the main page that holds the ListPages module.
Also [[image :first ...]] will only work with separate="yes".

Wrapper specifier:

"yes" means place all items into container (div).

"no" means do not place all items into container (div).

default is "yes".

Header specifier:

"text" means output this text at the start of the list of pages, only if the separation specifier is false.

Footer specifier:

"text" means output this text at the end of the list of pages, only if the separation specifier is false.

Sections head/body/foot

Additionally you can use [[head]], [[body]], [[foot]] sections, which simply replaces prependLine and appendLine. It allows you to create more complex header and footer for ListPages. This is particularly usable with complex table and list creation.

Passing arguments via URL

ListPages lets you create variations of a single list using specially constructed links, consisting of the page URL (link) followed by arguments and values. These are mainly useful to invoke new selectors, and change the ordering or display.

You can pass any arguments in the URL by specifying argument="@URL|default-value" as the argument value and then appending "/name/value" to the URL used to invoke the page. If the URL does not contain a value for the argument, the default is used. Arguments that do not have @URL in their value cannot be set via the URL. The default value is optional: if you use only argument="@URL" and do not provide a value on the URL, then the argument behaves as if it was not set.

The two main ways of using arguments-by-URL are (a) to create links to a page explicitly, on another page and (b) to generate links within the ListPages itself, so it will reshow itself with different configurations. Here is a simple example:

To pass tags with (+/-) "+" need to be encoded with "%2b"+apple,-banana

http://www.wikidot.com/blog/tags/%2bapple,-banana

You can create the URLs manually or within ListPages itself. Some modules also generate compatible URLs.

Editor's note: list of modules that produce compatible URLs should be documented here.

More than one module in the page

Since some of the arguments 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 use the urlAttrPrefix argument. This prepends a text (unique for each of the modules) to the argument names in the URL. So the …/created_at/2008.7 would become …/prefix_created_at/2008.07. If you can set unique prefixes for each of the ListPages instances you would avoid any conflicts.

Deprecated functionality

These arguments and variables can still be used but are disrecommended. You should when possible use the modern replacements. At some future date, deprecated functionality may be removed.

Instead of this

Use this

skipCurrent="yes"

range="others"

categories=

category=

tag=

tags=

tagTarget="pagename"

%%tags_linked|/pagename/tag/%%

date=

created_at=

order="dateCreatedAsc"

order="created_at"

order="dateCreatedDesc"

order="created_at desc"

order="dateEditedAsc"

order="updated_at"

order="dateEditedDesc"

order="updated_at desc"

order="titleAsc"

order="title"

order="titleDesc"

order="title desc"

order="ratingAsc"

order="rating"

order="ratingDesc"

order="rating desc"

order="pageLengthAsc"

order="size"

order="pageLengthDesc"

order="size desc"

rssTitle=

rss=

%%linked_title%%

%%title_linked%%

%%page_unix_name%%

%%fullname%%

%%full_page_name%%

%%fullname%%

%%page_name%%

%%name%%

%%author%%

%%created_by%%

%%author_edited%%

%%updated_by%%

%%user_edited

%%updated_by%%

%%date%%

%%created_at%%

%%date_edited%%

%%updated_at%%

%%description%%

%%summary%%

%%short%%

%%summary%%

%%text%%

%%content%%

%%long%%

%%content%%

%%body%%

%%content%%

ListPages supports a 'default format', where you do not specify any module body and no [[/module]]. This functionality is deprecated and you should avoid using it.