cogMacro to reference glossary entries and API needed for the Glossary Application
TypeJAR
Category
Developed by

Sarthak Gupta, Vincent Massol, slauriere

Active Installs53
Rating
0 Votes
LicenseGNU Lesser General Public License 2.1

Installable with the Extension Manager

Description

Provides:

  • a Rendering Transformation 
  • a Rendering Macro
  • Java APIs

This API is used by the Glossary Application.

Transformation

A Rendering Transformation (glossary) is available. When enabled and when a wiki page is rendered, this transformation will look for words matching glossary entries, and, when found, it'll automatically generate a link to the page defining the glossary entry.

Note that enabling the transformation is costly since all words of all pages will be scanned at each rendering, to find glossary entries. This is why a Macro is also provided (see below).

Macro

A {{glossaryReference/}} macro is provided to reference explicitly a glossary entry. This can be used when the glossary transformation is not enabled.

Usage: 

{{glossaryReference entryId="entryId" glossaryId="glossaryId"}}content{{/glossary}}

Where:

NameOptionalAllowed valuesDefault valueDescription
entryIdyesDocument nameNoneWhen not specified, the macro content will be used as the document name of the glossary entry referenced. Note that both the entryId and the content correspond to the document name of the wiki page reference only, e.g. LOL# for a glossary entry at Glossary.LOL.
glossaryIdyesSpace nameGlossaryWhen specified, defines the glossary being referenced. Technically this corresponds to the space name in which the Glossary is located, e.g. Glossary2 for a Glossary having entries in the Glossary2 space.

API

The following component roles are provided:

  • @Role
    public interface GlossaryModel
    {
       /**
         * Find all existing Glossary definition in the current wiki.
         *
         * @return the map containing the glossary entries with the index being the Glossary page name
         * @throws GlossaryException when an error happens when finding Glossary entries
         */

        Map<String, DocumentReference> getGlossaryEntries() throws GlossaryException;

       /**
         * @param entryReference the reference to the glossary entry for which to get the definition/content
         * @return the parsed content
         * @throws GlossaryException in case of an error
         */

        XDOM getGlossaryContent(DocumentReference entryReference) throws GlossaryException;
    }
  • @Role
    public interface GlossaryCache
    {
       /**
         * Get the value associated with the provided key in the cache.
         *
         * @param key of type String
         * @return the DocumentReference
         */

        DocumentReference get(String key);

       /**
         * Sets the key and value in the cache.
         *
         * @param key represents the glossaryItem.
         * @param value representing the DocumentReference of glossary Document.
         */

       void set(String key, DocumentReference value);

       /**
         * Remove the key and value pair from the cache.
         *
         * @param key represents the glossaryItem.
         */

       void remove(String key);
    }

Prerequisites & Installation Instructions

We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager).

You can also use the manual method which involves dropping the JAR file and all its dependencies into the WEB-INF/lib folder and restarting XWiki.

Dependencies

Dependencies for this extension (org.xwiki.contrib.glossary:application-glossary-api 1.0.4):

Tags:
    

Get Connected