• View
• Edit
• History
• Attach
• Print
• Backlinks

WPCategories

Question

How can I make PmWiki list all Categories certain page belongs to at the bottom of the page, like it's done in Wikipedia? and to have a category-list page, listing all pages in the category?

Answer

The WPCategories.phpΔ script is a PmWiki plugin, which collects all [[Category:Something]] links on a page, and lists them all in a pretty box at the bottom of the page. Additionally, it automatically adds a listing of all pages in the category to each page in the Category group.

Description

This plugin is trying to achieve Wikipedia's Category-links processing behaviour in PmWiki. The goal is to have all in-page links to categories, like in an example page describing PmWiki,

 
PmWiki is a Wiki engine, created by [[Patrick Michaud]].

[[Category:Wiki engines]]
[[Category:Patrick Michaud]]

removed, and then neatly grouped together at the bottom of a page, so that they're clearly visible and separated from the page's contents.

The resulting page, when used with the monobook skin, looks like in the picture:

Additionally, the plugin adds a special markup at the bottom of each page in the Category group, which results in a list of all pages in a category of that name. The effect is like in the picture:

Markup variants

Note also, that apart from Wikipedia's markup (with a colon - [[Category:Wiki engines]]), you can use PmWiki's markup. Therefore each of the versions below will give the same output:

• [[Category:Wiki engines]]
• [[Category/Wiki engines]]
• [[Category.Wiki engines]]
• [[!Wiki engines]]

Note also, that only links put at the beginning of a line will be moved. This way you're still able to normally link to categories in page's text, like here:

 
Articles in category [[Category/Wiki engines]] are very interesting.

[[Category/Summaries]]

In the example above, first link will be untouched, while second one will be put in a box.

Installation

This script is installed in the standard way:

1. download the file WPCategories.phpΔ and save it in your cookbook directory,
2. activate the plugin by adding the line below to your 'local/config.php' file:
   include_once( 'cookbook/WPCategories.php' );

Configuration

The script is ready for use immediately after the installation. However, you might want to tweak it to better suit your needs, so here are the options you can change. Note however, that you should set them above the line where you include WPCategories.php.

$WPCategoriesGroup

(default: 'Category')
Name of the group, links to which are collected.

$WPCategoriesPlural

(default: 'Categories' )
This string is used in the categories-box at the bottom of the page.

$WPCategoriesListingHeader

(default: '!! Articles in category "$Namespaced"' )
This string is used on every Category-group page, above the category pages listing.

$EnableWPCategoriesInline

(default: 0)
Normally, the recipe collects only those links, which are placed at the beginning of a line. Change to 1 if you want all the links in the page to be collected into a box (links in the text won't be hidden).

$WPCategoriesAutoBacklinks

(default: 1)
States whether to automatically add backlinks-listing to all Category-group pages. If you want to change the way the category listings are printed, set it to 0, and edit a page named Category.GroupFooter in your PmWiki installation. Below I provide a sample contents, resulting in the same listing as if you didn't turn $WPCategoriesAutoBacklinks off:

!! Articles in category "{$Namespaced}"
(:pagelist link=Category.{$Name} list=normal:)

$WPCategoriesPre, $WPCategoriesBetween, $WPCategoriesPost

These variables define the HTML markup, used to render the categories-box in the page footer. The box is rendered as:

The default values can be easily found in the WPCategories.phpΔ file itself.

Improving Speed

Note: since pmwiki-2.0.4 that's unnecessary - a similar speed-up feature is now built-in.

Note, that at the moment, PmWiki (:pagelist:) directive works terribly slow, resulting in very long, frustrating Category index pages generation times. But then, you needn't worry - there's a FastBacklinks recipe, which solves the problem for you! To make it work for you, install it, add the line below in your config.php:

  $WPCategoriesAutoBacklinks = 0; 

and create a page Category.GroupFooter, with the contents as below:

 
!! Articles in category "{$Namespaced}"
(:backlinks:)

Index Pages Format Tweaking

See PageLists for some possible (:pagelist:) tweaking. You might also consider using the DictIndex recipe to further improve the listing's layout.

Listing Only Pages In Category

There's one question appearing often when you start using the categories feature: How can I link to a category "traditionally", that is not inserting into the category the page which links to it?

Solution A

Possibly the simplest solution is to add an entry to your InterMap, like this one:

 Cat: http://www.your.site.com/wiki/?n=Category.$1

This solution has the advantage of being simple and solving most aspects of the issue.

The disadvantages are:

• The link doesn't show if the destination page exists (as it's formally an external link)
• The link, being formally external, may be rendered differently by your skin (e.g. with some small image attached)
• There's no easy way to find this page as linking to the Category.Something page - e.g. using "?action=backlinks". (Actually, that's what we want using this solution - but it might sometimes raise some problems. Sorry; this solution doesn't let you have your cake and eat it.)

Solution B

There's one quite easy solution, but it puts some requirements on your Wiki structure, and therefore may not always be applicable. The solution I'm talking about can be used if your wiki is structured (or you restructure it) in such a way, that you know that either:

1. all pages, which you want to be members of a category, are in certain Groups - while all pages linking "traditionally" to the category's main page are not there, or
2. all pages which you want to link "traditionally" to the category page (don't be listed in the category's main page) are in certain Groups, while the members of the category are not there.

