20. Registry, control panels, and vocabularies

In this part you will:

• Store custom settings in the registry

• Create a control panel to manage custom settings

• Create options in fields as vocabularies

• Training story: Assign talks to rooms

Topics covered:

• plone.app.registry

• Vocabularies

• Control panels

Check out mastering-plone-project at tag events:

git checkout events

The code at the end of the chapter:

git checkout vocabularies

More info in The code for the training

20.1. Introduction

Do you remember the fields audience and type_of_talk in the talk content type? The schema previously hard-coded several options for selection.

Next, you will add a field to assign talks to a room. The room names change each year for the conference, so site administrators need to edit them.

Additionally, admins should be able to edit the options for audience and type_of_talk, making it possible to add options like Lightning Talks!

By combining the registry, a control panel and vocabularies you can make rooms configurable options.

To achieve this you first need to get to know the registry.

20.2. The registry

The registry stores and retrieves values in records. Each record consists of the actual value, along with a field that describes the record in more detail. You can interact with the registry in Python using dictionary-style operations to get and set values.

Plone provides the registry through plone.registry and offers a user interface for interaction via plone.app.registry.

Most settings in Site Setup reside in the registry. You can modify them directly through its UI.

Open http://localhost:8080/Plone/portal_registry and filter for displayed_types. Modify the content types shown in the navigation and site map directly. These values match those in http://localhost:8080/Plone/@@navigation-controlpanel, where the form is customized for better usability.

Note

This UI for the registry is not yet available in the frontend.

20.3. Registry records

In Create a dynamic front page listing you already added a criterion usable for listing blocks in backend/src/ploneconf/site/profiles/default/registry/querystring.xml. This setting is stored in the registry.

Examine the existing values in the registry.

Go to http://localhost:3000/controlpanel/navigation and add talk to the field Displayed content types. Talks in the root will now show up in the navigation. This setting is stored in the registry record plone.displayed_types.

20.4. Access and modify records in the registry

In Python you can access the registry record with the key plone.displayed_types via plone.api.portal. It holds convenience functions to get and set a record:

from plone import api

api.portal.get_registry_record('plone.displayed_types')
api.portal.set_registry_record('plone.smtp_host', 'my.mail.server')

For more information see plone.api.portal documentation: Get plone.app.registry record.

Note

Code that cannot use plone.api, such as in Plone core, can access records via the IRegistry utility.

from plone.registry.interfaces import IRegistry
from zope.component import getUtility

registry = getUtility(IRegistry)
displayed_types = registry.get('plone.displayed_types')

The value of the record displayed_types is the tuple ('Image', 'File', 'Link', 'News Item', 'Folder', 'Document', 'Event', 'talk').

20.5. Custom registry records

Now add custom settings:

• Is talk submission open or closed?

• Which rooms are available for talks?

Additionally, new settings types_of_talk and audiences can be added for use later in the fields type_of_talk and audience.

To define custom records, you write the same type of schema as you already did for content types or for behaviors:

Add a file backend/src/ploneconf/site/controlpanels/controlpanel.py:

from plone import schema
from plone.autoform import directives
from zope.interface import Interface

import json


VOCABULARY_SCHEMA = json.dumps(
    {
        "type": "object",
        "properties": {
            "items": {
                "type": "array",
                "items": {
                    "type": "object",
                    "properties": {
                        "token": {"type": "string"},
                        "titles": {
                            "type": "object",
                            "properties": {
                                "lang": {"type": "string"},
                                "title": {"type": "string"},
                            },
                        },
                    },
                },
            }
        },
    }
)


