Glossary System Add-on Guide for Larapen

An SEO-friendly glossary add-on for Larapen with A–Z navigation, categories, search, and structured data markup for definitions and technical terms.

Use Cases

Technical Documentation Site

You run a software product site and want to help users understand technical jargon.

• Create categories like “Programming”, “Networking”, “Security”.
• Add terms with short definitions and extended content with code examples.
• Use abbreviations (e.g., API, DNS, SSL) for quick reference.
• Structured data markup helps search engines display definitions in rich snippets.

Industry Knowledge Base

You maintain a professional website in finance, healthcare, or legal services and need a glossary of industry terms.

• Group terms by domain (e.g., “Accounting”, “Tax”, “Compliance”).
• Provide clear, translatable definitions in multiple languages.
• Use the paginated display mode for glossaries with hundreds of entries.

Educational Website

A school or training platform wants students to quickly look up concepts.

• Students browse by letter or search for terms.
• Related terms link to each other for deeper learning.
• View counts help identify the most-referenced terms.

Requirements

• Larapen CMS v1.0.0 or later
• PHP 8.3+
• MySQL 8.0+

Installation

Step 1: Upload the Add-on

In the admin panel, go to Admin → Extensions → Add-ons and click the Upload Add-on button. Select the add-on’s ZIP file: the system extracts it automatically and the add-on appears in the installed add-ons list.

Step 2: Activate the Add-on

Find Glossary System in the list and click Activate. Its migrations, seeders (if any) and permissions are set up automatically.

Step 3: Configure

Navigate to Admin → Glossary → Settings to configure the public URL slug, terms per page, and related-terms behavior. See Configuration.

Purchase Code (License Key)

Glossary System is sold as a separate product, so it has its own purchase code (license key), distinct from the purchase code of the main application and from the one of every other add-on. You are asked for it when you activate Glossary System in Admin panel → Add-ons.

Our products are sold on three platforms. The way you receive a purchase code depends on where you bought the product.

1. bedigit.com Store (in-site purchase)

• As soon as the order’s payment status becomes Paid, a license key is generated automatically for every licensed item in the order (one key per purchased unit: buying 3 units gives 3 distinct keys).
• It is emailed to the address used on the order, either in a dedicated license email or inside the order confirmation email. Check your inbox and your spam / junk folder.
• The key stays available in your account under My Account → My Licenses. Keys are masked in the list; open the license detail page to reveal and copy the full key, see the domains it is activated on, and deactivate a domain to free an activation slot.
• The matching invoice is under My Account → My Orders.

2. Gumroad

• A Gumroad purchase produces two separate emails: the Gumroad receipt (sent by Gumroad, giving access to the files) and a license key email (sent by bedigit.com) that contains your purchase code.
• The license key email is generated as soon as Gumroad notifies us of the sale, so it normally arrives within seconds of the payment. Here too, check your inbox and your spam / junk folder.
• When the Gumroad product uses Gumroad’s own license-key feature, the same key also appears in your Gumroad receipt and under Library → your purchase on gumroad.com.
• Use the same email address on bedigit.com as on Gumroad: your keys are then linked to your account automatically and listed under My Account → My Licenses, even if you register after the purchase. You can also add a Gumroad key manually from My Account → My Gumroad Licenses.

3. Envato Market (CodeCanyon)

• Envato purchase codes are issued and delivered by Envato Market, never emailed by us, so there is nothing to look for in your spam folder: you retrieve the code from your Envato account.
• Log in to your Envato / CodeCanyon account, open the Downloads page, find the item, and choose License certificate & purchase code from the Download dropdown. The code is written in that certificate.
• An Envato purchase code looks like 12345678-90ab-cdef-1234-567890abcdef (8-4-4-4-12 characters). It never changes, and renewing item support does not issue a new one.
• Official Envato article: Where Is My Purchase Code?

Configuration

Configuration defaults are defined in config/glossary.php and can be overridden from the admin panel at Admin → Glossary → Settings (stored in the settings table, group glossary).

Config File Defaults

Admin: Terms

The Terms page (Glossary → All Terms) is the primary management interface for glossary entries.

Terms List

A paginated table (20 per page by default) showing:

• Letter: the first letter of the term, displayed as a badge
• Term: the term name with a truncated definition preview below
• Category: assigned category badge (or dash if uncategorized)
• Abbreviation: shown as inline code (e.g., API, CSS)
• Status: colored badge (Draft/Published/Archived)
• Views: front-end view count

Per-term actions: Edit, Delete (with confirmation).

Filtering

The listing supports three filter controls:

