Q: How does the Glossary of IT Terms work?
- How does the glossary work?
- What's behind the IT glossary in the Knowledge base?
Context
- This knowledge base and help system
- Glossary of IT Terms
Answer
Overview
- The IT glossary lives in a separate space on the Knowledge Base called "glossary"
- A special theme is applied to provide an alphabet navigation bar across the top of pages
- A special embedded form to add new pages (terms) to the glossary is available from the index pages; it is visible only to those users able to create pages in the "glossary" space
- A special sidebar module is displayed allowing definition look-up in Google and Wikipedia
- The page hierarchy is used in the special glossary space to organize and browse definition pages by their first letter
Space layout
The "glossary" space is laid out as follows:
- The space home page is called Glossary
- The space home page has 27 child pages with the names:
- Each "letter" child page has in turn definition pages for terms beginning with that letter as children
- The {children} macro is used to display the full glossary on the home page, and the letter subset on each letter index page
- The {children} macro is used with the excerpt option to display definitions on the index pages
- Pages in the glossary will typically have the "glossary" label applied
- Index pages in the glossary have the "index" label applied; this is important as it affects the behavior of the sidebar glossary macro
User macros related to glossary
- glossary-panel
- The glossary-panel macro is used in the glossary theme's sidebar
- It displays a panel and constructs links to look up the currently viewed term in Google and Wikipedia
- It uses the "index" label to determine whether it is on a definition page or an index page
- If the "index" label is present it will assume it is on an index page and will display generic links to Wikipedia and Google definitions search
- If the "index" label is not present it will assume it is on a definition page and that the page title is the term being defined; it will construct links to search for that term in Google and Wikipedia
- edit
- The edit macro is used in the glossary theme to provide edit controls at the top of each page
- This macro is displayed only to users with the permissions to edit and create pages in the glossary space
- There's a bit of a risk here because index pages can also be easily edited, but it is manageable
- show-to
- The show-to macro is used on index pages to hide author information from non-authors
- It is used to hide the "Tips for authors" section at the top of the page
- It is used to hide the create-glossary-term form at the bottom of the page
- create-glossary-term
- The create-glossary-term macro inserts a simple text box into a glossary index page to allow users with author permissions to enter a term and create a new page for it using the glossary template
Templates
The glossary uses a single global template for its definition pages called "Glossary term". It suggested a layout similar to other content pages with the term to be defined pulled into the level one major heading, and will apply the "glossary" label to the page by default.
Adding new definitions
Please see the page [istdraft:How do I add a new term to the glossary?] for more information.