Extension:BreadCrumbs2

From MediaWiki.org
Jump to: navigation, search
MediaWiki.org > Extensions > User interface > Extension:BreadCrumbs2
MediaWiki extensions manual
Crystal Clear action run.png
BreadCrumbs2

Release status: beta

Implementation User interface, Skin
Description Provides breadcrumb navigation based on categories
Author(s) Eric Hartwell, Ike Hecht
Latest version 1.0 (2013-08-01)
MediaWiki 1.10+
PHP 5.3+
Database changes No
License CC BY 3.0
Download
Example MediaWiki.org > Extensions > User interface > Extension:BreadCrumbs2
Hooks used
SkinTemplateOutputPageBeforeExec

BeforePageDisplay

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

Check usage and version matrix; code metrics

The BreadCrumbs2 extension generates "breadcrumbs" to help users navigate around your wiki (assuming it has a structure suitable for navigation). Breadcrumbs inserts a single line navigation string before a page's content. A sample breadcrumb for this page is shown in pale yellow above.

BreadCrumbs2 generates breadcrumbs in the "Where am I?" sense[1]; 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. Insert a single line navigation string before a page's content
  2. Highlight the active sidebar link and/or tab
  3. Change the site logo
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.[2]

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.

Usage[edit | edit source]

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 [[MediaWiki:Breadcrumbs]] 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.

Parameter Type Description
category name required For each line in the list, see if the current page is a member of the category that matches category or the namespace with the same name.
breadcrumb wikitext optional Text to display in the subtitle with the page name appended
tab name optional The tab (navigation) bar with the name tab name that matches category is marked as active.
site logo optional Use a different site logo for this page. (Note: Use this option with care)

Navigation[edit | edit source]

The extension inserts a single line navigation string before a page's contents.[3]

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

For example,

* Hook extensions @ [[Main Page|MediaWiki.org]] > [[:Category:Extensions|Extensions]] >

Generates the following breadcrumb for this page:

MediaWiki.org > Extensions > BreadCrumbs2

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:

* Navigation extensions @ [[Main Page|MediaWiki.org]] > [[:Category:Extensions|Extensions]] > [[:Category:Navigation extensions|Navigation]] >
* User interface extensions @ [[Main Page|MediaWiki.org]] > [[:Category:Extensions|Extensions]] > [[:Category:User interface extensions|User interface]] >

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

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.

[edit | edit source]

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.

Download[edit | edit source]

You can download the extension code, in .zip format, here.

You can also download the code directly via Git from the MediaWiki source code repository. From a command line, you can call the following:

git clone https://gerrit.wikimedia.org/r/p/mediawiki/extensions/BreadCrumbs2.git

To view the code online, including version history for each file, go here.

Installation[edit | edit source]

  • Download and extract the file(s) in a directory called BreadCrumbs2 in your extensions/ folder.
  • Add the following code at the bottom of your LocalSettings.php:
require_once "$IP/extensions/BreadCrumbs2/BreadCrumbs2.php";
  • Done! Navigate to "Special:Version" on your wiki to verify that the extension is successfully installed.

Tips, tricks, and hoops[edit | edit source]

  • 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.
  • If some of your users don't like the breadcrumbs, they can hide it with some CSS (see Manual:$wgAllowUserCss):
#breadcrumbs2 {
   display: none;
}

Technical details[edit | edit source]

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.
    • @@USERID@@: User ID, blank if anonymous
    • @@USERGROUPS@@: Comma-delimited list of groups this user belongs to
  3. Templates and variables in the text are expanded. You can use parser functions like #if: if installed.
  4. The extension scans each line to find the first match with the current page's namespace or one of the page's categories.
  5. The remainder of the line is evaluated to set the breadcrumb string, sidebar, and/or logo (see below)

See also[edit | edit source]

References[edit | edit source]

  1. Street signs and Breadcrumbs, Chapter 6, Don't Make Me Think - Steve Krug
  2. 2.0 2.1 Breadcrumb Navigation Increasingly Useful - Jakob Nielsen's Alertbox, April 10, 2007
  3. Arbitrary wikitext can be used for the navigation text, though it should be kept to a simple series of links and delimiters.

Links[edit | edit source]

Version history[edit | edit source]

  • 1.0: August 1, 2013: updating and code cleanup
  • 0.9: September 6, 2007: initial public release
  • 0.8: August 2, 2007 initial release on ehartwell.com