class IPloneconfSettings(Interface):
    talk_submission_open = schema.Bool(
        title="Allow talk submission",
        description="Allow the submission of talks for anonymous user",
        default=False,
        required=False,
    )

    types_of_talk = schema.JSONField(
        title="Types of Talk",
        description="Available types of a talk",
        required=False,
        schema=VOCABULARY_SCHEMA,
        default={
            "items": [
                {
                    "token": "talk",
                    "titles": {
                        "en": "Talk",
                        "de": "Vortrag",
                    },
                },
                {
                    "token": "lightning-talk",
                    "titles": {
                        "en": "Lightning-Talk",
                        "de": "Lightning-Talk",
                    },
                },
            ]
        },
        missing_value={"items": []},
    )
    directives.widget(
        "types_of_talk",
        frontendOptions={
            "widget": "vocabularyterms",
        },
    )

    audiences = schema.JSONField(
        title="Audience",
        description="Available audiences of a talk",
        required=False,
        schema=VOCABULARY_SCHEMA,
        default={
            "items": [
                {
                    "token": "beginner",
                    "titles": {
                        "en": "Beginner",
                        "de": "Anfänger",
                    },
                },
                {
                    "token": "advanced",
                    "titles": {
                        "en": "Advanced",
                        "de": "Fortgeschrittene",
                    },
                },
                {
                    "token": "professional",
                    "titles": {
                        "en": "Professional",
                        "de": "Profi",
                    },
                },
            ]
        },
        missing_value={"items": []},
    )
    directives.widget(
        "audiences",
        frontendOptions={
            "widget": "vocabularyterms",
        },
    )

    rooms = schema.JSONField(
        title="Rooms",
        description="Available rooms of the conference",
        required=False,
        schema=VOCABULARY_SCHEMA,
        default={
            "items": [
                {
                    "token": "101",
                    "titles": {
                        "en": "101",
                        "de": "101",
                    },
                },
                {
                    "token": "201",
                    "titles": {
                        "en": "201",
                        "de": "201",
                    },
                },
                {
                    "token": "auditorium",
                    "titles": {
                        "en": "Auditorium",
                        "de": "Auditorium",
                    },
                },
            ]
        },
        missing_value={"items": []},
    )
    directives.widget(
        "rooms",
        frontendOptions={
            "widget": "vocabularyterms",
        },
    )

The motivation to use schema.JSONField instead of schema.List is described as follows.

The options for the types of a talk, the room and the audience may change. A modification of the feeding vocabulary would mean that already used options are no longer available, which would corrupt the data of the concerned talks. We can "future-proof" this vocabulary with JSONFields that store a vocabulary source in the registry. This vocabulary is a list of dictionaries, with keys that never change, and values that may be modified when necessary. See the default values to understand what is stored in the registry: Example types_of_talk:

[
    {
        "token": "talk",
        "titles": {
            "en": "Talk",
            "de": "Vortrag",
        },
    },
    {
        "token": "lightning-talk",
        "titles": {
            "en": "Lightning-Talk",
            "de": "Lightning-Talk",
        },
    },
]

If the name Lightning-Talk needs to be updated to Short talks, the talks categorized as lightning talks will still display correctly. This is because the value stored in the talks is the token lightning-talk, which remains unchanged.

A new field JSONField has been introduced. This field is used to store structured JSON data for the content. A schema defines the valid structure of the field values.

    directives.widget(
        "audiences",
        frontendOptions={
            "widget": "vocabularyterms",
        },
    )

The frontendOptions forces Volto to display on editing the field with a widget prepared for vocabulary terms. It tells Volto to look up the widget named vocabularyterms in Volto's widget mapping to find the corresponding widget.

The schema IPloneconfSettings is now registered for the registry. Add the following to backend/src/ploneconf/site/profiles/default/registry/main.xml. Each field in the IPloneconfSettings schema adds a corresponding record to the registry.

<?xml version="1.0" encoding="utf-8"?>
<registry xmlns:i18n="http://xml.zope.org/namespaces/i18n"
          i18n:domain="ploneconf.site"
>

  <records interface="ploneconf.site.controlpanels.controlpanel.IPloneconfSettings"
           prefix="ploneconf"
  />

</registry>

Note

The prefix allows you to access these records with a shortcut: You can use ploneconf.rooms instead of ploneconf.site.controlpanels.controlpanel.IPloneconfSettings.rooms.

After reinstalling the package to apply the registry changes, you can access and modify these registry records as described before. Either use http://localhost:8080/Plone/portal_registry or Python:

from plone import api

api.portal.get_registry_record('ploneconf.rooms')

Note

In the training project mastering-plone-project, we use Python to define the registry records. Alternatively you could add these registry entries with Generic Setup.

