User:*Surak*/Extension:NiceCategoryList

Purpose
This extension displays a category listing, including sub-categories, in a number of useful formats. This is intended to allow easier navigation of a wiki's category tree. It implements a new tag,, which generates a list of all pages and sub-categories in a given category. The list can display multiple levels of sub-categories, and has several options for the display style.

This extension was originally created by Kichik as Extension:NiceCategoryList, and has been enhanced by JohanTheGhost and *Surak*.

Parameters
The  tag displays a category list:

Category:Some Category

The tag takes the following parameters, all of which are optional:
 * maxdepth= : maximum category depth to display; default 32
 * headings= : 'head' to display category headings as Wiki headings (default); 'bullet' to display category headings as bullet lists
 * showfirst= : '0' to skip top heading (default), else display it
 * headstart= : with 'headings=head', headstart is the heading level to list top-level categories with; default 2
 * style= : 'bullet' to show category contents as bullet lists (default); 'compact' for a more compact listing
 * showcats= : not '0' to display sub-category links in "bottom" (i.e. maxdepth) categories; default 0
 * showarts= : not '0' to display articles in categories; default 1
 * sort= : not '0' to sort the list alphabetically; else sort the list according to the index key; default 0
 * number= : not '0' to display only up to of articles, else display all articles; default 0
 * random= : with number not '0': display random choice of articles if random not '0', else display the first of articles; default 0

CSS Styles
The original wiki syntax from version 2.2 was basically left, only the direct formatting was taken out. Instead of, the discrete elements are now enclosed in DIV and SPAN tags with class names to allow CSS formatting.

The basic strucure of the elements now looks as follows:

Examples
Caveat: When used in a template, the category list will not refresh immediately when reloaded; edit and save the article to see updates.

Performance
This extension has not been tested on wikis with large (more than a hundred or so) category trees. It may be unacceptably slow on very large wikis. Use with care.

Installation

 * 1) Download the extension code:
 * 2) * Version 1.0: known to work with PHP 4 and MW 1.6.
 * 3) * Version 2.0: known to work with PHP 5 and MW 1.9; will not work on PHP 4 / MW 1.6. This version has much better encapsulation and is better structured.
 * 4) * Version 2.1:
 * 5) * Version 2.2: solved problem with MW 1.12. (Seems to not work with php 5.3?)
 * 6) * Version 2.2a: works for php 5.3
 * 7) * Version 2.3: tested with MW 1.16.2 and PHP 5.2.17; should also work with PHP 5.3
 * 8) Save all files in the directory.
 * 9) Add the following near the end of  :