[pmwiki-users] Categories (was: on over-bundling)

Patrick R. Michaud pmichaud at pobox.com
Wed Mar 9 00:11:45 CST 2005


> On Wednesday, 9 March 2005 5:07 PM, Neil Herber <nospam at mail.eton.ca> wrote:
> The only problem that presents to me, is that I still can't get my 
> head around how categories work.

Okay, so now I'm going to try to solve that.  Categories are fundamentally
simple, but I know we haven't done a very good job of explaining the basics.
I'm a learn-by-example person myself, so what we need is a good basic
example.  And pmwiki.org is something we're all somewhat familiar with,
so I've started my example there.

I find it helpful to think of categories as being the opposite of
WikiTrails.  A WikiTrail defines a set of pages by having links from
a central "trail" page to all of the pages in the trail.  In contrast,
a Category defines a set of pages as being all pages that contain a link
back to the central "category" page.

Note the difference:  To add page XYZ into a trail, we create a link
from the trail page to XYZ.  To add page XYZ to a category, we create
a link from XYZ back to the category.

PmWiki has defined a special markup for this:  [[!ABC]] creates a 
link to Category.ABC, which means that the current page is a 
member of Category.ABC.

Okay, so now a real-world example that hopefully makes this clear.
On pmwiki.org we have several pages that describe uploads, spread
across the documentation and cookbook.  How can someone find these
pages?  They can try a search for "upload", but this is likely to
find lots of pages that happen to contain the word "upload" but aren't
really about PmWiki uploads.  We could build an UploadIndex page that
contains links to all of the relevant pages, but that requires
maintaining UploadIndex which is a pain.

Enter categories.

What I've done tonight is to take several of pages related to uploading
and add the markup [[!Upload]] near the bottom of each.  You can see
an example at http://www.pmwiki.org/wiki/PmWiki/Uploads -- scroll
to the bottom of the page to where it says "Category: Uploads".
The link means that the current page is in the "Uploads" category.
(The word "Category:" is just decoration.)

Now, follow the "Category: Uploads" link.  This takes you to 
Category.Uploads, where you'll see a list of all pages that are
in the Uploads category (i.e., pages with a link to Category.Uploads).

Suppose we have a new page describing uploads that needs to be
added to the uploads category -- how do we do it?  We simply place
[[!Uploads]] somewhere on the new page, and it will automatically
appear in the listing on the Category.Uploads page.

That's really all there is to using categories.  I've already taken
the liberty of defining a Category.Passwords and Category.Skins and
placing some pages in them.  Everyone is welcome to add more pages
to the categories, and to define new categories if we need them.
Nothing special has to be done to define a new category -- simply
place [[!XYZ]] (where XYZ is the category name) into a page somewhere
and you've defined the category.

It's also valid for a page to belong to multiple categories, as in:

    Categories:  [[!Uploads]] [[!Passwords]]

So, that's it.  Go forth and categorize!  :-)

The rest of this message just explains the "magic" of how the the
page listings are generated in the Category.Uploads and other
category pages -- but you don't need to understand this part to
be able to use categories on pmwiki.org.

Okay, so how does Category.Uploads get the list of pages in the
Uploads category?  If you try editing the Category.Uploads page,
you'll see that it's just a simple line of text with no special
markup.  In fact, this is true for nearly all of the Category.*
pages, and some Category pages don't even exist!  So where does
the list of pages come from in Category.Uploads?

The magic is in the Category.GroupFooter page.  Category.GroupFooter
contains markup to be added to the end of every page in the 
Category group, and I've set the group footer to be:

    (:pagelist Category.{$Name} fmt=simple list=normal:)

This markup says to generate a simple list of "normal" pages that
have Category.{$Name} in them.  When this page is rendered, {$Name} is 
replaced by the name of the "current" page, so for Category.Uploads 
this markup will be treated as:

    (:pagelist Category.Uploads fmt=simple list=normal:)

which is just a simple list of all (normal) pages on the site that
have Category.Uploads in them, either as text or a link.  In other
words, display all pages that reference the current page, which
is what we wanted.  Isn't that cool?  And note that this works
for any page in the Category group, including pages that haven't
been created yet.  Very nice.

>From here we often like to point out that the Category pages can themselves
be placed into categories -- but that's a message for another day.

Pm



More information about the pmwiki-users mailing list