• Search: text input that searches across term names, definitions, and abbreviations
• Status filter: dropdown to filter by Draft, Published, or Archived
• Category filter: dropdown to filter by glossary category

Creating & Editing Terms

The create/edit form is organized into sections:

Content (Translatable)

A language selector allows switching between active languages. For each language:

• Term: the term name (required for the default language)
• Slug: URL-friendly slug (auto-generated if left empty)
• Definition: short definition text (required for the default language)
• Extended Content: longer explanation, examples, or rich content

SEO & Meta (Translatable)

• Meta Title: up to 70 characters
• Meta Description: up to 160 characters

Publishing Sidebar

• Status: Draft, Published, or Archived
• Category: select from glossary categories (optional)
• Abbreviation: short form or acronym (e.g., API, CSS, ML): up to 50 characters

Admin: Categories

The Categories page (Glossary → Categories) manages glossary categories using the core unified category system.

Categories List

A paginated table showing categories with nesting indicators:

• Name: with indentation for nested categories
• Slug: shown as inline code
• Status: Active or Inactive badge

Per-category actions: Edit, Delete (with confirmation).

Creating & Editing Categories

Categories use the core StoreCategoryRequest / UpdateCategoryRequest form requests. All glossary categories are stored in the categories table with categorizable_type = 'glossary'.

Category fields include translatable name, slug, description, meta title, and meta description, plus an optional parent category for nesting.

Admin: Settings

The settings page (Glossary → Settings) configures front-end display behavior.

Display Mode

Two mutually exclusive display modes, selectable via styled radio cards:

• Grouped by Letter: all terms loaded at once, organized under A–Z headings. Best for small-to-medium glossaries (fewer than ~200 terms).
• Paginated List: terms loaded page by page with pagination controls. Recommended for large glossaries with many entries.

Items Per Page

Dropdown selector with options: 10, 15, 20, 30, 50, 100. Controls pagination in paginated mode, search results, letter filtering, and category filtering.

Settings are stored in the settings table (group: glossary) and override the defaults in config/glossary.php.

Front-end: Glossary Index

The glossary index page is the main entry point for visitors, available at /{locale}/glossary.

Layout

• A–Z navigation bar: an alphabetical letter strip at the top. Letters with published terms are clickable; letters without terms are grayed out. An “All” link shows all terms.
• Search bar: full-text search across term names, definitions, and abbreviations.
• Category filter: optional dropdown or sidebar to filter by category.

Grouped Mode

When glossary_display_mode = 'grouped', all published terms are loaded at once and displayed under alphabetical section headings (A, B, C…). Each term shows its name, a truncated definition, abbreviation (if any), and category badge.

Paginated Mode

When glossary_display_mode = 'paginated', terms are paginated according to the glossary_per_page setting. Standard Laravel pagination links appear at the bottom.

Search

When a search query is submitted, the system always returns paginated results regardless of the configured display mode. The search matches against term names, definitions, and abbreviations in the current locale.

Front-end: Letter Filtering

Clicking a letter in the A–Z navigation navigates to /{locale}/glossary/letter/{letter}.

This page shows all published terms starting with the selected letter, paginated according to the per-page setting. The A–Z navigation bar remains visible with the active letter highlighted.

Only single alphanumeric characters are accepted (validated by the route constraint [A-Za-z0-9]).

Front-end: Category Filtering

Category pages are available at /{locale}/glossary/category/{slug}.

The category slug is translatable: each language can have its own URL-friendly slug. The controller resolves the category by slug in the current locale and shows all terms in that category, paginated. Alternate URLs are shared for the language switcher.

Front-end: Term Detail Page

Each term has a dedicated page at /{locale}/glossary/{slug}.

Page Content

• Letter badge: large letter indicator
• Term title (h1)
• Abbreviation: shown if set (with hash icon)
• Category badge: clickable link to the category page
• Definition: the core definition text
• Extended content: longer explanation, examples, or rich content
• Related terms: up to 5 terms from the same category, linking for further exploration

Breadcrumbs

Full breadcrumb trail: Home → Glossary → Letter → Category (if assigned) → Term.

View Counter

Each time a term detail page is loaded, the view_count is incremented. This count is visible in the admin listing and can be displayed on the front-end.

Language Switcher

Alternate URLs are shared for the language switcher, using the term’s translatable slug in each language via share_alternate_urls().

SEO & Structured Data

Meta Tags

Each page generates appropriate meta tags via SeoService::getMetaTags():

• Index page: uses the configured glossary title and description
• Letter page: “Glossary: Letter {letter}”
• Category page: uses the category’s meta title/description (falls back to name)
• Term detail: uses the term’s meta title (falls back to “{term}: Definition & Meaning”) and meta description (falls back to truncated definition, 160 chars)

