edit SideBar

PmWiki • Categories

authors (intermediate)

Purpose of Categories

Categories (also known as "tags") are a way to organize and find related pages. Categories are implemented by default in PmWiki 2, and in most wikis they don't require any special code or markup, they're just a useful convention. The idea is that every page that falls into a particular subject area should have a link to a shared page containing links to other pages on that subject. These pages are created in the Category group, and thus these subject areas are called Categories.

Using Categories

Getting Categories to work requires two steps, the first of which is adding links to each Category. A Category named Subject is created by adding a link to Category.Subject on any page. When you add the link to a page, the page can be described as being in the Category "Subject".

There is a special markup for creating these links which makes Categories work more smoothly: [[!Subject]] will create a link to Category.Subject. So [[!Subject]] is a kind of shortcut to the page Subject in the category group.

If you click on the category links on a page, initially you'll just be taken to an empty page named Category.Subject. The second step in setting up Categories is to modify the behavior of pages in the Category group so that they will display a list of all pages containing links to Category.Subject. This is relatively simple to do:

  1. Open the page Category.GroupFooter? for editing
  2. Add the line (:pagelist link=Category.{$Name} list=normal:)
  3. Save the edits

This will cause the footer on every page in the Category group to display a list of links to pages that reference that page in the category group.

It is worth noting that rather than adding this to Category.GroupFooter, the pagelist code could be added to Category.GroupHeader to similar effect; it just depends on whether you'd prefer to have the list of pages appear before or after any text that you add to the individual category pages (which can be edited just like normal pages).

Because we use the normal PageList link= markup, you can use it not only in the category group. If you want to show all pages belonging to the category Subject you can use on any wiki page (:pagelist link=Category.Subject list=normal:).

Similarly, there's no requirement that a "category page" has to be in the Category group -- any page can define a "category" of pages that link to it.

An administrator can override the default category group name of "Category" by setting the $CategoryGroup variable in config.php to another group name.


So, by adding the link [[!Subject]] to a page, a link to that page will automatically appear on the page Category.Subject, as long as the GroupFooter for the Category group has been tweaked appropriately. Thus, you can create a page that automatically creates an alphabetized list of all movies discussed on your wiki by creating links to [[!Movies]] on each film's page; the resulting automatic list would be on the page Category.Movies.

authors (advanced)

Category Nesting

Categories have the potential for even greater usefulness because Category.* pages can themselves be placed into categories! To follow an excellent example from John Rankin, let's suppose we have the following film pages in the categories listed to the right:

Film.SeanOfTheDead    [[!Horror]] [[!Comedy]] [[!2003]]
Film.InMyFathersDen   [[!Drama]] [[!2004]]
Film.TheCorporation   [[!Documentary]] [[!2003]]

Now then, we can create Category.Horror, Category.Comedy, Category.Drama, and Category.Documentary, and in each one of those pages we put [[!Genre]]. In Category.2003 and Category.2004, we put [[!Year]].

So, what happens when we display Category.Genre ? We see links to "Comedy", "Drama", "Documentary", and "Horror", because they're in the Genre category. When we click on one of those links, we see all of the films listed in one of those categories. Similarly, if we click on Category.Year, we see links to "2003" and "2004", each of which in turn displays the list of films for that year.

Finally, in Category.Genre and Category.Year we can put [[!Category]], which makes them "top-level" categories reachable from the Category.Category page. Voila, we now have an instant "hierarchy":


Note however that this isn't a "strict" hierarchy--i.e., any page or category can appear simultaneously in multiple categories. For example, Category.Documentary could be a member of both the Genre and top-level category listings.

Each category page can have content text before the generated list, e.g., to give a generic description of things in the category. (Or it can be empty, which works fine.) It can also contain associations to related categories ("see also" references). For example, in a tourism wiki, the ''bed and breakfast" category might contain a see-also reference to the "self-catering" category.

administrators (intermediate)

The Guts of the Category Markup

As mentioned, all of the necessary markup features for Categories are enabled by default in current releases of PmWiki 2.0, but here's how they work for those who are interested. The use of the Category group as the repository for all categories is determined by setting the $CategoryGroup variable, and the special [[!Subject]] markup is activated by a call to the Markup() function:

Markup('[[!','<links','/\[\[!([^\|\]] ?)\]\]/',
  "<span class='category'>[[$CategoryGroup/$1]]</span>");

Coming Up With Good Category Schemes