The following creates a new entry ploneconf.talk_submission_open with Generic Setup:

<record name="ploneconf.talk_submission_open">
  <field type="plone.registry.field.Bool">
    <title>Allow talk submission</title>
    <description>Allow the submission of talks for anonymous users</description>
    <required>False</required>
  </field>
  <value>False</value>
</record>

When creating a new vanilla Plone instance, a lot of default settings are created that way. See plone/Products.CMFPlone to see how Products.CMFPlone registers values.

20.6. Add a custom control panel

Now you'll add a custom control panel to edit all settings related to the package with a user-friendly interface.

To register a control panel for the frontend, add the following RegistryConfigletPanel to backend/src/ploneconf/site/controlpanels/controlpanel.py. The RegistryConfigletPanel uses the schema and will serve as a factory for a control panel configlet.

from plone.restapi.controlpanels import RegistryConfigletPanel
from zope.component import adapter

# …

class IPloneconfSettings(Interface):
    talk_submission_open = schema.Bool(
        title="Allow talk submission",
        description="Allow the submission of talks for anonymous user",
        default=False,
        required=False,
    )

# …

@adapter(Interface, Interface)
class PloneConfRegistryConfigletPanel(RegistryConfigletPanel):
    """Volto control panel"""

    schema = IPloneconfSettings
    schema_prefix = "ploneconf"
    configlet_id = "ploneconf-controlpanel"
    configlet_category_id = "Products"
    title = "Ploneconf Settings"
    group = "Products"

Tip

If you want to use this control panel in Blicca as well, see https://2022.training.plone.org/mastering-plone/registry.html#add-a-custom-control-panel, which also shows the Blicca version.

Update backend/src/ploneconf/site/controlpanels/configure.zcml to register PloneConfRegistryConfigletPanel as a named adapter:

  <adapter
      factory=".controlpanel.PloneConfRegistryConfigletPanel"
      name="ploneconf-controlpanel"
      />

Finally, in backend/src/ploneconf/site/profiles/default/controlpanel.xml, register the configlet with Generic Setup so that it gets listed in Site Setup.

<?xml version="1.0" encoding="utf-8"?>
<object name="portal_controlpanel">
  <configlet action_id="ploneconf-controlpanel"
             appId="ploneconf-controlpanel"
             category="Products"
             title="Ploneconf Settings"
             visible="True"
  >
    <permission>Manage portal</permission>
  </configlet>
</object>

After applying the profile (for example, by reinstalling the package), your control panel shows up on http://localhost:3000/controlpanel.

As you can see in the control panel for the ploneconf.site package, the entries can be modified and reordered. Changes are stored in the registry because the configlet is registered with the schema of the registry fields.

Note

Frontend widgets

A short remark on the frontend widget. We want the VocabularyTermsWidget to be applied. Thus we use the widget "directive" to specify the name of the frontend widget to be used for the three control panel fields in our backend schema. Thus no widget registration in the frontend app is needed.

directives.widget(
    "types_of_talk",
    frontendOptions={
        "widget": "vocabularyterms",
    },
)

This is also the way you would configure a content type schema, where you may want to override the default widget.

A widget component in your frontend package would be mapped to a key "mywidget". In your content type schema you would add a widget directive with frontendOptions={"widget": "mywidget"}.

20.7. Vocabularies

Now the custom settings are stored in the registry and can be modified conveniently by site administrators. These options still need to be used in talks.

To achieve this, turn them into vocabularies.

Vocabularies are often used for selection fields. They have many benefits:

• They enable you to separate the select option values from the content type schema. Users can edit vocabularies through the UI.

• Developers can set vocabularies dynamically. The available options may vary based on existing content, the user's role, or even the time of day.

Create a file backend/src/ploneconf/site/vocabularies/talk.py and write code that generates vocabularies from these settings:

from plone import api
from zope.interface import provider
from zope.schema.interfaces import IVocabularyFactory
from zope.schema.vocabulary import SimpleVocabulary