The solution is based on modyfing the (:pagelist:) directive in your Category.GroupFooter page (see WPCategoriesAutoBacklinks, which must be changed to 0). Here are the modifications to be used if corresponding condition above is fulfilled:

1. (:pagelist link=Category.{$Name} list=normal group=GroupOne,GroupTwo:) if your category members are only in groups GroupOne, GroupTwo.
2. (:pagelist link=Category.{$Name} list=normal group=-GroupOne,-GroupTwo:) if your category members are not in groups GroupOne, GroupTwo.

Automatic creation of Category pages

If you want empty Category pages to be created automatically when you link to them, add the following line to your 'local/config.php' (note: you must use at least PmWiki 2.2 for this):

 $AutoCreate['/^'.$CategoryGroup.'\\./'] = array('ctime' => $Now);

Notes and Comments

• This recipe was last tested on PmWiki version: 2.1.5
• This recipe was first tested on PmWiki version: 2.0beta55
• This recipe requires at least PmWiki version: ???

• 'WP' in 'WPComments' stands for Wikipedia.

Known Issues

• Category index pages list also those pages, which link to a certain category with normal, inline (in page text) links. That should not happen.
  • One possible partial solution working currently is given above.
  • An idea of a solution: write a script which mimics the pmwiki's backlinks indexing, but indexes only properly formatted (as above) category links as backlinks. The WPCategories recipe should then use this data somehow to list pages in a category. The described script could possibly add new 'behaviour' to the (:pagelist:), like (:pagelist category=Category.WikiEngines:)
• Theoretically possible conflicts with the InterMap, although it's hard to imagine why someone would want to create a Category: InterMap.

See Also

• FastBacklinks - make your Category-index pages load much faster! (see section: Improving Speed, above)
• MediaCategories
• DictIndex - recipe for prettier page listings formatting.

More Wikipedia

• Monobook - Wikipedia-like PmWiki skin.
• DiscussionTab - Wikipedia-like Discussion Tab for each page.
• SectionEdit - this recipe aims to achieve the effect similar to [edit]-links in page sections in Wikipedia.

Contributors

• Mateusz, 2005-08-04 - if you are having issues with the recipe, when emailing the mailing list please send me a copy of your email (I'm not actively reading the list).

History

• 2007-10-07 - v1.6
  • modified for compatibility with Cookbook:MarkupExtensions
• 2007-09-30 - v1.5
  • $EnableWPCategoriesInline to collect links not only from line beginning
  • duplicates in the categories box are removed (thanks to Erik Lindberg for feedback)
• 2006-05-10 (version 1.4) - more bugfixes - thanks to Des again
  • [[!Name]]-style links are now also extracted only if they're at the beginning of a line
  • a [[!Name]]-style link on last line was not extracted if no newline at line's end - corrected
  • $WPCategoriesGroup was ignored at some places - corrected
• (version 1.3) - only links put at the beginning of a line are now moved to the box. Therefore linking to a category from page's text is now possible.
• 2006-05-07 (version 1.1beta01) - corrected to work with pmwiki-2.1.5 (and I hope other 2.1.* versions) - thanks to Des for an e-mail describing the problem.
• (version 1.0beta01) - initial version

Comments

• Has Anyone tried this with any success on PmWiki 2.1?
  I have installed the option in 2 separately hosted wikis, and in each case the both the Category Box and the Category List have failed to appear. (Des Jan 10, 2005)

• Hey, I also did installed it on the actual PmWiki Version. The Category Box appears as described, but the Categories were not created. All that appears is a link to a new site calles categories.xxx
  Chris
  • Have you tried to open the "Category.Xxx" page? There should be a listing there of all pages in the category, even if the page is not 'created'. If it's really absent, please e-mail me and we might try to find the cause of the problem.
    ~Mateusz
• This recipe does not work with some skins (like grease) is there a list of working skins?
  • I've tested this skin and haven't encountered this problem. Maybe that was rather the problem of WPCategories not working properly with pmwiki-2.1.* - which is now hopefully corrected.
• I just tried installng MarkupExtensions and found it broke the functioning of WPCategories.
  Two problems I saw were:
  1. The shaded box that should surround the collected list of categories was no longer visible
  2. When there was more than one category, then some of the categories that should have been in the list actually appeared out of position, ABOVE the list of categories
  Unfortunately, the code for WPCategories is way over my limited capability, so I have no clue where to look, but I did post a comment with a couple of observations on the MarkupExtensions page too.
  Actually, all I really wanted was the footnote functionality from the extensions. I find the anonymous link made using [[stuff | #]] useless for this purpose if you have more than one, as you lose your position on the page when you jump to the anchor. The footnote extension places an automatic link back to point you jumped from, which is much more sensible and useable Des August 20, 2006, at 05:12 PM

• Question: Is there a way to turn off the Articles in Category functionality and still have the pretty box with Categories at the bottom. Thanks!

• I'm using 2.2.0-beta65, and everything appears as promised, but the links to the Category pages are all suffixed with ?action=edit. They open an editing box instead of bringing up the Categories list. I've looked through the WPCategories code and didn't see anything that might cause it, though I'm not a PHP expert by any means. Am I just doing something wrong? Thanks.

• Pages listed by title not name.

• Category Pages repeating list