# Glossary Management

The Glossary provides a shared, searchable reference of terms and definitions used across the educational portal. All users can browse and search the glossary at any time. Administrators manage the content — adding, editing, deleting, and importing terms in bulk — through a separate administration view.

## Table of Contents

* [Overview](#overview)
* [Browsing the Glossary](#browsing-the-glossary)
  * [Navigating by Letter](#navigating-by-letter)
  * [Searching for a Term](#searching-for-a-term)
  * [Exporting the Glossary](#exporting-the-glossary)
* [Glossary Administration](#glossary-administration)
  * [Opening the Administration View](#opening-the-administration-view)
  * [Finding Terms in the Table](#finding-terms-in-the-table)
  * [Adding a New Term](#adding-a-new-term)
  * [Editing a Term](#editing-a-term)
  * [Deleting a Term](#deleting-a-term)
* [Importing Terms from a CSV File](#importing-terms-from-a-csv-file)
  * [Preparing the Import File](#preparing-the-import-file)
  * [Choosing an Import Mode](#choosing-an-import-mode)
  * [Running the Import](#running-the-import)
  * [Reviewing Import Results](#reviewing-import-results)
* [Troubleshooting](#troubleshooting)

***

## Overview

The Glossary is a portal-wide reference that any user can access without logging in. Terms are organized alphabetically into letter groups. Each entry has a term, a definition (which may include rich formatted text), and a group label that controls where it appears in the alphabetical index.

Key capabilities:

* Browse all terms organized by letter group, with smooth scroll-to-letter navigation
* Search across both terms and definitions with live autocomplete suggestions
* Export the full glossary (or a filtered subset) to a spreadsheet
* Administrators can create, edit, and delete individual terms
* Bulk-import terms from a CSV file, either adding to the existing glossary or replacing it entirely

***

## Browsing the Glossary

The public-facing Glossary page is available to all users and does not require a login.

### Navigating by Letter

A row of letter buttons appears at the top of the glossary. Clicking any letter smoothly scrolls the page to that letter's section, which is headed by a large letter label followed by all terms beginning with that letter.

On mobile devices, the letter row is replaced by a horizontal carousel. Tap a letter in the carousel to jump to the corresponding section. A floating up-arrow button appears at the bottom-right of the screen so you can return to the top quickly.

Terms that begin with a number or symbol are grouped under the **#** heading.

### Searching for a Term

A search field at the top of the page accepts free-text input. After you type at least three characters, a dropdown appears showing matching terms and their definitions. Both the term and the definition text are searched — you do not need to know the exact word at the start of a term.

Selecting an item from the dropdown navigates directly to that entry in the glossary list. On desktop, the search field remains visible so you can keep refining. On mobile, the search field clears after navigation so the list is unobstructed.

### Exporting the Glossary

An **Export to CSV** button appears next to the search field. Clicking it downloads the current glossary as a spreadsheet file named `Glossaries.xlsx`. If you have entered a search term before clicking Export, only the matching entries are included in the download.

The export is available to all users, including unauthenticated visitors.

***

## Glossary Administration

Administrators manage glossary content through a dedicated administration table. This view requires the **Glossaries: Edit**, **Glossaries: Create**, or **Glossaries: Delete** permission depending on the operation you need to perform.

### Opening the Administration View

Navigate to the Glossary Administration page through the Administration menu. The page is titled **Glossary Administration** and displays all terms in a paginated table.

### Finding Terms in the Table

A keyword filter appears above the table. Type part of a group name or term to narrow the list. The filter activates automatically after three characters. Click the refresh icon to reload all entries.

Columns in the table:

| Column       | Description                                              |
| ------------ | -------------------------------------------------------- |
| Term / Group | The term text and the letter group it belongs to         |
| Definition   | The full definition (truncated if very long)             |
| Modified     | Last-modified timestamp and the user who made the change |

The table supports column-based sorting. Click any column heading to sort ascending or descending. Pagination controls appear at the bottom when there are more than ten entries.

### Adding a New Term

Click **Add New Term** in the bottom-right action area of the table. A modal form opens with the following fields:

| Field      | Required | Notes                                                                          |
| ---------- | -------- | ------------------------------------------------------------------------------ |
| Term       | Yes      | 2 to 120 characters                                                            |
| Definition | Yes      | Rich-text editor; supports formatted content including bold, italic, and lists |

The **Group** field is not shown when creating a new term. The system automatically assigns the term to the group matching its first letter. Terms that begin with a non-letter character are placed in the **#** group. You can change the group later by editing the term.

Click **Save** to create the term. The table refreshes automatically.

### Editing a Term

Click the pencil (Edit) icon on any row to open the edit form. When editing an existing term, a read-only **Group** field appears at the top showing the current group assignment. You can update the term text and definition freely.

To reassign a term to a different letter group, you must change the term text itself so it begins with the desired letter — or contact a system administrator who can update the group field directly.

Click **Save** to apply your changes.

### Deleting a Term

Click the delete (trash) icon on any row to remove a term. A confirmation dialog appears asking you to confirm the deletion. Click **OK** to proceed. The action cannot be undone.

The delete icon is only visible for terms that have no child entries.

***

## Importing Terms from a CSV File

Administrators with the **Glossaries: Import** permission can load multiple terms at once from a CSV file. This is useful for initial population of the glossary or for applying a large batch of updates.

### Preparing the Import File

The import file must be a `.csv` file with a header row. Required columns:

| Column     | Description                                                                                                                                  |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| Term       | The glossary term text                                                                                                                       |
| Definition | The full definition for the term                                                                                                             |
| Group      | Optional. The letter group (e.g., `A`, `B`, `#`). If omitted or blank, the group is derived automatically from the first letter of the term. |

The file can be encoded as UTF-8, Windows-1252, or ASCII. The importer detects the encoding automatically.

### Choosing an Import Mode

When you open the Import dialog, a **Type of Import** toggle lets you choose how the file is handled:

| Mode                    | Behavior                                                                                                                      |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| Append Only             | Adds new terms and updates existing ones. Terms already in the glossary that are not in the file are left unchanged.          |
| Overwrite / Replace All | Deletes the entire existing glossary before importing. After the import, the glossary contains only the terms from your file. |

If a term from the file already exists in the glossary (matched by the term text), its definition and group are updated regardless of which mode is selected.

Use **Overwrite / Replace All** with caution — it permanently removes all existing entries before the new data is loaded.

### Running the Import

1. In the Glossary Administration table, click **Import CSV** in the filter bar.
2. The Import Glossary dialog opens.
3. Select the import mode (Append Only or Overwrite / Replace All).
4. Click **Upload your document** and choose your `.csv` file.
5. The **Upload** button becomes active once a file is selected. Click **Upload** to begin.

The import runs immediately. A success notification appears when the process completes.

### Reviewing Import Results

After the upload finishes, a results summary appears inside the dialog:

* The number of records successfully added or updated.
* A count of errors encountered.
* If any errors occurred, a table lists each error with its line number in the CSV file and a description of the problem.

Common causes of row-level errors include missing required column values or data that does not match expected formats. Correct the affected rows in your CSV file and re-import. Successfully processed rows are not rolled back when errors occur on other rows.

Click **Close** to dismiss the dialog. The glossary table refreshes to show the updated entries.

***

## Troubleshooting

**The Export to CSV button is grayed out.** The button is disabled briefly while the page is loading a secure download token. Wait a moment for the page to finish loading and the button will become active.

**My search is not returning results.** The search requires at least three characters before suggestions appear. Verify you have typed at least three characters. The search is not case-sensitive, but it requires the characters to appear consecutively somewhere in the term or definition text.

**A term I imported is in the wrong letter group.** If the CSV file included a blank or invalid Group column value, the system derived the group from the first character of the term. Edit the term in the administration table to correct the group, or fix the Group column in your CSV and re-import using Append Only mode.

**The import completed but some terms are missing.** Check the error table that appears after the import. Rows with missing Term or Definition values are skipped. Correct those rows in your CSV and re-run the import. Existing terms that were already imported will be updated (not duplicated).

**I see an "Invalid download token" error when trying to export.** Download tokens expire after 30 seconds from when the page loaded. Refresh the page and try the export again immediately after the page finishes loading.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://nimble.docs.otised.com/guides/glossary-management.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.