@provider(IVocabularyFactory)
def TalkTypesVocabulary(context):
    name = "ploneconf.types_of_talk"
    registry_record_value = api.portal.get_registry_record(name)
    items = registry_record_value.get("items", [])
    lang = api.portal.get_current_language()
    return SimpleVocabulary.fromItems(
        [[item["token"], item["token"], item["titles"][lang]] for item in items]
    )


@provider(IVocabularyFactory)
def AudiencesVocabulary(context):
    name = "ploneconf.audiences"
    registry_record_value = api.portal.get_registry_record(name)
    items = registry_record_value.get("items", [])
    lang = api.portal.get_current_language()
    return SimpleVocabulary.fromItems(
        [[item["token"], item["token"], item["titles"][lang]] for item in items]
    )


@provider(IVocabularyFactory)
def RoomsVocabularyFactory(context):
    name = "ploneconf.rooms"
    registry_record_value = api.portal.get_registry_record(name)
    items = registry_record_value.get("items", [])
    lang = api.portal.get_current_language()
    return SimpleVocabulary.fromItems(
        [[item["token"], item["token"], item["titles"][lang]] for item in items]
    )

The SimpleVocabulary.fromItems() is a method that takes the list of dictionaries of vocabulary terms

[
    {
        "token": "talk",
        "titles": {
            "en": "Talk",
            "de": "Vortrag",
        },
    },
    {
        "token": "lightning-talk",
        "titles": {
            "en": "Lightning-Talk",
            "de": "Lightning-Talk",
        },
    },
]

and creates a Zope vocabulary. This SimpleVocabulary instance has methods that Plone uses to display select widgets, display the rendered content type instance according the user language, etc..

You can now register these vocabularies as named utilities in backend/src/ploneconf/site/vocabularies/configure.zcml:

  <utility
      name="ploneconf.types_of_talk"
      component="ploneconf.site.vocabularies.talk.TalkTypesVocabulary"
      />
  <utility
      name="ploneconf.audiences"
      component="ploneconf.site.vocabularies.talk.AudiencesVocabulary"
      />
  <utility
      name="ploneconf.rooms"
      component="ploneconf.site.vocabularies.talk.RoomsVocabularyFactory"
      />

From now on you can use these vocabularies by referring to their name, for example, ploneconf.rooms.

Note

• Plone comes with many useful named vocabularies that you can use in your own projects, for example plone.app.vocabularies.Users or plone.app.vocabularies.PortalTypes.

• See plone/plone.app.vocabularies for a list of vocabularies.

• We turn the values from the registry into a dynamic SimpleVocabulary that can be used in the schema.

• You could use the context with which the vocabulary is called or the request (using getRequest from zope.globalrequest) to constrain the values in the vocabulary.

See also

Plone documentation: Vocabularies

20.8. Use vocabularies in a schema

To use a vocabulary in a schema field, replace the attribute values with vocabulary, and point to a vocabulary by its name:

type_of_talk = schema.Choice(
    title='Type of talk',
    vocabulary='ploneconf.types_of_talk',
    required=True,
)

Edit backend/src/ploneconf/site/content/talk.py. Don't forget to add the new field room.

from plone.app.textfield import RichText
from plone.autoform import directives
from plone.dexterity.content import Container
from plone.namedfile.field import NamedBlobImage
from plone.schema.email import Email
from plone.supermodel import model
from z3c.form.browser.checkbox import CheckBoxFieldWidget
from z3c.form.browser.radio import RadioFieldWidget
from zope import schema
from zope.interface import implementer


class ITalk(model.Schema):
    """Dexterity-Schema for Talks"""

    directives.widget(type_of_talk=RadioFieldWidget)
    type_of_talk = schema.Choice(
        title="Type of talk",
        vocabulary="ploneconf.types_of_talk",
        required=True,
    )

    details = RichText(
        title="Details",
        description="Description of the talk (max. 2000 characters)",
        max_length=2000,
        required=True,
    )

    directives.widget(audience=CheckBoxFieldWidget)
    audience = schema.Set(
        title="Audience",
        value_type=schema.Choice(
            vocabulary="ploneconf.audiences",
        ),
        required=False,
    )

    speaker = schema.TextLine(
        title="Speaker",
        description="Name (or names) of the speaker",
        required=False,
    )

    company = schema.TextLine(
        title="Company",
        required=False,
    )

    email = Email(
        title="Email",
        description="Email address of the speaker",
        required=False,
    )

    website = schema.TextLine(
        title="Website",
        required=False,
    )

    github = schema.TextLine(
        title="Github username",
        required=False,
    )

    image = NamedBlobImage(
        title="Image",
        description="Portrait of the speaker",
        required=False,
    )

    speaker_biography = RichText(
        title="Speaker Biography (max. 1000 characters)",
        max_length=1000,
        required=False,
    )

    room = schema.Choice(
        title="Room",
        vocabulary="ploneconf.rooms",
        required=False,
    )


