Jump to content

Extension:YAMBE

From mediawiki.org
MediaWiki extensions manual
Yambe
Release status: stable
Implementation Tag
Description Insert hierarchical breadcrumbs into pages
Author(s) Ian Coleman, Steffen Olszewski (Sodeveltalk)
Latest version 0.9.2 (2023-03-30)
Compatibility policy Master maintains backward compatibility.
MediaWiki >= 1.37.0
License GNU General Public License 2.0 only
Download
$wgYambeURLsplit, $wgYambeBCdelimiter, $wgYambeBCmaxCount, $wgYambeBCoverflowPrefix, $wgYambeBCselfLink, $wgYambeBCprintable
yambe:breadcrumb

The YAMBE extension (Yet Another MediaWiki Breadcrumb Extension)

It creates a hierarchical breadcrumb (navigation path) for a MediaWiki page based on the page that it was created from. Allows users to track back through the wiki more easily and provides a context for the current page.

Whenever a new page is created beneath a page which already uses YAMBE a piece of markup is inserted at the start of the page to set up YAMBE and identify the page's parent. When the page is displayed this is used to build links to the parent page looping through each parent until it gets to the top of the tree.

YAMBE differs from many of the other MediaWiki breadcrumb extensions in that it allows the wiki structure (and the author) to control the breadcrumb that the user sees, rather than displaying the user's progress through the wiki.

Installation

[edit]

Configuration

[edit]

The extension can be configured by LocalSettings.php using the following variables, the default values are shown below:

// Fragment to split the URL with to find the page title, the part right of this fragment will be used. Usually either /w/index.php?title= or /wiki/.
$wgYambeURLsplit = '/w/index.php?title=';

// String to separate the breadcrumb elements with.
$wgYambeBCdelimiter = ' > ';

// Maximum number of breadcrumb elements.
$wgYambeBCmaxCount = 5;

// Prefix to use if the maximum number of breadcrumb elements is exceeded.
$wgYambeBCoverflowPrefix = '[...]';

// If true, the breadcrumb element for the current page will be a link to it, otherwise it will be plain text.
$wgYambeBCselfLink = false;

// If true, the breadcrumbs will also be visible in the printable page variant, otherwise not.
$wgYambeBCprintable = false;

The breadcrumbs are rendered into a div element with the id yambe, this can be used for styling with CSS.

Usage

[edit]

General

[edit]

To define the parent page of a child page, the YAMBE tag needs to be added to the child page:

<yambe:breadcrumb self='Self Text'>Parent_Title|Parent Text</yambe:breadcrumb>

NOTE: All contents of the tag must be valid XML, this forbids the usage of raw <, > and & characters, use the corresponding HTML entities &lt;, &gt; and &amp; instead.

This tag gets rendered as the breadcrumb chain to the child page, add it at the location where the breadcrumbs should be displayed. Currently, only one such tag per page is supported.

The only required element is Parent_Title, the title of the parent page. If Parent Text is given, this will be used as name for the breadcrumb of that page, otherwise the display name of the page will be used. To not specify Parent Text, don't add the pipe character |, or Parent Text will be defined as empty. If Self Text is given, this will be used as name for the breadcrumb of the current page, otherwise the display name of the current page will be used.

For the root page, use an empty Parent_Title. To suppress the display of the breadcrumbs on the root page, specify an empty Self Text. There can be more than one root page, each such page starts a new breadcrumb chain.

New Page

[edit]

To simplify the construction of breadcrumb chains, the YAMBE tag gets inserted automatically into the edit field of a new page if the page creation was triggered from a page that already contains such a tag. This happens when a red link on such a page is clicked. If in such case the tag is missing from the edit field, verify that $wgYambeURLsplit is correctly setup for your wiki.

History

[edit]

The original implementation of this extension is available under https://github.com/qtiger/yambe. However, this project was abandoned a long time ago, it is not working for recent MediaWiki versions. The currently used fork https://github.com/sodevel/yambe is a complete rewrite of the original implementation. It has been adapted for recent MediaWiki versions, fixes issues of the original implementation and especially enables the usage of the page cache, but stays fully compatible to the original definition of the YAMBE tag.

See also

[edit]