ListPages Module

Description

The goal of the work is to create a very general-purpose module for listing pages in a way similar to the FrontForum module. The module would allow custom content formatting, ordering, pagination, support for tags and RSS feed generation. It could be possibly used to create blogs, news systems etc.

Details

The main scenario for this module is blogging, though there are many scenarios we want to make using ListPages. Currently bloggers are using two approaches when creating blogs on Wikidot:

  1. either they make it forum-based, where every new blog post is a new forum thread. Then they are using the FrontForum module to make the front-page listing of new articles,
  2. or they are using category-based structures, where every new blog post is a new page in a given category (e.g. blog:).

We find the second approach much more wiki-like and want to develop the complete blogging suite based on wiki categories.

The ListPages module would allow one to:

  • define selection criteria for pages (which pages to select) based on
    • category(-ies)
    • tags
    • date range (by year or month, e.g. all pages from May 2008)
    • ordering by date created, last edit
  • define how to display them
    • format defined in a similar way that the FrontForum does
    • aware of content sections (the ==== delimiter), can easily create short and full versions
  • point to the RSS feed that lists the pages too.

Proposed documentation for the module

Description

The ListPages module allows one to select pages based on various criteria and display them in a custom way.

Attributes

attribute required allowed values default description
category yes 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 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"
date no year or year.month
(numbers)
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)
perPage no number 20 number of items (pages) to display on one screen (when paginating)
limit no number none limits the total number of selected pages
order no dateCreatedDesc
dateCreatedAsc
dateEditedDesc
dateEditedAsc
titleDesc
titleAsc
lengthDesc
lengthAsc
dateCreatedDesc selects ordering of the pages, the default one is: newest pages first
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 separation="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 separation="false", this line of wiki text will be appended to the processed list of pages
rssEmbed no true, false, yes, no true if true, a link to the RSS feed (with the same page selection as in the module) will be generated and placed within the web so that news readers and browsers can discover this; the link is not visible for humans
rssShow no true, false, yes, no true if true, a link to the RSS feed (with the same page selection as in the module) will be generated and placed under the selection of pages
rssTitle no any text "RSS feed" title for the RSS feed; if rssShow is true, the title will appear next to the RSS icon below the 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>
[[/module]]

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%% unix name of the page — the one that is displayer in the URL of a page
%%link%% URL pointing to the page
%%author%% prints author of 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
%%tags%% displays space-separated list of tags for a given page

The default format is:

+ %%linked_title%%

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

%%short%%

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

Examples

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" rssTitle="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" rssTitle="My Blog Posts" tags="technology news +apple -funny"]]
+++ %%linked_title%%

by %%author%% %%date%%

%%content%%

tags: %%tags%%
[[/module]]

In both examples we are pointing to an RSS feed with recent pages from the blog: category and we are setting a tittle 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

Short list of recently edited pages

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

This piece of code selects pages from all categories, number of pages is limited to 10, it switches of the separation 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" rssShow="false" prependLine="||~ Page||~ Date created||~ Created by ||"]]
|| %%linked_title%% || %%date%% || %%author%% ||
[[/module]]
Page Date created Created by
Karma 27 May 2008 10:22 michal-frackowiakmichal-frackowiak
Blogging Suite 20 May 2008 09:15 michal-frackowiakmichal-frackowiak
ListPages Module 20 May 2008 04:48 michal-frackowiakmichal-frackowiak
Templates 13 May 2008 07:25 michal-frackowiakmichal-frackowiak

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