@rohberg/volto-slate-glossary

Volto add-on @rohberg/volto-slate-glossary adds tooltips for glossary terms of collective.glossary

Install Plone add-on collective.glossary in your backend. This provides the content type glossary.

Determine where to apply tooltips in your project by match configuration:

    import { Tooltips } from '@rohberg/volto-slate-glossary/components';

    export default function applyConfig(config) {
        config.settings.appExtras = [
            ...config.settings.appExtras,
            {
            match: '/documentation',
            component: Tooltips,
            },
            {
            match: '/news',
            component: Tooltips,
            },
        ];

        return config;
    }

By default we show a tooltip when a word matches case insensitively: when the term is "Hello" or "hello", a tooltip is shown for "Hello", "hello", "HELLO", "hElLo", etcetera.

You can configure this to be case sensitive for all terms, so "Hello" only matches for "Hello":

config.settings.glossary.caseSensitive = true;

Regardless of this setting, when you have a fully uppercase term, for example REST (Representational State Transfer), always only the exact word REST gets a tooltip, not rest or Rest.

By default we show tooltips for all occurrences of a term.

You can configure to only show tooltips for the first occurence on a page.

config.settings.glossary.matchOnlyFirstOccurence = true;

Hide alphabet navigation of glossary view:

config.settings.glossary.showAlphabetNavigation = false;

Show glossary term in tooltips header:

config.settings.glossary.mentionTermInTooltip = true;

Show tooltips also in text blocks of an accordion block:

config.settings.glossary.includeAccordionBlock = true;

Show tooltips also in a teaser block

Per default only texts of slate blocks are equipped with tooltips. TextWithGlossaryTooltips can be used to enhance other texts with tooltip markup.

Create a custom TeaserView component in your project:

import TeaserBody from '@plone/volto/components/manage/Blocks/Teaser/Body';
import { withBlockExtensions } from '@plone/volto/helpers/Extensions';
import { TextWithGlossaryTooltips } from '@rohberg/volto-slate-glossary/utils';

const TeaserView = (props) => {
  return (
    <TeaserBody
      {...{
        ...props,
        data: {
          ...props.data,
          description: TextWithGlossaryTooltips({
            text: props.data.description,
          }),
        },
      }}
    />
  );
};

export default withBlockExtensions(TeaserView);

Register your TeaserView component:

import TeaserViewWithTooltips from './components/TeaserViewWithTooltips'; // import by speaking name

const applyConfig = (config) => {
  // your project configuration…

  // teaser block with tooltips 
  config.blocks.blocksConfig.teaser.view = TeaserViewWithTooltips;
  // teaser block in grid block also with tooltips 
  config.blocks.blocksConfig.gridBlock.blocksConfig.teaser.view =
    TeaserViewWithTooltips;

  return config;
};

export default applyConfig;

You can find the code also via packages/policy/src/index.js.

Show tooltips also in a description block

Per default only texts of slate blocks are equipped with tooltips. TextWithGlossaryTooltips can be used to enhance other texts with tooltip markup.

Create a custom DescriptionBlockView in your project:

import { TextWithGlossaryTooltips } from '@rohberg/volto-slate-glossary/utils';

const DescriptionBlockView = ({ properties, metadata, id }) => {
  let description = (metadata || properties)['description'] || '';
  description = TextWithGlossaryTooltips({ text: description });

  return <p className="documentDescription">{description}</p>;
};

export default DescriptionBlockView;

Register your DescriptionBlockView component:

config.blocks.blocksConfig.description.view = DescriptionBlockViewWithTooltips; // import by speaking name

You can find the code also via packages/policy/src/index.js.

Register Custom tooltip component

The tooltip component can be replaced by a custom one.

  config.registerComponent({
    name: 'TooltipPopup',
    component: CustomTooltipPopup,
  });

Demo

To see the add-on in action, set up backend and frontend of this package.

backend:

make backend-install
make backend-create-site
make backend-start

frontend:

make install
make start

Opt-out for users

A user can opt-out by setting glossarytooltips to false. Add a boolean member field glossarytooltips to provide this.