The hard part about using categories is choosing a good vocabulary. Site content managers may wish to follow the Guidelines for the establishment and development of monolingual thesauri (ISO 2788-1986) and the Guidelines for the establishment and development of multilingual thesauri (ISO 5964-1985). Questions to think about include:

  • whether a scheme already exists and can be reused
  • number of levels in a multilevel scheme (not too shallow, not too deep -- e.g. 3)
  • number of categories per page (not too many, not too few -- e.g. 3)
  • consistent use of singular ([[Mercury]] is a [[!planet]]) or plural ([[Mercury]] is in the [[!planets]] category)
  • disambiguation and use of phrases ([[!musical instruments]] and [[!medical instruments]]) or Cookbook:Subpage Markup ([[!Instruments*Musical]] and [[!Instruments*Medical]])

Or you can just let people use whatever category terms they find meaningful. A vocabulary (or "folksonomy") will emerge over time.


Radu, John Rankin, SolaRoofGuy, David A Spitzley

<< Passwords | DocumentationIndex | Installation >>

July 2014:
Yate 5.4 and YateBTS 4 launched. Added JSON and DNS support in Javascript, Handover support in YateBTS.

March 2014:
YateBTS 2.0 launched. Added authentication and WebGUI. Added USSD support in commercial version.

March 2014:
Yate 5.2 launched. Better JavaScript support and a fixed memory leak.

Jan 2014:
YateBTS 1.0 launched. The first GSM Basestation which works with an IMS/VoLTE core network.

Jan 2014:
Yate 5.1 launched. Better JavaScript support and added libygsm. Elisa chatbot added in RManager

Oct 2013:
OpenHSS is the Yate based HLR/HSS solution for MVNO and LTE carriers.

Oct 2013:
Yate 5 released. Added IPv6 support in SIP for LTE. Improved JavaScript support. Download NOW

Jan 2013:
Yate 4.3 released: Added XML support in Javascript. SCCP - GTT routing between different networks. Stability improvements.
Download NOW

Aug 2012:
Yate 4.2 released: SIP flood protection. Better Jabber/Google Voice support. Usable Javascript. Fixed SIGTRAN links fluctuations.
Download NOW

Apr 2012:
YateClient was accepted in the Mac Store.

Yate 4.1 released: better Gvoice support, iSAC codec, support for new Wanpipe drivers. Fixes T.38 and Mac client issues.

Mar 2012:
SS7Cloud is launched today, 1st March, 2012, by NullTeam, Yate creators. Having all you need to be a US CLEC, it brings SS7 services in a cloud.

Feb 2012:
Yate 4.0 released.
SCCP, TCAP, MAP and CAMEL, TCP and TLS in SIP, Javascript fast prototyping of telephony applications and brand new face for YateClient.

Nov 2011:
Here is a video that, quote "demonstrates the truly awesome power of the YATE engine, as it easily handles 3 simultaneous calls to an audio player application including dtmf (button press) handling "(from PaintedRockComm).

Nov 2011:
Yate will attend ORR - OPENRHEINRUHR (November 12 - 13).

04 May 2011:
sipgate chooses open source project Yate for core infrastructure.

12 Apr 2011:
Yate 3.3.2 released.
Fix for Jingle calls to Google Voice dropping after 5 minutes.
4 Apr 2011:
Yate 3.3 released.
Support for GMail chat conference, fixes for internal microphone in MacOS. Minor fixes in SS7 M2PA and ANSI. Fixes in H.323, SIP and RTP.

9 Mar 2011:
Yate 3.2 released.
Bug fixes in SIGTRAN/MGCP/SS7 and added support for CNAM/LNP lookup by SIP INVITE/3xx.

Feb 2011:
Yate will attend FOSDEM and XMPP summit.

31 Jan 2011:
Yate 3.1 released.
Yate client support for Google Voice. Support for any country tones in tonegen.

20 Dec 2010:
Yate 3.0 released.
SS7 ITU certified. SS7 STP added. Client supports Jabber IM (Google Talk + Facebook).

3 May 2010:
Yate 3.0.0 alpha 3 released. Featuring the new Jabber server and wideband audio.

8 March 2010:
Yate 2.2 released. Mostly bug fixes. Dahdi compatible. Latest 2 release before 3.0.

6-7 February 2010:
Yate booth at FOSDEM 2010. Free CD with Freesentral available.

2 Nov 2009:
Yate 2.1 launched. Can replace a Cisco PGW2200 to control a Cisco AS54xx.

6 Aug 2008:
Yate and OpenSIPS (former OpenSER) join to build IP based clusters.

4 Aug 2008:
Yate 2 launched.

EditHistoryBacklinksRecent ChangesSearch