|
Cookbook /
GlossaryPlusSummary: Glossary Plus
Version: 2012-01-23
Prerequisites: pmWiki-2.2.x and JavaScript, DHTML Tooltips Library by Walter Zorn
Status: Beta
Maintainer: Kaptainkory
Categories: FunctionalExtensions, Links
Questions answered by this recipeHow can I create an integrated glossary for my site? DescriptionThis script creates a cross-linked glossary with the following default features:
Minimum InstallationStep 1Download the latest version of the JavaScript, DHTML Tooltips Library(approve links) 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 2Download glossaryplus.phpΔ and save it to your cookbook folder. pmwiki/cookbook/glossaryplus.php Step 3Add 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 4Create a wiki page for your glossary. The default is "Main.Glossary". List your items using definition list formating ( :term:defintion ). CustomizationsChanging Default OptionsThe 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.
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.phpThe 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");
}
}
StylingStyling may be accomplished a number of different ways, such as using
/* 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
: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.
:Term: Definition with ''emphasis'' and %red%color%%.
>>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.
:Term: Definition line one. \\ And line two. \\ And line three.
:Term: %lfloat width=20 height=20%Attach:Main.Glossary/defimg.gif"Alt text"%% Explanation of picture.
:Term: (:include Main.Glossary#DefTableStart#DefTableEnd:) >>display=none<< [[#DefTableStart]] ||border=1 || cell1 || cell2 || [[#DefTableEnd]] >><<
:Term:(:include Main.Glossary#DefStart#DefEnd:) >>display=none<< [[#DefStart]] ||border=0 || Attach:Main.Glossary/defimg.gif || Text explanation... \\ ...with multiple... \\ ...lines even! || [[#DefEnd]] >><<
: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}
[[#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
This will show how to protect a glossary [=term=] from being processed by the script.
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 DirectivesTerms may be customized on an individual basis using a (:gloss:) directive, with the following arguments available.
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
Demo and Live Examples
Release Notes
ContributorsSee AlsoComments and Bug ReportsPrevious comments have been removed as of 2009-06-07 as they (likely) will not apply to the current script. I am very new to this so any help would be greatly appreciated including advice on how best to post bug reports. I followed the instructions as of June 23rd and receive this error message when trying to open my pmwiki: "Parse error: syntax error, unexpected T_VARIABLE in /homepages/2/d210009773/htdocs/wiki/local/config.php on line 166" I am using clean URLs as well as the Skittlish skin if that makes a difference. Line 166 of my config.php file is the third of the five that are supposed to be pasted into the config.php: $PageTextStartFmt .= "'></script>"; I have checked and rechecked that I followed the steps exactly as described. It seems like this is supposed to be pointing to the javascript file that I uploaded to the /pub/wz_tooltip/ directory and it is not finding it but that is a pretty much completely a guess. Thanks in advance for any help! Typo in instructions has been corrected. Try this: $PageTextStartFmt .= "$PubDirUrl/wz_tooltip/wz_tooltip.js"; Kaptainkory June 28, 2009, at 03:19 AM Thanks so much! That did the trick. Lost Walter Zorn librariesI have used this recipe for some time (thank you) and decided to look at the revised offering - which appears to have been added with no apparent problems. However, the libraries referred to in the opening instructions regarding installation of the recipe are gone from the given location: JavaScript, DHTML Tooltips Library by Walter Zorn, and the link now just leads to a parked domain. Perhaps another source can be identified and added where these may be found, to assist anyone that may be interested in using the glossary. Des June 19, 2011, at 12:59 PM Added wz_tooltip.js.txtΔ locally. Utopiah December 19, 2011, at 09:42 AM Possible bug disrupting url and properties generated by PmWiki for page logoPmWiki allows the user to define a logo - via PmWiki also creates the title property so that this logo shows a tooltip with the page name - and this also seems to be the same title which is applied to the displayed page. I am running the newest version of GlossaryPlus, and this appears to have introduced a bug to the internal formatting of the properties of this logo, and which was not present in the first version of GlossaryPlus. When the recipe is activated by a glossary term being present on a page, the recipe appears to be identifying something in the scripting around the logo and identifying it as glossary item, and rewriting the html associated with the clickable page logo, thereby corrupting it. The page title is changed to a long piece of html, the tooltip associated with the logo is changed to the same html, and a segment of this html appears in the top left corner of the page, behind the page logo. This does not happen on pages where there are no glossary items present, and the recipe is not active. This can be seen on this page: www.secretscotland.org.uk/index.php/Secrets/AABatteryBallymenach While this page has no glossary items, and is unaffected: www.secretscotland.org.uk/index.php/Secrets/InchinnanOldParishChurch Everything else seems to be running normally, as expected. Happy to provide more info if needed. Des January 05, 2012, at 09:31 AM Des, I have been unable to replicate your issues so far. Depending on when you downloaded the script, I did introduce an oopsy which was corrected a few hours later, but still the same release date. Please download again and see if the issues are not corrected. Regardless, I am 99% sure the problem is not in If the newest script doesn't fix it, I may follow up for more info. If I can't replicate it, I can't fix it. Thanks for the feedback. kaptainkory January 05, 2012, at 07:36 PM Thanks for the quick note, and the update. Although it did not fix the problem I see, it might have pointed at the cause! I was on this page: www.secretscotland.org.uk/index.php/Secrets/EskdalemuirSeismologicalRecordingStation when I installed the update, and as can be seen this has a glossary entry, but did not produce the spurious text string in the top left corner. Things looked good. But when I returned to the example page given above: www.secretscotland.org.uk/index.php/Secrets/AABatteryBallymenach the string was still in the corner. Then I noticed an almost invisible difference - the title of the page included a glossary entry! It is hard to see in the large bold type, but the 'AA' in the title (in this case AA Battery Ballymenach) is the cause of the spurious text. As far as I can see, PmWiki inserts the page title into the 'title' property of the site logo at top left. If this title also happen to include a glossary term, then this is rewriting the entry, and upsetting that title property. I created a duplicate of the Eskdalemuir page, with the AA added in the page title. It can be seen here: www.secretscotland.org.uk/index.php/Secrets/AAEskdalemuirStation As can be seen, the spurious text has now appeared top left, although the page content is the same as that of the original Eskdalemuir page. I would happily just use the usual trick to deal with this (and I often do this if I find a section heading includes a glossary term), but as the page title is created internally by PmWiki, this is not an option. Fingers crossed this will let you reproduce the symptom - and if so, that is it an easy fix :-) Anything else I can try or test, just ask. Des January 06, 2012, at 05:11 AM Des, I believe you are correct on where the glossary script is erroneously matching a term. However, PmWiki does not insert a title property for the site logo as you claim...at least it doesn't for the latest version and default skin. I've set up a fresh wiki to try to break, but have been unable to do so. Please, feel free to see if you can break it: http://herpsofarkansas.com/wikitest/pmwiki.php(approve links) I'm using the following GlossaryPlus settings in config:
$PageLogoUrl = 'http://herpsofarkansas.com/wikitest/pub/images/wikilogo.gif';
$PubDirUrl = 'http://' . $_SERVER['HTTP_HOST'] . '/wiki/pub';
$PageTextStartFmt = "\n<script type='text/javascript' src='$PubDirUrl/wz_tooltip/wz_tooltip.js'></script>\n<div id='wikitext'>\n";
include_once("$FarmD/cookbook/glossaryplus.php");
I'd be happy to try a different skin or different config, if it might help in troubleshooting. At this point, I can only conclude that the latest GlossaryPlus script functions correctly for the latest PmWiki and default skin. And that's about all I can do unless given another lead on what might be happening. Again, if I can't replicate it, I can't fix it. If it comes to it, you might just go to the cookbook attachments and fall back to the older version of the script. The recent revisions have made no upgrades or changes at all in how the script functions. kaptainkory January 07, 2012, at 09:10 PM When you mentioned skins, I thought I should carry out a quick check, and let you know the findings ASAP. The normal site skin is Monobook, where I have been seeing the symptom reported to you. I have Triad installed as a switchable option, as its layout can make heavy editing sessions easier. When I switched to Triad, and looked at the Ballymenach page referred to above - the spurious text did NOT appear. (Obviously this is similar to the test site you set up, which used the default PmWiki skin.) You can find the skin switching option hidden on the menu on the left of the secretscotland.org.uk/index.php/Manual/TextFormatting page - just select Monobook or Triad to set either skin. If you try this and go to the Ballymenach page after setting Triad skin, there is no spurious text on the page. Also, under Triad, the 'AA' abbreviation in the article title is NOT detected by GlossaryPlus, and is not given a tooltip, or made into a link leading to the Glossary entry. Other glossary items in the page text work normally. I'm not sure what this means, but it does suggest something in the Monobook skin is contributing to the appearance of the text. Maybe I should be apologizing, and this is down to something structured into Monobook, and GlossaryPlus is working as intended. I do like to try and keep software up-to-date for obvious reasons, but since you say the revisions don't involve any sort of upgrade or functionality, then I'm not losing anything by going back. (Can I ask if there were any changes to the locations of directories or files though? I seem to remember having to fiddle with these to get things working after installing the later script - but that just might have been me misreading the relevant details, and putting something in the wrong place to start with.) Des January 08, 2012, at 11:54 AM Des, I still can't explain why the old GlossaryPlus script worked and the new one didn't (the changes made should not have made any observable/functional differences), but I'm calling the issue closed for now. The culprit does appear to be the Monobook skin. Likely there should be a Keep() function in the skin around the title processing--specifically to the template variable $Titlespaced--that would prevent additional markup processing (such as we see from GlossaryPlus). Apparently, the preventative Keep() function is not there, but I am not interested in troubleshooting someone else's skin. A quick solution would be to add the following to your config: $SkinPartFmt['wikititle'] = "$WikiTitle"; You will have less title than before, but it'll give you a place to start if you want to work on the issue further. And no, no changes to locations/directories for files were changed in the latest version. I do admit though that this can be a tricky part of getting the recipe to work. Thanks for your feedback and help. kaptainkory January 08, 2012, at 11:50 PM Yes, time to step back as the source lies elsewhere - but thank you very much for the checking that led to the cause. I incorporated the quick fix, and it does indeed remove the offending scrap - and alter the title a bit. I actually use an earlier version of Monobook - a later one updated the appearance a little, but I did not like the revisions. But, I still have both versions installed, and tried the newer one. It still throws the spurious text, but unlike the earlier version, the text includes the whole page title, not just the latter part seen during out discussions. I really tried it to see if the markup processing might have been updated as per your suggestion, but obviously it had not. (As this whole section is not really relevant to the recipe, you may wish to purge (or move) it now - I don't really see much reason to keep it here.) 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. |