Extension:BreadCrumbs2

MediaWiki.org > Extensions > User interface > Extension:BreadCrumbs2

What can this extension do?
This extension generates "breadcrumbs" to help users navigate around your wiki (assuming it has a structure suitable for navigation). Breadcrumbs replace the page subtitle, which is normally used for redirect messages, with a single line navigation string. A sample breadcrumb for this page is shown in pale yellow above.

BreadCrumbs2 generates breadcrumbs in the "Where am I?" sense ; use Extension:BreadCrumbs for breadcrumbs in the traditional "How did I get here?" sense.

For each page the extension can use the categories and/or namespace to:
 * 1) Replace the page subtitle with a single line navigation string
 * 2) Highlight the active sidebar link and/or tab
 * 3) Change the site logo

Note that BreadCrumbs2 only makes sense on small, highly structured wikis, typically ones where the navigation sidebar has a short list of links that define distinct sections of the wiki. By its very nature, a generic reference like Wikipedia has no meaningful structure at the page level.


 * Breadcrumbs use a single line of text to show a page's location in the site hierarchy... Breadcrumbs have always been a secondary navigation aid... All that breadcrumbs do is make it easier for users to move around the site, assuming its content and overall structure make sense.

BreadCrumbs2 is especially useful with skins like GuMax that display the navigation bar as a row of tabs at the top of the page instead of the Discussion/Edit/History tools. It detects and uses the dynamic sidebar generated by DynamicSkin-based skins.

See InfoDabble for an example of a wiki that uses BreadCrumbs2.

Usage
The breadcrumb data is stored in a special page, MediaWiki:Breadcrumbs. To access this page, either enter "MediaWiki:Breadcrumbs" into the "search" box and click Go or copy and paste the link   into a page, then open and edit. The contents are formatted as a wikitext list, with one line per breadcrumb option: * category name @ breadcrumb wikitext @ tab name @ site logo Extra blanks between parameters are ignored.

The breadcrumbs are built from the data page as follows:
 * 1) The string '@@@' is stripped from the text to be replaced with '@' before output (since the '@' character is used as a delimiter)
 * 2) Pseudo-variables of the form @@VAR@@ are evaluated.
 * 3) * @@USERID@@: User ID, blank if anonymous
 * 4) * @@USERGROUPS@@: Comma-delimited list of groups this user belongs to
 * 5) Templates and variables in the text are expanded. You can use parser functions like #if: if installed.
 * 6) The extension scans each line to find the first match with the current page's namespace or one of the page's categories.
 * 7) The remainder of the line is evaluated to set the breadcrumb string, sidebar, and/or logo (see below)

Navigation
The extension replaces the page subtitle, which is normally used for redirect messages, with a single line navigation string. Arbitrary wikitext can be used for the navigation text, though it should be kept to a simple series of links and delimiters.


 * Note: Jakob Nielsen strongly encourages web designers to use the '>' character to delimit breadcrumb levels.

For example, Generates the following breadcrumb for this page:

Note that BreadCrumbs2 uses the first match with the current page's namespace or one of the page's categories. For example, if the Breadcrumbs page contains: The breadcrumbs for this page would be MediaWiki.org > Extensions > Navigation > Extension:BreadCrumbs2 and not MediaWiki.org > Extensions > User interface > Extension:BreadCrumbs2 because the Navigation line comes first.

Sidebar
The active link in the navigation sidebar can be highlighted using the tab name parameter, if specified. This is especially useful with skins like GuMax that display the navigation bar as a row of tabs at the top of the page instead of the Discussion/Edit/History tools.

BreadCrumbs2 automatically detects and uses the dynamic sidebar generated by DynamicSkin-based skins.


 * Note: The tab name is compared to the actual text displayed in the sidebar, so it is not language-independent.

Site logo
If the site logo parameter is specified, an alternate image file is used instead of the site default. The path to this image is relative to the root of your wiki.


 * Note: Use this feature with caution so that it doesn't interfere with your site's usability. Subtle changes are good, but dramatic changes can be confusing. If your site needs significantly different look and feel between sections, consider using namespaces and namespace-specific styles and/or DynamicSkin.

Installation
Copy the BreadCrumbs2.php file to the /extensions directory and add a reference to LocalSettings.php.

Tips, tricks, and hoops

 * The original version of this extension used subpages to define the navigation tree. This proved unworkable for the same reasons originally encountered in Wikipedia. Categories work much better when combined with manual input as in this version.
 * The breadcrumb list in MediaWiki:Breadcrumbs defines all the categories and subcategories used for navigation. You could add the code from Extension:CategoryBreadcrumb if you'd rather automatically generate a category tree.
 * The extension uses the '@' character to delimit parameters instead of '|' as used in MediaWiki:Sidebar. This greatly simplifies the use of conditional templates in the breadcrumb list.
 * The hook code is based on Extension:RemoveSubpagestr. It hooks the  event which is triggered before   starts page output:
 * The function  uses a cloned copy of the parser object to render the wikitext contents (see How do I render wikitext in my extension?).
 * The function  creates a new   to load the settings page and   to get its wikitext contents.
 * The function  creates a new   to load the settings page and   to get its wikitext contents.

Links

 * Extension:BreadCrumbs (MediaWiki) provides a breadcrumb navigation which shows the user's path through a wiki.
 * MediaWiki BreadCrumbs (Luke Jackson) allows you to dynamically create a "trace" of the pages you have visited so far.
 * Breadcrumb navigation (Wikitravel) shows bread crumb menus under the title of an article to show the countries and regions that a destination belongs to.
 * Extension:CategoryBreadcrumb (MediaWiki) creates a category tree to show the current category for an article, with all the parent categories.
 * DynamicSkin (MediaWiki) allows the skin layout to be defined using normal wikitext articles instead of PHP script files. The layout and content can change automatically depending on the page being displayed
 * MenuTabs - Meta adds CSS tabbed navigation to each page in the wiki.
 * Extension:RemoveSubpagestr removes links from certain subpages back to their root page.

Version history

 * 0.9: September 6, 2007: initial public release
 * 0.8: August 2 2007, initial release on ehartwell.com