GlossaryPlus

Summary: Glossary Plus

Version: 2015-01-01

Prerequisites: pmWiki-2.2.58+ and JavaScript, DHTML Tooltips Library by Walter Zorn

Status: Beta

Maintainer: Kaptainkory

Categories: FunctionalExtensions, Links

Discussion: GlossaryPlus-Talk

Questions answered by this recipe

How can I create an integrated glossary for my site?

Description

This script creates a cross-linked glossary with the following default features:

Terms and definitions are maintained on a separate glossary page using the format ( :term:definition ).
Each term from the glossary page that appears on the current page will be converted as follows:
- It will link back to its matching definition on the glossary page.
- On mouseover, a tooltip will show its definition.
A (:gloss:) directive may be applied to individual glossary terms for special treatment.
Look and feel are highly customizable.

Minimum Installation

Step 1

Download the latest version of the JavaScript, DHTML Tooltips Library by Walter Zorn. Save the library script to your web server where it can be accessed by PmWiki. One can download the local wz_tooltip.js.txt Δ downloaded from the official demo.

pmwiki/pub/wz_tooltip/wz_tooltip.js

In addition, you may include the library extension scripts (tip_centerwindow.js and tip_followscroll.js), although these are not necessary for default functionality.

Step 2

Download glossaryplus.php Δ and save it to your cookbook folder.

pmwiki/cookbook/glossaryplus.php

Step 3

Add the following lines to your config.php file:

$PageTextStartFmt = "\n<script type='text/javascript' src='";
$PageTextStartFmt .= "$PubDirUrl/wz_tooltip/wz_tooltip.js";
$PageTextStartFmt .= "'></script>";
$PageTextStartFmt .= "\n<div id='wikitext'>\n";
include_once("$FarmD/cookbook/glossaryplus.php");

Alternately, you may manually add the tooltip <script> to your template file (pmwiki.tmpl) just below the <body> tag. The script library will not work (and it will complain with javascript alert warnings!) if placed in the <heading> section.

Step 4

Create a wiki page for your glossary. The default is "Main.Glossary". List your items using definition list formating ( :term:defintion ).

Customizations

Changing Default Options

The following variables may be set in your config.php file BEFORE calling the glossaryplus.php script:

# Set the glossary page.
$GlossaryPlus['PageName'] = 'Main.Glossary';

# Add additional terms and definitions ( 't1' => 'd1', 't2' => 'd2' ).
$GlossaryPlus['TermsAndDefinitions'] = array();

# Set case sensitivity.
$GlossaryPlus['CaseSensitive'] = false;

# Set maximum number of times a term is processed per page.
$GlossaryPlus['MaxToolTipsPerTerm'] = 5;

# Set if term links back to Main.Glossary#Term; otherwise links to Main.Glossary.
$GlossaryPlus['LinkToTerm'] = true;

# Set class for term link.
$GlossaryPlus['TermClass'] = 'glossterm';

# Set class for definition tooltip.
$GlossaryPlus['DefClass'] = 'glossdef';

# Set warnings for missing terms used in directives.
$GlossaryPlus['DirectiveWarnings'] = true;

The HTML patterns used for the terms and tooltips are customizable.

# Set HTML for term link.  See glossaryplus.php for default.
$GlossaryPlus['ToolTipDefPattern'] = ...;

# Set HTML for definition tooltip.  See glossaryplus.php for default.
$GlossaryPlus['ToolTipTermPattern'] = ...;

The following variables may be used in the HTML patterns.

{GP_TERM}
- Replaced by glossary term.
{GP_DEF}
- Replaced by glossary definition of term.
{GP_TT}
- Used by the script to properly place the tooltip code.
{GP_COMMANDS}
- Tooltip commands; see JavaScript, DHTML Tooltips Library.
{GP_URL}
- Link used for term.
{GP_PAGENAME}
- Resolved pagename of glossary, such as "Main.Glossary".
{GP_GROUP}
- Resolved group of glossary, such as "Main".
{GP_PAGE}
- Resolved page of glossary, such as "Glossary".

The definition tooltips are customizable according to commands listed on the JavaScript, DHTML Tooltips Library homepage. Commands may be set singly...

$GlossaryPlus['ToolTipCommands']['SHADOW'] = true;

...or as an array. Default settings (shown below) allow for much of the look to come from CSS.

$GlossaryPlus['ToolTipCommands'] = array(
	'BGCOLOR'	=> '',
	'BORDERWIDTH' 	=> 0,
	'PADDING'	=> 0,
);

