Extension:Glossary

From MediaWiki.org

Manual on MediaWiki Extensions
List of MediaWiki Extensions

Glossary Release status: stable
Implementation	Extended syntax
Description	Enable a Glossary within MediaWiki using tooltips.
Author(s)	BarkerJr, Benjamin Kahn, Sorin Sbarnea
Last Version	2008-05-28 (2008-05-28)
MediaWiki	1.6-1.13 (and maybe above)
PHP	5
License	LGPL
Download	svn
check usage (experimental)

[edit] Related Extensions

An alternative version of this extension can be found at Extension:Terminology

[edit] What can this extension do?

Ever been reading a technical article with lots and lots of acronyms? Unless you know all the terminology they are using, it can be really frustrating trying to understand what the author means.

This extension allows wiki authors to define a list of acronyms and their definitions on a special page. Whenever that acronym is found, it will be highlighted and mousing over it will reveal the definition in a tooltip.

Additionally, using Walter Zorn's "JavaScript, DHTML Tooltips" library (found at: http://www.walterzorn.com/tooltip/tooltip_e.htm ) you can customize the appearance of the tooltips.

[edit] Usage

By default, the page "Glossary" without a namespace will be used as the source of acronyms and their definitions. It's also possible to modify the extension to put the definitions in a protected namespace.

[edit] Installation

Just checkout the code from the svn to /extensions/Glossary/

[edit] LocalSettings.php

2. Add the following to the end of your LocalSettings.php:

require_once( "$IP/extensions/Glossary/Glossary.php" );

3. Create the page "Glossary"

4. Add one line to this page for each acronym. Each line should start with a ';' (semicolon), then the text to be replaced followed by a ':' (colon) followed by the text to replace it with.

[edit] Sample Glossary

;FTP:File Transport Protocol
;AAAAA:American Association Against Acronym Abuse
;ACK:Acknowledge
;AFAIK:As Far As I Know
;AWGTHTGTATA:Are We Going To Have To Go Through All This Again
;HTTP:HyperText Transfer Protocol

[edit] ToolTip

This extension will not work without the tooltip javascript library. Download wz_tooltip.zip and unpack it into a directory called extensions/tooltip.

[edit] Parameters

To lock down the glossary, modify the glossary.php file.

Find the line:

$rev = Revision::newFromTitle(Title::makeTitle(null, 'Glossary'));

and change it to:

$rev = Revision::newFromTitle(Title::makeTitle(8, 'Glossary'));

The Glossary will now be located at:

MediaWiki:Glossary

Alternatively to use a different Glossary page within each namespace, change this line to:

$rev = Revision::newFromTitle(Title::makeTitle(intval(($parser->getTitle()->getNamespace())/2)*2, 'Glossary'));

This will look at the NameSpace:Glossary page for all pages in NameSpace and NameSpace_Talk (assuming you have set any custom namespaces up following the convention of even numbers for the namespace and the following odd numbers for the corresponding talk namespaces).

[edit] Styling

It is possible to apply your own visual style to glossary words that are shown to users. Open Glossary.php and find:

  $wgOut->addHTML("<script type='text/javascript' src='$wgScriptPath/extensions/tooltip/wz_tooltip.js'></script>");

Then insert the following line below:

  $wgOut->addHTML("<style text=\"text/css\" media=\"screen\">.glossarydef {cursor: help; border-bottom: 1px dotted blue;}</style>");

Also find:

          $span->setAttribute('style', 'cursor:help');

And replace it with:

          $span->setAttribute('class', 'glossarydef');

You can change the style of glossary words by adjusting the CSS style for <nowki>.glossarydef</nowiki>. Remember that pages in MediaWiki will probably be cached and you won't see visual style changes immediately unless you append "&purge=1" to the URL of the pages you're trying to view.

[edit] Known problems

[edit] Tooltips onmouseout

See bug #20011 for more information.

As of version 5.0 of the tooltip javascript library, the tooltips get "stuck" on the cursor.

1. Open Glossary.php in a text editor
2. Find line 88: $span->setAttribute('onmouseover', "TagToTip('$term')");
3. Add a new line after it:

 $span->setAttribute('onmouseout', 'UnTip()');

[edit] Escaping forward slashes for PCRE functions

See bug #20008 for more information.

On line 82 within the glossaryParseThisNode function, the following code exists:

    $texts = preg_split('/\b(' . preg_quote($term) . 's?)\b/iu', $node->textContent, -1, PREG_SPLIT_DELIM_CAPTURE);

preg_quote() is meant to escape special regular expression characters from glossary terms. However by default it will not escape the forward slash character that has special meaning in PCRE regular expression functions. You will therefore need to change line 82 to:

    $texts = preg_split('/\b(' . preg_quote($term, '/') . 's?)\b/iu', $node->textContent, -1, PREG_SPLIT_DELIM_CAPTURE);

Without this fix, glossary terms containing a forward slash may cause a lot of rendering errors that make your MediaWiki installation unusable.

[edit] Incompatibility with CrossReference

See bug #20009 for more information.

CrossReference does not work properly with the Glossary extension because Glossary will parse the text before CrossReference does, mangling the cross references in the process. Glossary should not work for <a> elements (hyperlinks). To solve this problem, inside Glossary.php, find:

  if ($node->nodeType == XML_TEXT_NODE) {

And replace that line with the following code:

  $parent_node = $node->parentNode;
  if ($parent_node && $parent_node->nodeType == XML_ELEMENT_NODE) {
    $tag_name = $parent_node->tagName;
  }
  if ($node->nodeType == XML_TEXT_NODE && $tag_name != 'a') {

[edit] Multiple HTML tags in output

See bug #20010 for more information.

The Glossary plugin will create multiple <html> tags within the same output page which is invalid and causes undefined browser rendering behaviour. This has been reproduced with MediaWiki 1.15.0 and is caused by ParserBeforeTidy only parsing the user content of the page (rather than the entire HTML output that is sent to the client). To resolve this problem, open up Glossary.php and find:

            if (glossaryParseThisNode($doc, $doc->documentElement, $term)) {

And replace it with:

            $body_element = $doc->getElementsByTagName('body')->item(0);
            if (glossaryParseThisNode($doc, $body_element, $term)) {

Then a few lines down, find:

              $doc->documentElement->appendChild($span);

And replace with:

              $body_element->appendChild($span);

Finally, find:

         $text = $doc->saveHTML();

And insert the following immediately below:

        $text = substr($text, strpos($text, '<body>'), -16);

[edit] Don't parse empty content

See bug #20012 for more information.

Glossary will attempt to parse zero length content and as a result, it may cause everything to fail. The simple fix is to open Glossary.php and find:

  if ($rev) {

And replace with:

  if ($rev && $text) {