Metadata-Version: 2.5
Name: collective.glossary
Version: 3.1.0
Summary: Content types to define a glossary and its terms
Project-URL: Homepage, https://github.com/collective/collective.glossary
Project-URL: PyPI, https://pypi.org/project/collective.glossary
Project-URL: Source, https://github.com/collective/collective.glossary
Project-URL: Tracker, https://github.com/collective/collective.glossary/issues
Author-email: Plone Community <collective@plone.org>
License-Expression: GPL-2.0-only
License-File: LICENSE.GPL
License-File: LICENSE.md
Keywords: CMS,Plone,Python
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Web Environment
Classifier: Framework :: Plone
Classifier: Framework :: Plone :: 6.0
Classifier: Framework :: Plone :: 6.1
Classifier: Framework :: Plone :: Addon
Classifier: License :: OSI Approved :: GNU General Public License v2 (GPLv2)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Requires-Dist: plone-api
Requires-Dist: plone-restapi
Requires-Dist: plone-volto
Requires-Dist: products-cmfplone
Provides-Extra: dev
Requires-Dist: zest-releaser[recommended]>=9.1.3; extra == 'dev'
Requires-Dist: zestreleaser-towncrier>=1.3.0; extra == 'dev'
Provides-Extra: test
Requires-Dist: horse-with-no-namespace; extra == 'test'
Requires-Dist: plone-app-testing; extra == 'test'
Requires-Dist: plone-restapi[test]; extra == 'test'
Requires-Dist: pytest; extra == 'test'
Requires-Dist: pytest-cov; extra == 'test'
Requires-Dist: pytest-plone>=0.5.0; extra == 'test'
Description-Content-Type: text/markdown

# collective.glossary

[![PyPI version](https://badge.fury.io/py/collective.glossary.svg)](https://badge.fury.io/py/collective.glossary)
[![Python versions](https://img.shields.io/pypi/pyversions/collective.glossary.svg)](https://pypi.org/project/collective.glossary/)
[![Plone versions](https://img.shields.io/badge/Plone-5.2%20|%206.0%20|%206.1-blue.svg)](https://plone.org)
[![CI](https://github.com/collective/collective.glossary/actions/workflows/ci.yml/badge.svg)](https://github.com/collective/collective.glossary/actions/workflows/ci.yml)
[![License](https://img.shields.io/pypi/l/collective.glossary.svg)](https://pypi.org/project/collective.glossary/)

Plone backend add-on to define a glossary and provide tooltips on matching text.

## Features

- The terms are defined as title / definition pairs.
- The term can have variants.
- The definiton is richtext formated.
- The tooltip can be disabled in glossary control panel.
- Tooltips can be restricted to a selection of content types.
- REST API service @glossary_terms to fetch the terms of a glossary.

[@rohberg/volto-slate-glossary](https://github.com/rohberg/volto-slate-glossary) is the corresponding Volto add-on.

## Caching

Volto fetches `@tooltip_terms` on every page view, while the terms rarely change.
Both REST API services, `@tooltip_terms` and `@glossary_terms`, therefore use the caching ruleset *Glossary terms* (`collective.glossary.terms`) of [plone.app.caching](https://github.com/plone/plone.app.caching).

When plone.app.caching is installed, installing or upgrading collective.glossary maps this ruleset to *Terse caching*, with these settings:

| Setting | Value | Header |
| --- | --- | --- |
| Maximum age | 10 seconds | `max-age=10` |
| Shared maximum age | 300 seconds | `s-maxage=300` |

A caching proxy such as Varnish then keeps the terms for 5 minutes, and a changed term reaches visitors within 5 minutes.
Change the settings in *Site Setup* > *Caching*, on the *Caching operations* tab, for the *Glossary terms* ruleset.

Installed plone.app.caching after collective.glossary?
Apply the `collective.glossary:caching` profile in the ZMI, under `portal_setup` > *Import*, or map the *Glossary terms* ruleset yourself in the caching control panel.
Without a mapping, the services send no `Cache-Control` header, and caching proxies do not cache them.

## Screenshots

![Create a Glossary](https://raw.github.com/collective/collective.glossary/master/docs/docs/_static/glossary.png)

*Create a Glossary.*

![Use it!](https://raw.github.com/collective/collective.glossary/master/docs/docs/_static/usage.png)

*Use it!*

![Control Panel](https://raw.github.com/collective/collective.glossary/master/docs/docs/_static/controlpanel.png)

*Configure glossary settings in the control panel.*

## Contribute

- [Issue tracker](https://github.com/collective/collective.glossary/issues)
- [Source code](https://github.com/collective/collective.glossary/)
- [PyPI](https://pypi.org/project/collective.glossary/)

### Prerequisites ✅

-   An [operating system](https://6.docs.plone.org/install/create-project-cookieplone.html#prerequisites-for-installation) that runs all the requirements mentioned.
-   [uv](https://6.docs.plone.org/install/create-project-cookieplone.html#uv)
-   [Make](https://6.docs.plone.org/install/create-project-cookieplone.html#make)
-   [Git](https://6.docs.plone.org/install/create-project-cookieplone.html#git)
-   [Docker](https://docs.docker.com/get-started/get-docker/) (optional)

### Installation 🔧

1.  Clone this repository, then change your working directory.

    ```shell
    git clone git@github.com:collective/collective.glossary.git
    cd collective.glossary
    ```

2.  Install this code base.

    ```shell
    make install
    ```


## License

The project is licensed under GPLv2.

## Acknowledgements

Generated using [Cookieplone (0.9.7)](https://github.com/plone/cookieplone) and [cookieplone-templates (c7497ac)](https://github.com/plone/cookieplone-templates/commit/c7497ace6a6d52fd75e67047f652a801b03c12c4) on 2025-06-25 15:56:13.999992.
