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.residsystem setting, - in static resources, weblinks, symlinks and resources with a content type
other than
text/htmlorapplication/xhtml+xml, - in HTML tags and their attributes, HTML comments, HTML entities and MODX tags,
- inside
script,styleandtextareaelements and inside the elements listed in theglossary.disabledTagssystem 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.
-
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]]. ↩ -
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. ↩