The following are for advanced usage only. The script attempts to protect terms from processing if they occur nested in other HTML code, but may fail under certain situations. If you are getting gibberish code appearing from overzealous processing (or if terms that should be processed aren't), you may need to adjust these settings. Matching uses lookahead ( ?= ?! ) and lookbehind ( ?<= ?<! ) assertions. Lookbehind assertion are restricted such that all the strings it matches must have a fixed length. See glossaryplus.php for default.

$GlossaryPlus['PreTermMatch'] = ...;
$GlossaryPlus['PostTermMatch'] = ...;

Example config.php

The following config.php snippet may give you some ideas about how to use this recipe most efficiently.

# Get page and group names.
$pagename = ResolvePageName($pagename);
$page = PageVar($pagename, '$FullName');
$group = PageVar($pagename, '$Group');

# Only call recipe if "browsing" (not "editing", etc.)
if ($action == 'browse') {
AND current group is not Site, SiteAdmin, or PmWiki.
	if ($group != 'Site' && $group != 'SiteAdmin' && $group != 'PmWiki') {

		# Include script at page text start (instead of copying into template).
		$PageTextStartFmt = "\n<script type='text/javascript' src='";
		$PageTextStartFmt .= $PubDirUrl/wz_tooltip/wz_tooltip.js
		$PageTextStartFmt .= "'></script>";
		$PageTextStartFmt .= "\n<div id='wikitext'>\n";

		# Increase the maximum times that a term is converted to link/tooltip per page.
		$GlossaryPlus['MaxToolTipsPerTerm'] = 5;

		# Change the look and behavior of tooltips.
		$GlossaryPlus['TermClass'] = '';
		$GlossaryPlus['DefClass'] = '';
		$GlossaryPlus['ToolTipCommands'] = array(
			'BGCOLOR'	=> '#38fff2',
			'BORDERCOLOR'	=> '#a9ff38',
			'BORDERWIDTH'	=> '2',
			'FONTCOLOR'	=> '#cc2d30',
			'FONTSIZE'	=> '1.2em',
			'PADDING'	=> '15',
		);

		# Include Glossary Plus script.
		include_once("$FarmD/cookbook/glossaryplus.php");
	}
}

Styling

Styling may be accomplished a number of different ways, such as using $HTMLStylesFmt. However, it may be easiest just to copy-and-paste the following code into your CSS and adjust it to suit.

/* Glossary Plus - Start */

a.glossterm {
	color: #2e2f8f;
	font-weight: normal;
	text-decoration: none;
}

a.glossterm:hover {
	border-bottom: 1px dotted #2e2f8f;
	border-top: 1px dotted #2e2f8f;
}

h1 a.glossterm, h2 a.glossterm, h3 a.glossterm, h4 a.glossterm {
	color:inherit;
	font-weight:inherit;
}

div.glossdef {
	padding: 2px;
	color: #000000;
	background: #f7f7f7;
	border-top: 1px solid #cccccc;
	border-left: 1px solid #cccccc;
	border-right: 2px solid #cccccc;
	border-bottom: 2px solid #cccccc;
}

dt {
	font-weight: bold;
	border-top: 1px solid #cccccc;
}

dd {
	margin: 0px 0px 5px;
}

/* Glossary Plus - End */

Suggestions for Glossary Page

Include special characters for a term or in a definition. The script should be quite tolerant of using special characters, but there may be a few special situations.

:Crazy /\*?^$(){}<>=!|#@-"'.&+ Characters: These work! Also in definitions: /\+*?^$(){}<>=!|#@-"'.&+
:Te[=:=]rm: Appears correct on glossary page; fails by script.
:'''Term''': Appears correct on glossary page; fails by script.

Include formating within a definition. This is straightforward and is the same as with any regular wiki page.

:Term: Definition with ''emphasis'' and %red%color%%.

Include formating for a term. You have to be a little careful with this to preserve correct processing. It is best to apply formating to the <dt> tag using a separate CSS.

>>red<<
:Term: Term and definition red in glossary; plain in tooltip.
>><<

:%red%Term%%: Term red, definition plain in glossary; fails by script.
:Term: Term red, definition plain in glossary; red in tooltip. %apply=block color=red%
:Term: Term red, definition plain in glossary; plain in tooltip %apply=item color=red%
%red%:Term:%% Does not work, really, for either.

Include multiple lines in a definition.

:Term: Definition line one. \\
And line two. \\
And line three.

Include an image in a definition (and float it left). The tooltip library likes width and height specified for images.

:Term: %lfloat width=20 height=20%Attach:Main.Glossary/defimg.gif"Alt text"%% Explanation of picture.

Include a table in a definition. This is a little more complex because of how the wiki coding is handled (although there may be a simpler solution?).

:Term: (:include Main.Glossary#DefTableStart#DefTableEnd:)

>>display=none<<
[[#DefTableStart]]
||border=1
|| cell1 || cell2 ||
[[#DefTableEnd]]
>><<

Include a picture and text inside a table to produce a nice layout for tooltips.

:Term:(:include Main.Glossary#DefStart#DefEnd:)

>>display=none<<
[[#DefStart]]

||border=0
|| Attach:Main.Glossary/defimg.gif || Text explanation... \\
...with multiple... \\
...lines even! ||

[[#DefEnd]]
>><<

Make use of PageTextVariables. You have to be a little careful with these as shown below.

:Term1: Plain definition.
:Term2: Works fine: {$:Term1}
:Term3: Works fine if TermAP is from another page: {Another.Page$:TermAP}
:Term4: %red%Definition with other wiki code.%%
:Term5: Works fine again: {$:Term4}

Deal with iterations ('-s', '-ing', etc.) of a term. The following prevents iterations from appearing on the glossary page, preserves anchors, and shows how to reuse definitions.

[[#Terms]][[#Terming]][[#TermTwice]][[#TermAgain]]
:Term: The primary definition.

>>display=none<<
:Terms: {$:Term}
:Terming: {$:Term} The -ing definition
:Term Twice: Notice to remove spaces in named anchor.
:Term Again: {$:Term Twice} Will fail; must be one word for variable.
>><<

Suggestions for Terms

Prevent an occurrence of a term from being processed.

This will show how to protect a glossary [=term=] from being processed by the script.

Watch for situations where a term will NOT be processed. Basically, the script attempts to prevent processing of terms when nested inside other HTML tags.

If you have a term: followed by a colon, it will not be processed.

If you are sure your terms will not show up, for example, as ( style='color: red; term: 1px' ), you may unset the preventative pattern match.

$GlossaryPlus['PostTermMatch'][':'] = '';

Alternately, for this example, the following will allow the term to be processed as expected.

If you have a term[==]: like this, it will be processed.

Using Directives

Terms may be customized on an individual basis using a (:gloss:) directive, with the following arguments available.

term=
- Set glossary term.
link=
- Set alternative link.
termclass=
- Set different CSS class for term.
defclass=
- Set different CSS class for definition tooltip.
commands=
- Set custom commands from tooltip library.
text=
- Set alternative text.

The following show some examples for use.

Same as default behavior.
(:gloss Term:)
(:gloss term="Term":)

Link is to another page.
(:gloss term="Term" link="Main.HomePage":)
(:gloss link="Main/HomePage" Term :)

Different CSS class is applied ( or removed with defclass="" ).
(:gloss Term termclass="AnotherClass" defclass="":)

Custom commands applied from tooltip library.  You may want to clear the CSS classes for these.
(:gloss term="Term" commands="SHADOW, true, TITLE, 'Special Title'":)

Alternate text shown, but link and definition are for Term.
(:gloss term="Term" text="Alternative":)

Combination of commands.
(:gloss term="Term" link="Main.HomePage" text="Alternative":)

Bugs and Known Issues

The script does have a few idiosyncrasies, so you'll want to read the documentation provided above.
The variable $GlossaryPlus['MaxToolTipsPerTerm'] may give slightly unexpected results due to what is considered a "page". If set to 5, for example, the first five occurrences of a term on the main page will be converted, as will the first five occurrences on the SideBar.
Probable bug of tooltip library in FireFox 3.0.8 (and likely other browsers): PADDING and SHADOW do not work well when used together. SHADOW rendering is too long.

Demo and Live Examples

The script is currently active on the following website.
- Herps of Arkansas, Glossary
Please list your website that uses this recipe.
- Secret Scotland Retrieved January 04, 2012 01:24:17.
  - Glossary Retrieved January 04, 2012 01:26:57.

Release Notes

2015-01-01: Removed depreciated PHP code.
2012-01-23: Minor fix to make XHTML validators happier.
2012-01-05: Hopefully fixed bug introduced in previous version.
2012-01-03: Simply fixed a few php exceptions that were being thrown with E_STRICT.
2009-06-12: Bugs squashed. TagToTip() now using Tip(). Directive (:gloss:) argument "class" is now "termclass" and "defclass". Removed {GP_ID}, added {GP_TT}.
2009-06-11: Bugs squashed.
2009-06-10k: Pretty major rearrangement of code; actually simplified it. Could have introduced new bugs?
2009-06-10: Bugs squashed.
2009-06-09: Several bugs squashed, especially concerning looping of terms in other definitions.
2009-06-08: Added (:gloss term="Term":) directive. Several bugs squashed.
2009-06-07: Completely new script! Should be improved in ALL areas. New tooltip library used.
2008-01-03: Corrected bug causing strange behavior with AuthUser
2006-02-07: Minor bug fixes and enhancements
2006-02-04: Minor bug fix to link back to glossary correctly.
2006-02-03: Initial release.

Contributors

Kaptainkory

Comments

See discussion at GlossaryPlus-Talk

User notes ? : If you use, used or reviewed this recipe, you can add your name. These statistics appear in the Cookbook listings and will help newcomers browsing through the wiki.