Structured Data

The term detail page supports Schema.org DefinedTerm structured data markup, which helps search engines understand and potentially display definitions as rich snippets in search results.

Updating

There are two ways to update this add-on: via the admin panel (recommended) or manually replacing files.

Method 1: Admin Panel Upload (Recommended)

1. Download the latest .zip file of this add-on.
2. Go to Admin panel → Add-ons and click the Upload button.
3. Select or drag the .zip file into the upload area.
4. A confirmation prompt will show the current and new version numbers. Click Replace to proceed.
5. Go to Admin panel → System Update (/admin/update) to apply any pending database migrations.

Method 2: Manual File Replacement

Step 1: Replace Files

Replace the add-on directory with the new version.

Step 2: Run Migrations

php artisan migrate

Pending migrations run once, so the command is safe to repeat.

Step 3: Rebuild Assets

Step 4: Clear Caches

php artisan config:clear
php artisan route:clear
php artisan view:clear

Step 5: Verify

Visit Admin → Glossary → All Terms and the front-end glossary page to confirm everything works correctly.

Uninstallation

Switching an add-on off without losing anything is a deactivation: go to Admin panel → Add-ons, find Glossary System and click Deactivate.

• Its routes, views, admin menu entries and permissions stop being registered, and its front-end pages stop answering.
• Its database tables and all the data they hold are kept, and its files stay under extensions/addons/glossary/. Nothing is deleted.
• The purchase code recorded at activation is kept too, so activating the add-on again does not ask for it.
• Deactivation is refused while another active add-on depends on this one: deactivate that add-on first.

Click Activate on the same card to switch it back on. Pending migrations are re-run, assets are republished, and the add-on picks up exactly where it left off.

Removing

Removing is permanent and destroys the add-on's data. The Remove button only appears on a deactivated add-on, so removal is always two steps:

1. Deactivate Glossary System (see Uninstallation).
2. Click Remove on its card and confirm the prompt.

The admin panel then, in one pass:

• runs the add-on's uninstall hook, if it ships one, while its code is still on disk;
• revokes the permissions declared in its addon.json;
• rolls back its migrations (this drops its database tables and every row they hold) and purges its entries from the migrations table, so a later reinstall migrates from scratch;
• deletes its published assets: public/addons/glossary/, public/vendor/glossary/ and storage/app/public/addons/glossary/;
• deletes the add-on directory extensions/addons/glossary/;
• deletes its row in the addons table (the recorded purchase code goes with it) and clears the application cache.

Removal is refused, with an explanatory message and before anything is destroyed, when the add-on is still active, when another active add-on depends on it, or when the web server (PHP) user cannot delete extensions/addons/glossary/. In that last case, give that user write permission on the directory and on its parent, then try again.

Deleting the folder over FTP or SSH is not equivalent: the add-on's tables, its entries in the migrations table and its addons row are all left behind, and its card stays in the list. Use Remove in the admin panel instead.

Troubleshooting

Glossary page shows “No terms found”

• Ensure at least one term has Published status and a published_at date in the past.
• Draft and Archived terms are not shown on the front-end.
• If using category filtering, verify the category has published terms assigned to it.

A–Z navigation shows no clickable letters

The letter navigation only highlights letters that have at least one published term. Add and publish terms to populate the navigation.

Term detail page returns 404

• The term must be published (status = published and published_at ≤ now()).
• Verify the slug matches the current locale. Each language has its own translatable slug.
• Check that the slug does not conflict with other routes (e.g., letter or category).

Categories not appearing in the filter

• Categories must have is_active = true in the categories table.
• Categories must have categorizable_type = 'glossary'.
• Ensure you are creating categories through Admin → Glossary → Categories, not through another add-on’s category manager.

Letter is not auto-derived correctly

The letter column is derived from the first character of the term name (using the English translation, or the first available locale). If the term starts with a non-ASCII character, the letter may not map to A–Z. Terms starting with numbers use the digit as their letter.

Vite manifest error: “Unable to locate file”

If you see this error for glossary SCSS files, rebuild the Vite manifest:

This is required after adding new SCSS or JS files to theme asset directories.

Settings not taking effect

• Clear the config cache: php artisan config:clear
• Settings saved in the admin panel (stored in the settings table) override the defaults in config/glossary.php.
• Verify the settings group is glossary in the database.

Search returns no results

Search matches against the current locale’s term name and definition, plus the abbreviation field (which is not translatable). Ensure the search query matches content in the active language.