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:
- 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,
- 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:
- Virtual Machine for Development
25 Oct 2010 08:16 - ListPages Module
29 May 2008 22:58 - Blogging Suite
28 May 2008 10:31 - Top Bar Menu
27 May 2008 12:36 - Welcome to dev.wikidot.org!
27 May 2008 10:46 - Karma
27 May 2008 10:22 - Templates
14 May 2008 14:22 - Contribute
18 Apr 2008 11:49 - WikiML XML Reference
12 Mar 2008 11:27 - Project repository
22 Feb 2008 17:21
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 | |
Blogging Suite | 20 May 2008 09:15 | |
ListPages Module | 20 May 2008 04:48 | |
Templates | 13 May 2008 07:25 |
Consider instead of tagMode:
- by default, tags are OR
- use +tag to make a tag mandatory in the selection
- use -tag to make a mandatory negative selection
For category, the default should be the current category, so that if I use ListPages in the blog: category the default category is "blog:"
To select all categories I should be able to use "*".
For the Rss options, use consistent naming:
Instead of 'separate' with default 'true', use 'breaks' with default 'false'. It's not nice to have defaults that are 'true', in general a default should be 'off' until requested to be 'on'.
Portfolio
OK for almost everything, but the separate thing should stay as it is. The option affects how the whole list is compiled and you basically do want to process pages separately. However it should be set to false e.g. when you generate a list of pages as a bulleted list — see the example above.
Please everyone test this module and comment on the functionality, either here or on our dev list.
m.
Michał Frąckowiak @ Wikidot Inc.
Visit my blog at michalf.me
> Please everyone test this module and comment on the functionality
Could you perhaps support ListPages configurations like the following? Thanks!
Module ListPages seems to report wrong %%date%% values.
See [http://community.wikidot.com/bugs:module-listpages].
You could consider supporting a "categories" attribute instead or in addition to the "category" attribute. That would also be more consistent with the existing "tags" attribute.
Else you might consider to issue a warning if a non-existing attribute is specified. [[module ListPages categories="_default howto" ...]] works now, but doesn't list those two categories, but the current page's category.
+1 on "categories" for consistency.
A warning on unknown attributes would be generally useful. Also, later, help in the editor for entering module arguments.
Portfolio
1. When inserting %%content{1}%%, %%description%%, or %%short%%, Wikidot should remove all formatting (e.g. <h1>) and also line terminators. It is impossible to show this, for example:
2. There is no way to ask for the first paragraph if one uses content separators. That is, adding a content separator anywhere into the page changes the behaviour of %%short%% and %%description%%, which is not good. I'd suggest that if people want to show the first content section they can use this explicitly:
and if they use %%description%% or %%index%% then that should always take the first paragraph of text.
3. We eventually need selection on page rankings and parent page, so we can deprecate all these modules:
4. We need the %%comments%% field in order to properly show blog entries and news stories.
5. When showing %%content{n}%% in a ListPages module on a page with content sections, it shows the data from the current page rather than the listed page. It should show the content section from the listed page.
Portfolio
Thanks for all the valuable comments!
I will try to answer most of them below here:
%%date%% issue
@Erich: thanks, dates are working fine now.
categories parameter and not recognized parameters.
OK, now categories is an alias to category. I think we can make warnings about wrong parameters later - the module took a bit more time than expected anyway. But certainly this is a good thing.
More on custom formatting
@Erich - unfortunately it is not possible to do custom formatting (i.e. table headers) the way you propose it because modules are processed at a different moment than the rest of the page. However I have a solution that does work: look at the prependLine and appendLine parameters. This works fine for me:
@Pieter
1. Headers are now stripped from the summary and newlines are being removed.
2. There is now a %%first_paragraph%% that does what it says. %%content{1}%% will fetch the first section while the %%short%% and aliases will use either the first section (if exists) or would fall back to the first paragraph. I believe this brings some consistency.
3. Sure, one module to rule them all.
4. Yes, %%comments%% will be here, but first we would like to detach page comments from the forums structures and possibly make them a bit more blog-like.
5. Fixed. Just to be clear: this happened when you had %%content{n}%% in a ListModule inside a _template page.
Thanks for all the comments, I hope the module works much better now.
m.
Michał Frąckowiak @ Wikidot Inc.
Visit my blog at michalf.me
Michal: sounds good but a couple more comments… :-)
I'm not sure %%first_paragraph%% is a good name, it's kind of ugly. I'd prefer:
- %%content{n}%% to be explicit
- %%short%% to be the first paragraph (obviously, in the first section if any)
- %%description%% to be the same as short (and in fact, multiple names for the same thing is ugly too, and we should choose the nicest, shortest name, and deprecate the rest)
I can't see any case where the designer would want the current %%index%%/%%description%% behaviour… like I said, it's unstable because adding a second section makes it go bizarre. First you get the first paragraph, then suddenly you get the whole first section. Unstable is not good.
Lastly allowing both 'category' and 'categories' is another hack, and not the right solution. If you can't choose between two terms, they're both wrong. Try something different, like "from" (SQL semantics), and "where" for the tags property.
[[code]]
[[module ListPages from="blog,news,index" where="+public,-deleted"]]
etc.
[[/module]
Portfolio
Michal: s/prependLine/header/, s/appendLine/footer/
-Pieter
Portfolio
When below code lists its own page (i. e. the page that contains this code) you get several “The ListPages module does not work recursively” errors. Not sure though if this is “working as designed” or a bug.
See http://sandbox.wikidot.com/listpages:recursive
Maybe perPage and limit need better explanation. I'm not sure I fully understand, when to set which of them to what value.
Hi Erich,
the reason the module "does not work recursively" is because it can enter an endless loop, exactly as in one of your early tests when displaying such a page brings "connection dropped" from the server. Thanks for finding this bug anyway! The quickest way to be 100% sure that no ListPages calls was to disable the nested ListPages.
Perhaps a better solution could be found. We were trying some other methods too but this one was the quickest to fix the problem. Any suggestions?
PerPage and limit work in the following way:
Suppose you have 100 pages in your category blog:. You want to show them all, but paginated, 10 per page. You use: perPage="10".
Now, to display just 10 pages, but nothing else, no pagination, you use: limit="10".
A combination of these: you want a visitor to browse only 50 first pages of 100, but still 10 per page: perPage="10", limit="50".
limit="n" limits the total number of results that fulfill the select conditions — if you have many pages, 10000, this can limit your set to e.g. 40. This limitation is applied first.
perPage="n" tells how to display the results — how many per one page. If you limit your result set from 10000 to 40, your can display them all at once (perPage="40") or e.g. by 10 (perPage="10") — it would create 4 pages of results with previous/next buttons.
I hope it helps!
Thanks for your comments!!!
m.
Michał Frąckowiak @ Wikidot Inc.
Visit my blog at michalf.me
> limit="n" limits the total number of results that fulfill the select conditions
If the default for limit is “none”, then I would expect a default configuration to display all pages, but it actually just displays 20.
Is the documentation wrong? What does “none” mean? Zero? Unlimited?
Since the module is not yet widely used (and not yet in the official list of modules) there might be a few changes we would like to consider. One of them is default values for
What do you thing would be the most commonly used settings for those two? Setting them manually to false too often could be annoying, but on the other hand it would be nice to promote the use of feeds.
RSS feeds exist independently of the module, the module just points to the proper URL that allows one to access the feed.
Michał Frąckowiak @ Wikidot Inc.
Visit my blog at michalf.me
I'd prefer a default of "false" for both rssEmbed and rssShow.
I'd prefer 'false' for all boolean options, simply for consistency. In some cases this means finding better names.
Portfolio
The code (see http://sandbox.wikidot.com/listpages)
shows the following error(s):
Thanks, it looks like anonymously created pages triggered an error. Quick-fixed for now, I will look at this later today too.
Michał Frąckowiak @ Wikidot Inc.
Visit my blog at michalf.me