Skip to content

Usage

Introduction

This MODX Extra adds a custom manager page that allows you to create and maintain a list of explanations for key terms in your site. Entries into the glossary take the form of term => explanation where term is the phrase being described and explanation is the description of said term.

Included in the package is a snippet called Glossary which will output the glossary terms to a resource page. The snippet is fully templatable using chunks specified as optional parameters to the snippet call, and various features can be turned on or off in the same manner.

Snippet

This snippet outputs a list of terms and explanations, ordered alphabetically and grouped by first letter. It also outputs a navigation list of links at the top of the glossary list to allow a user to jump to a specific letter. The following properties could be set in the snippet call:

Property Description Default
showNav Show the letter nav at the top of the list. 1 (Yes)
showEmptySections Show empty sections in the quick-nav bar at the top of the glossary. 0 (No)
outerTpl Template chunk for glossary outer wrapper. Glossary.listOuterTpl
groupTpl Template chunk for glossary item group. Glossary.listGroupTpl
termTpl Template chunk for glossary term items. Glossary.listItemTpl
navOuterTpl Template chunk for outer nav-bar wrapper. Glossary.navOuterTpl
navItemTpl Template chunk for each item in the nav-bar. Glossary.navItemTpl
toPlaceholder If set, will assign the result to this placeholder instead of outputting it directly. 1 -

Plugin

The GlossaryHighlighter plugin parses the content field of a resource on render and replaces all occurrences of the terms with the markup defined in the plugin's tpl chunk. This can be used to provide a link directly to the glossary entry for that term.

The plugin does not replace terms:

  • in the resource referenced by the glossary.resid system setting,
  • in static resources, weblinks, symlinks and resources with a content type other than text/html or application/xhtml+xml,
  • in HTML tags and their attributes, HTML comments, HTML entities and MODX tags,
  • inside script, style and textarea elements and inside the elements listed in the glossary.disabledTags system setting,
  • inside a longer term that contains the shorter term (longer terms are replaced first).

The resource cache is cleared each time a term is created, updated or removed, so that cached resources show the changed terms.

The plugin could be controlled by the following MODX system settings:

Setting Description Default
debug Log debug information in the MODX error log. No
disabledTags Comma-separated list of HTML tags Glossary does not replace text inside. The content of script, style and textarea tags is never replaced. a,form,select
fullwords Replace only full words of a glossary term in the resource content. 2 Yes
html Allow HTML in the explanation (enables a rich-text editor in the term form). Yes
resid ID of a resource containing a Glossary snippet call. 0
sections Replace Glossary links only in sections marked with <!-- GlossaryStart --> and <!-- GlossaryEnd -->. The section markers could be changed with the settings glossary.sectionsStart and glossary.sectionsEnd. No
sectionsEnd Marker at the end of a section processed by Glossary. The restriction to marked sections can be activated in the setting glossary.sections. <!-- GlossaryEnd -->
sectionsStart Marker at the start of a section processed by Glossary. The restriction to marked sections can be activated in the setting glossary.sections. <!-- GlossaryStart -->
tpl Template Chunk for the highlight replacement. Glossary.highlighterTpl

The following optional system settings are not created during the installation. You can create them in the glossary namespace, if you want to restrict the plugin to some contexts or templates:

Setting Description
enabledContexts Comma-separated list of context keys, in which the terms are highlighted.
enabledTemplates Comma-separated list of template IDs, in which the terms are highlighted.

Available placeholders

The following placeholders are available in the chunks used by the snippet and the plugin or in the resource output:

Placeholder Description Chunk
link Link url including hash anchor. highlighterTpl
html 1 if the system setting glossary.html is enabled, otherwise empty. highlighterTpl
groups The list of term groups. outerTpl
items The list of terms. groupTpl
anchor The anchor for the term being referenced. listItemTpl
term The term being referenced. listItemTpl, highlighterTpl
explanation The explanation for this term. In the highlighterTpl chunk it is HTML-escaped, so it can be used in an attribute. listItemTpl, highlighterTpl
letters The list of letters in the letter nav. navOuterTpl
letter One letter in the letter nav or the letter of the current group. groupTpl, listItemTpl, navItemTpl
class disabled for an empty section (if showEmptySections is enabled), otherwise empty. navItemTpl
placeholder Optional placeholder, that is created by the toPlaceholder property: The whole snippet output 3 Resource output
placeholder.nav Optional placeholder, that is created by the toPlaceholder property: Outputs the nav only 3 Resource output
placeholder.items Optional placeholder, that is created by the toPlaceholder property: Outputs the items (terms & explanations) 3 Resource output

The default chunks for these placeholders are available with the Glossary. prefix. If you want to change the chunks, you have to duplicate them and change the duplicates. The default chunks are reset with each update of the Glossary extra.


  1. If you fill the toPlaceholder property i.e. with the value glossaryResult, the placeholder [[+glossaryResult]] is filled by the output of the snippet. This also creates two additional placeholders: [[+glossaryResult.nav]] and [[+glossaryResult.items]]. ↩

  2. A term is treated as a full word, if it is not preceded or followed by a letter, a number or an underscore. This also works with terms containing special characters and with terms next to HTML entities. ↩

  3. See the toPlaceholder snippet property. ↩↩↩