Creating your own static and dynamic vocabularies
Vocabularies are normally used in conjunction with selection fields, and are supported by the zope.schema package, with widgets provided by z3c.form.
Selection fields use the
field type. To allow the user to select a single value, use
class IMySchema(model.Schema): myChoice = schema.Choice(...)
For a multi-select field, use a
class IMySchema(model.Schema): myList = schema.List(..., value_type=schema.Choice(...))
The choice field must be passed one of the following arguments:
valuescan be used to give a list of static values;
sourcecan be used to refer to an
vocabularycan be used to refer to an
IVocabularyinstance or (more commonly) a string giving the name of an
In the remainder of this section, we will show the various techniques for defining vocabularies through several iterations of a new field added to the Program type allowing the user to pick the organiser responsible for the program.
Our first attempt uses a static list of organisers. We use
the message factory to allow the labels (term titles) to
be translated. The values stored in the
field will be a unicode object representing the chosen
if no value is selected:
from zope.schema.vocabulary import SimpleVocabulary, SimpleTerm organizers = SimpleVocabulary( [SimpleTerm(value=u'Bill', title=_(u'Bill')), SimpleTerm(value=u'Bob', title=_(u'Bob')), SimpleTerm(value=u'Jim', title=_(u'Jim'))] ) organizer = schema.Choice( title=_(u"Organiser"), vocabulary=organizers, required=False, )
False, there will be a
no value option in the
The static vocabulary is obviously a bit limited, since it is hard-coded in Python.
We can make a one-off dynamic vocabulary using a context
source binder. This is simply a callable (usually a
function or an object with a
method) that provides the
interface and takes a
argument is the context of the form (i.e. the folder on an
add form, and the content object on an edit form). The
callable should return a vocabulary, which is most easily
achieved by using the
Here is an example using a function to return all users in a particular group:
from zope.schema.interfaces import IContextSourceBinder from zope.schema.vocabulary import SimpleVocabulary from Products.CMFCore.utils import getToolByName from zope.interface import directlyProvides def possibleOrganizers(context): acl_users = getToolByName(context, 'acl_users') group = acl_users.getGroupById('organizers') terms =  if group is not None: for member_id in group.getMemberIds(): user = acl_users.getUserById(member_id) if user is not None: member_name = user.getProperty('fullname') or member_id terms.append(SimpleVocabulary.createTerm(member_id, str(member_id), member_name)) return SimpleVocabulary(terms) directlyProvides(possibleOrganizers, IContextSourceBinder)
We use the PAS API to get the group and its members, building a list, which we then turn into a vocabulary.
When working with vocabularies, you’ll come across some terminology that is worth explaining:
- A term is an entry in the vocabulary. The term has a value. Most terms are tokenised terms which also have a token, and some terms are titled, meaning they have a title that is different to the token.
- The token must be an ASCII string. It is the value passed with the request when the form is submitted. A token must uniquely identify a term.
- The value is the actual value stored on the object. This is not passed to the browser or used in the form. The value is often a unicode object, but can be any type of object.
- The title is a unicode object or translatable message. It is used in the form.
class contains two class methods that can be used to
create vocabularies from lists:
takes a simple list of values and returns a tokenised
vocabulary where the values are the items in the list,
and the tokens are created by calling
str()on the values.
takes a list of
(token, value)tuples and creates a tokenised vocabulary with the token and value specified.
You can also instantiate a
yourself and pass a list of terms in the initialiser. The
class method can be used to create a term from a
title. Only the value is required.
In the example above, we have chosen to create a
from terms with the user id used as value and token, and
the user’s full name as a title.
To use this context source binder, we use the
argument to the
organizer = schema.Choice( title=_(u"Organiser"), source=possibleOrganizers, required=False, )
We can improve this example by moving the group name out
of the function, allowing it to be set on a per-field
basis. To do so, we turn our
into a class that is initialised with the group name:
from zope.interface import implements class GroupMembers(object): """Context source binder to provide a vocabulary of users in a given group. """ implements(IContextSourceBinder) def __init__(self, group_name): self.group_name = group_name def __call__(self, context): acl_users = getToolByName(context, 'acl_users') group = acl_users.getGroupById(self.group_name) terms =  if group is not None: for member_id in group.getMemberIds(): user = acl_users.getUserById(member_id) if user is not None: member_name = user.getProperty('fullname') or member_id terms.append(SimpleVocabulary.createTerm(member_id, str(member_id), member_name)) return SimpleVocabulary(terms)
Again, the source is set using the
argument to the
organizer = schema.Choice( title=_(u"Organiser"), source=GroupMembers('organizers'), required=False, )
When the schema is initialised on startup, a
object is instantiated, storing the desired group name.
Each time the vocabulary is needed, this object will be
called (i.e. the
method is invoked) with the context as an argument,
expected to return an appropriate vocabulary.
Context source binders are great for simple dynamic vocabularies. They are also re-usable, since you can import the source from a single location and use it in multiple instances.
Sometimes, however, we want to provide an additional level of decoupling, by using named vocabularies. These are similar to context source binders, but are components registered as named utilities, referenced in the schema by name only. This allows local overrides of the vocabulary via the Component Architecture, and makes it easier to distribute vocabularies in third party packages.
Named vocabularies cannot be parameterised in the way as
we did with the
context source binder, since they are looked up by name
We can turn our first "members in the
organizers group" vocabulary into a named
vocabulary by creating a named utility providing
IVocabularyFactory. Add to your
<utility name="example.conference.Organisers" provides="zope.schema.interfaces.IVocabularyFactory" component="example.conference.vocabularies.OrganizersVocabularyFactory" /> By convention, the vocabulary name is prefixed with the package name, to ensure uniqueness.
Then create a vocabulary factory in
... class OrganizersVocabularyFactory(object): def __call__(self, context): acl_users = getToolByName(context, 'acl_users') group = acl_users.getGroupById('organizers') terms =  if group is not None: for member_id in group.getMemberIds(): user = acl_users.getUserById(member_id) if user is not None: member_name = user.getProperty('fullname') or member_id terms.append(SimpleVocabulary.createTerm(member_id, str(member_id), member_name)) return SimpleVocabulary(terms)
We can make use of this vocabulary in any schema by
passing its name to the
argument of the
organizer = schema.Choice( title=_(u"Organiser"), vocabulary=u"example.conference.Organizers", required=False, )
Some common vocabularies¶
As you might expect, there are a number of standard vocabularies that come with Plone. These are found in the plone.app.vocabularies package. Some of the more useful ones include:
- a list of all available content languages;
- a list of currently supported content languages;
- the user roles available in the site;
a list of types installed in
- a list of those types that are likely to mean something to users;
- a list of workflows;
- a list of all states from all workflows;
- a list of all transitions from all workflows.
In addition, the package plone.principalsource provides several vocabularies that are useful for selecting users and groups in a Dexterity context:
- provides users
- provides groups
- provides security principals (users or groups)
Importantly, these sources are not iterable, which means that you cannot use them to provide a list of all users in the site. This is intentional: calculating this list can be extremely expensive if you have a large site with many users, especially if you are connecting to LDAP or Active Directory. Instead, you should use a search-based source such as one of these.
We will use one of these together with an auto-complete
widget to finalise our
field. To do so, we need to add
as a dependency of
setup.py, we add:
install_requires=[ ... 'plone.principalsource', ],
Since we use an
configure.zcml, we do not need a separate
for this new dependency.
field now looks like:
organizer = schema.Choice( title=_(u"Organiser"), vocabulary=u"plone.principalsource.Users", required=False, )
The autocomplete selection widget¶
field now has a query-based source. The standard selection
widget (a drop-down list) is not capable of rendering such
a source. Instead, we need to use a more powerful widget.
For a basic widget, see
z3c.formwidget.query, but in a Plone context, you will more likely want to
plone.formwidget.autocomplete, which extends
to provide friendlier user interface.
The widget is provided with
plone.app.dexterity, so we do not need to configure it ourselves. We only
need to tell Dexterity to use this widget instead of the
default, using a form widget hint as shown earlier. At the
program.py, we add the following import:
from plone.formwidget.autocomplete import AutocompleteFieldWidget
If we were using a multi-valued field, such as a
value_type, we would use the
schema (which, recall, derives from
and is therefore processed for form hints at startup), we
then add the following:
from plone.autoform import directives directives.widget(organizer=AutocompleteFieldWidget) organizer = schema.Choice( title=_(u"Organiser"), vocabulary=u"plone.principalsource.Users", required=False, )