ListPages et al
nav_first.pngFirst: thread:131
HTML Block
Edited: 11 Oct 2012 12:06 by: James Kanjo
Comments: 0
Tags:
nav_prev.pngPrevious: thread:125
Consistent Tool Arguments
Edited: 12 Nov 2009 12:34 by: pieterh
Comments: 0
Tags:
Last: thread:112
Image Module
Edited: 12 Nov 2009 12:22 by: pieterh
Comments: 0
Tags:
nav_last.png
Next: thread:136
Ten Core Principles
Edited: 12 Nov 2009 12:27 by: pieterh
Comments: 0
Tags:
nav_next.png

Steven HeynderickxSteven Heynderickx wrote on 10 Nov 2009 15:41

Update: most of the design specified here has been implemented, and so I'm freezing this page, and the discussion, and starting a new page for improvements to what we have already made. — Pieterh 2009-09-24

ListPages is one of the key modules but needs polishing and extension. This design sketch is for a set of incremental improvements to ListPages and related modules. Normal indicates functionality already present; bold indicates functionality scheduled for next delivery; italics indicate functionality not yet scheduled.

Standard selection

Applies to ListPages, CountPages:

  • Select by category: category="category-selector"
  • Select by tag: tags="tag-selector"
  • Select by date: created_at="created-at-selector"
  • Select by parent: parent="parent-selector"
  • Select by page type: pagetype="pagetype-selector"
  • Select by range: range="range-selector"
  • Select by author: created_by="created-by-selector"
  • Select by offset: offset="offset-selector"
  • Select by rating: rating="rating-selector"
  • Select by backlink: backlink="backlink-selector"

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)

Tag 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)

Created-at selector:

  • "=" means created on same day as current page
  • "yyyy" means specified year
  • "yyyy.mm" means specified year and month
  • "last n unit" where 'n' is a count (defaults to 1) and unit is "day", "week", or "month"
  • optionally prefixed by ">", "<", "=", "<=", ">=", "<>" (default is "=")
  • selector takes into account UTC+- site settings (new site manager setting)

Created-by selector:

  • "=" means by created by author of current page
  • "-=" means by not created by author of current page
  • else, a single user name

Parent selector:

  • "-" means pages with no parent
  • "=" 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

Page type selector:

  • "normal" means pages without underscore in name (default)
  • "hidden" means pages starting with underscore
  • "*" means all pages, with or without underscores

Range selector:

  • "." means current page
  • "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 (replaces old skipCurrent)

Offset selector:

  • "n" means do not show the first n pages (default is 0)

Rating selector:

  • "n" means pages with rating equal to n
  • "=" means pages with same rating as current page
  • optionally prefixed by ">", "<", "=", "<=", ">=", "<>" (default is "=")

Backlink selector:

  • "-" means pages with no backlink (i.e. orphaned pages)
  • else specifies a list of space/comma delimited category:page values

Standard sorting

Applies to ListPages:

  • specify order criteria: order="order-criteria"

Order criteria:

  • property name
  • optionally followed by " desc" meaning "descending"
  • optionally followed by " desc desc" meaning "ascending", which makes "desc" safe to add after any sort order
Property Meaning
name Order by page name (numeric if autonumbered)
fullname Order by category and page name
title Order by page title
parent Order by parent name
created_by Order by author screen name
created_at Order by date created
updated_at Order by date updated
commented_at Order by date of last comment
size Order by number of size
rating Order by rating
revisions Order by number of revisions
children Order by number of children
comments Order by number of comments
watchers Order by number of watchers

For example to order by rating in descending order:

order="rating desc"

Passing arguments by URL

An advanced use of ListPages lets you create variations of a single list using specially constructed links (consisting of the page 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:

[[module ListPages category="@URL|design"]]
%%name%% in category %%category%%
[[/module]]

Output order

By default pages are output in the sort order. To reverse the order use:

  • reverse="yes" — outputs pages in reversed order

Page properties

These page properties would be available both in ListPages content, and in live template content:

Property Meaning
Page lifecycle
%%created_at%% Date page was created
%%created_by%% User who created page
%%created_by_linked%% Icon and link to user who created page
%%updated_at%% Date page was updated (edited, tagged, parented)
%%updated_by%% User who updated page
%%updated_by_linked%% Icon and link to user who updated page
%%commented_at%% Date of last comment
%%commented_by%% User who made last comment
%%commented_by_linked%% Icon and link to user who made last comment
Page structure
%%name%% Page name without category
%%category%% Page category if any
%%fullname%% Page name with category if any
%%title%% Page title
%%title_linked%% Link to page showing title as text
%%parent_name%% Parent page name without category
%%parent_category%% Parent page category if any
%%parent_fullname%% Parent page name with category if any
%%parent_title%% Parent page title
%%parent_title_linked%% Link to Parent page showing title as text
%%link%% URL pointing to page
%%content%% Page content
%%content{n}%% Numbered content section
%%summary%% Short content, first paragraph
%%tags%% Page visible tags (not starting with underscore)
%%tags_linked%% Page visible tags linked to system:page-tags/tag/{tag}
%%tags_linked|link_prefix%% Page visible tags linked to link_prefix{tag}
%%_tags%% Page hidden tags (starting with underscore)
%%_tags_linked%% Page hidden tags linked to system:page-tags/tag/{tag}
%%_tags_linked|link_prefix%% Page hidden tags linked to link_prefix{tag}
%%field{name}%% Field value from page data form
%%field_display{name}%% Displayed field value if different
Page reporting
%%children%% Number of child pages
%%comments%% Number of comments on page
%%views%% Number of times page has been viewed
%%watchers%% Number of watchers on page
%%size%% Number of characters in page
%%rating%% Page rating value
%%revisions%% Number of revisions to page
%%index%% Page index in ListPages output + offset (1 to %%total%%)
%%total%% Total number of pages in ListPages output (highest %%index%%)
%%history%% Summary of last edits to page
Current context
%%site_title%% Title of current site
%%site_name%% Wikidot Unix name for site
%%site_domain%% Active domain name of current site
%%user%% Current logged user name if any, else "anonymous"
%%user_linked%% Icon and link to current logged user, if any
%%user_status%% Returns anonymous, member, moderator, administrator or master-administrator
%%now%% Current date taking into account site UTC +- settings

Property selection:

  • %%property-name{n}%% - when the property occurs more than once, selects instance 'n', where '1' is the first instance. Applies to content.

Output formatting:

  • %%property-name(n)%% - truncates the property to a maximum of 'n' characters. Applies to all string properties.
  • %%property-name?value%% - provide default value if property name is empty. Applies to all string properties.

Date formatting:

  • All _at fields are dates and allow a custom format via the |format specifier.

Tag linking:

  • If no link_prefix is specified, tags link to system:page-tags/tag/name-of-tag
  • If link_prefix is specified, tags link to link_prefixname-of-tag (colors irrelevant)
  • Examples
if syntax is: "shiny" tag will link to:
%%tags_linked%% /system-page-tags/tag/shiny
%%tags_linked|system-page-tags/tag/%% /system-page-tags/tag/shiny
%%tags_linked|interesting-list/category/%% /interesting-list/category/shiny
%%tags_linked|player:%% /player:shiny
%%tags_linked|very_%% /very_shiny
%%tags_linked|http://myothersite.wikidot.com/see-also/tag/%% http://myothersite.wikidot.com/see-also/tag/shiny

Start a new sub-thread

We discourage direct comments on this thread: to discuss it, please start a sub-thread.

Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License