@implementer(ITalk)
class Talk(Container):
    """Talk instance class"""

Now, after restarting, these fields on the talk content type should show the options that are configured in the control panel.

20.9. Adjust frontend according schema changes

Now that we have vocabulary terms with a title that can be different from the token, we adjust frontend/packages/volto-ploneconf-site/src/components/views/TalkView.jsx to show the title:

        {content.audience?.map((item) => {
          const audience = item.token;
          const color = colorMapping[audience] || 'green';
          return (
            <div className={`ui label ${color}`} key={audience}>
              {item.title}
            </div>
          );
        })}

One tiny thing is still missing: We should display the room. In the same file, add this after the When component:

        {content.room && (
          <>
            <div className="ui dividing sub header">Where</div>
            <p>{content.room.title}</p>
          </>
        )}

The complete TalkView

import { Container as SemanticContainer } from 'semantic-ui-react';
import config from '@plone/volto/registry';
import { When } from '@plone/volto/components/theme/View/EventDatesInfo';

const colorMapping = {
  beginner: 'green',
  advanced: 'yellow',
  professional: 'purple',
};

const TalkView = (props) => {
  const { content } = props;
  const Container =
    config.getComponent({ name: 'Container' }).component || SemanticContainer;
  const Image = config.getComponent({ name: 'Image' }).component;
  return (
    <Container id="view-wrapper talk-view">
      <h1 className="documentFirstHeading">
        <span className="type_of_talk">{content.type_of_talk.title}: </span>
        {content.title}
      </h1>
      {content.description && (
        <p className="documentDescription">{content.description}</p>
      )}
      <div className="ui right floated segment">
        {content.start && !content.hide_date && (
          <>
            <div className="ui dividing sub header">When</div>
            <When
              start={content.start}
              end={content.end}
              whole_day={content.whole_day}
              open_end={content.open_end}
            />
          </>
        )}
        {content.room && (
          <>
            <div className="ui dividing sub header">Where</div>
            <p>{content.room.title}</p>
          </>
        )}
        {content.audience && (
          <div className="ui dividing sub header">Audience</div>
        )}
        {content.audience?.map((item) => {
          const audience = item.token;
          const color = colorMapping[audience] || 'green';
          return (
            <div className={`ui label ${color}`} key={audience}>
              {item.title}
            </div>
          );
        })}
      </div>
      <div dangerouslySetInnerHTML={{ __html: content.details.data }} />
      <div className="ui clearing segment">
        {content.speaker && (
          <div className="ui dividing header">{content.speaker}</div>
        )}
        {content.website ? (
          <p>
            <a href={content.website}>{content.company || content.website}</a>
          </p>
        ) : (
          <p>{content.company}</p>
        )}
        {content.email && (
          <p>
            Email: <a href={`mailto:${content.email}`}>{content.email}</a>
          </p>
        )}
        {content.github && (
          <p>
            Github:{' '}
            <a href={`https://github.com/${content.github}`}>
              {content.github}
            </a>
          </p>
        )}
        <Image
          item={content}
          alt={content.speaker}
          className="ui small right floated image"
        />
        {content.speaker_biography && (
          <div
            dangerouslySetInnerHTML={{
              __html: content.speaker_biography.data,
            }}
          />
        )}
      </div>
    </Container>
  );
};
export default TalkView;

20.10. Summary

• You successfully combined the registry, a control panel, and vocabularies to enable site administrators to manage field options.

• It seems like a lot, but you will certainly use dynamic vocabularies, control panels, and the registry in many of your Plone projects in one way or another.