Extension:Hierarchy

Introduction
There are three main forms to organize content on a web site: webs, sequences and hierarchies.

A web is the most common organization form for a wiki. In this structure, pages have many free links among them. This format is well-suited for pages that are loosely related, such as encyclopedic entries.

In a sequence, pages are organized in a sequential form. One page leads to the next. This structure is appropriate for tutorials and presentations.

A more structured form is the hierarchy. It is useful when there is a natural classification of the content that makes navigation more intuitive. It could be used, for instance, for a product reference manual.



MediaWiki excels at the web structure. It can also be used to represent hierarchies, using internal links and subcategories. But sometimes it is useful that, in addition to the web structure, the user is presented with some guidance that will help him to have a global vision of an information body and to achieve an easier navigation.

The Hierarchy Extension can be used to create sequential and hierarchical structures.

For example:





Features

 * Several independent hierarchies can be present on the same wiki. Each page can only belong to a single hierarchy, though.
 * The hierarchy definition is centralized in an index page, not on the individual pages. Changes to the hierarchy only need to be made in one place and take effect immediately.
 * A hierarchical index is automatically generated, with direct links to the pages.
 * Multiple levels are supported.
 * The levels (e.g. top, chapters, subchapters) are themselves pages that can, optionally, have an introductory text.
 * Each page has, when appropriate:
 * A navigation box with link to the index, to the superior pages, to the pages of the same level and, optionally, to its subordinate pages.
 * Optionally, a list of its subordinate pages embedded in the page content.
 * Navigational links to the previous and next pages.

Limitations

 * Cache must be disabled for the hierarchy changes to take effect without editing the affected pages on the hierarchy.
 * External images must be enabled.
 * There must be at least 4 pages in the index.

Installation
1. Download Hierarchy.php and save it in the extensions directory of your wiki.

2. Download this image and upload it to your wiki as HierarchyPrevious.gif.

3. Download this image and upload it to your wiki as HierarchyNext.gif.

4. Create the database table, executing the following script on your MySQL administration tool. Substitute `databasename` for the name of your database.

CREATE TABLE `databasename`.`hierarchy` ( `Id` int( 10 ) unsigned NOT NULL AUTO_INCREMENT,  `IndexArticleId` int( 10 ) unsigned NOT NULL ,  `TocLevel` int( 10 ) unsigned NOT NULL ,  `TocNumber` varchar( 255 ) NOT NULL ,  `TocText` varchar( 255 ) NOT NULL ,  `Sequence` int( 10 ) unsigned NOT NULL ,  `ArticleId` int( 10 ) unsigned NOT NULL ,  `PreviousArticleId` int( 10 ) unsigned NOT NULL ,  `NextArticleId` int( 10 ) unsigned NOT NULL ,  `ParentArticleId` int( 10 ) unsigned NOT NULL ,  PRIMARY KEY ( `Id` ) ,  KEY `IndexArticle` USING BTREE( `IndexArticleId` , `Sequence` ), KEY `ArticleId` ( `ArticleId` ) ) ENGINE = MYISAM DEFAULT CHARSET = latin1;

Configuration
Add these lines to LocalSettings.php:

$wgEnableParserCache = false; $wgCachePages = false;
 * 1) Disable cache

$wgAllowExternalImages = true;
 * 1) Allow external images

require_once("extensions/Hierarchy.php"); $wgHierarchyNavPrevious = "http://server.com/wiki/path/HierarchyPrevious.gif"; $wgHierarchyNavNext = "http://server.com/wiki/path/HierarchyNext.gif";
 * 1) Activate Hierarchy extension

Write the full URL of the uploaded images on $wgHierarchyNavPrevious and $wgHierarchyNavNext.

Create a hierarchy header template
This is a one-time step. It is not mandatory but it makes it easier to work with the extension.

Create a page named Template:Hierarchy header or something like it. Insert this content:

This is the header of a page that belongs to a hierarchy.

Create a hierarchy footer template
This is a one-time step. It is not mandatory but it makes it easier to work with the extension.

Create a page named Template:Hierarchy footer or something like it. Insert this content:

This is the footer of a page that belongs to a hierarchy.

Apply hierarchy templates to pages
For each page that will belong to the hierarchy, insert the templates you created on the first and last lines of the page, like this:

This is a page that belongs to a hierarchy.

Create the top hierarchy page
For each hierarchy create a page that will be the topmost page of that hierarchy. It will provide an introduction to the hierarchy and an starting point to it.

This is the topmost page of this hierarchy.

Create the index page
Each hierarchy is defined by an index. The index is just a regular wiki page that uses the special   tag to define the hierarchical structure.

The index is the only place in which the hierarchy is defined. To insert new levels, pages or move things around in the hierarchy, you only need to edit the index. All navigational links on the pages will immediately reflect the new structure.

These important restrictions must be considered when editing the index:
 * Only existing pages are indexed.
 * The index can be defined before the pages are created. But in this case it must be edited and saved again after all pages are created. This will recreate the hierarchy information on the database, so the navigational links can be shown correctly.
 * A page can only belong to one hierarchy.
 * Only one set of hierarchical navigational links can be shown on a page. If a page is used in two indexes, it will belong to the one that was saved more recently.
 * The index format is strict.
 * The top page must be defined as an internal link on the first line of the index. The hierarchical pages must be defined as titles of the appropriate level. Failure to follow these strict formatting requirements will result in navigational problems. On the other hand, you can write anything (or nothing) outside the "index" tags.

This is the index of a page hierarchy.

Sample Top page = Sample Chapter one =

Sample Topic two
= Sample Chapter two =

Sample
See the usage sample to get started with an working example.

Customization
Some customization options are available and can be set in LocalSettings.php: Some messages can also be customized using the Special:Allmessages page:
 * $wgHierarchyNavPrevious: URL of "previous page" image.
 * $wgHierarchyNavNext: URL of "next page" image.
 * $wgHierarchyEmbedSubordinates: true to embed a list of subordinate pages on the page contents (footer template); false otherwise.
 * $wgHierarchyNavigateSubordinates: true to include the subordinate pages on the navigation box (header template); false otherwise.
 * $wgHierarchyNavigationBoxBaseWidth: Starting width of the navigation box in pixels.
 * $wgHierarchyNavigationBoxIncrement: Number of pixels to increment the width of the navigation box for each hierarchical level.
 * hierarchy_index: Word to use for the link to the hierarchy index page.
 * hierarchy_subordinates_separator: Wiki markup to use to separate the embedded subordinate pages list from the main page contents.

Alternatives

 * CategoryTree extension
 * Slides extension
 * Treeview skin

Feedback
Use the discussion page for feedback, questions, feature requests and bug reports.