Extension:Hierarchy

From MediaWiki.org
Jump to: navigation, search
MediaWiki extensions manual
Crystal Clear action run.png
Hierarchy

Release status: unmaintained

Implementation Database, Tag, Parser function
Description Creates an hierarchical page navigation structure.
Author(s) Fernando Correia
Latest version 1.2.1 (2012-01-10)
MediaWiki 1.16
Database changes Yes
License GPLv2+
Download Code
View
Parameters

$wgHierarchyNavPrevious
$wgHierarchyNavNext
$wgHierarchyEmbedSubordinates
$wgHierarchyNavigateSubordinates
$wgHierarchyNavigationBoxBaseWidth
$wgHierarchyNavigationBoxIncrement

Translate the Hierarchy extension if it is available at translatewiki.net

Check usage and version matrix; code metrics

Introduction[edit | edit source]

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.

Page hierarchy

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:

Sample index page


Sample hierarchical page

Features[edit | edit source]

  • 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[edit | edit source]

  • 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[edit | edit source]

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

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

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

4. Create the database table, executing the following script on your MySQL administration tool.

CREATE TABLE `hierarchy` (
  `Id` INT(10) UNSIGNED NOT NULL AUTO_INCREMENT,
  `IndexArticleId` INT(10) UNSIGNED NOT NULL,
  `TocLevel` INT(10) UNSIGNED NOT NULL,
  `TocNumber` varbinary(255) NOT NULL,
  `TocText` varbinary(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,
  `RootText` varbinary(255) NOT NULL,
  `Deslash` INT(10) UNSIGNED NOT NULL DEFAULT '0',
  PRIMARY KEY  (`Id`),
  KEY `IndexArticle` USING BTREE (`IndexArticleId`,`Sequence`),
  KEY `ArticleId` (`ArticleId`)
) ENGINE=MyISAM DEFAULT CHARSET=BINARY;

Configuration[edit | edit source]

Add these lines to LocalSettings.php:

# Disable cache
$wgEnableParserCache = false;
$wgCachePages = false;
 
# Allow external images
$wgAllowExternalImages = true;
 
# Activate Hierarchy extension
require_once("$IP/extensions/Hierarchy.php");
$wgHierarchyNavPrevious = "http://server.com/wiki/path/HierarchyPrevious.gif";
$wgHierarchyNavNext = "http://server.com/wiki/path/HierarchyNext.gif";

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

Since version 1.2.1 $wgHierarchyOldStyle has been introduced to limit the generated top TOC to only siblings and childs. By default this is set to false.

$wgHierarchyOldStyle = true;

Usage[edit | edit source]

Create a hierarchy header template[edit | edit source]

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:

<includeonly>{{#hierarchy-top:}}</includeonly><noinclude>
This is the header of a page that belongs to a hierarchy.
</noinclude>

Create a hierarchy footer template[edit | edit source]

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:

<includeonly>{{#hierarchy-bottom:}}</includeonly><noinclude>
This is the footer of a page that belongs to a hierarchy.
</noinclude>

Apply hierarchy templates to pages[edit | edit source]

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:

{{Hierarchy header}}
This is a page that belongs to a hierarchy.
{{Hierarchy footer}}

Create the top hierarchy page[edit | edit source]

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.

{{Hierarchy header}}
This is the topmost page of this hierarchy.
{{Hierarchy footer}}

Create the index page[edit | edit source]

Each hierarchy is defined by an index. The index is just a regular wiki page that uses the special <index> 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.
  • A rendered Table of Contents is required!
    In case you have less than 4 items you have to write either the magic word __FORCETOC__ anywhere on the page to make it display at the default location, or __TOC__ at the preferred position.


This is the index of a page hierarchy.

<index>
[[Sample Top page]]
= Sample Chapter one =
== Sample Topic one ==
== Sample Topic two ==
= Sample Chapter two =
== Sample Topic three ==
=== Sample Subtopic A ===
=== Sample Subtopic B ===
== Sample Topic four ==
</index>

Sample[edit | edit source]

See the usage sample to get started with a working example.

Customization[edit | edit source]

Some customization options are available and can be set in LocalSettings.php:

  • $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.

Some messages can also be customized using the Special:Allmessages page:

  • 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[edit | edit source]

Feedback[edit | edit source]

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