The following tables shows the most common field types for use in Dexterity schemata. See the documentation on creating schemata for information about how to use these.

Field properties

Fields are initialised with properties passed in their constructors. To avoid having to repeat the available properties for each field, we'll list them once here, grouped into the interfaces that describe them. You'll see those interfaces again in the tables below that describe the various field types. Refer to the table below to see what properties a particular interface implies.

Field types

The following tables describe the most commonly used field types, grouped by the module from which they can be imported.

Fields in zope.schema

Fields in plone.namedfile.field

See plone.namedfile and plone.formwidget.namedfile for more details.

Fields in z3c.relationfield.schema

See z3c.relationfield for more details

Fields in plone.app.textfield

See plone.app.textfield for more details

Most of the time, you will use the standard widgets provided by z3c.form. To learn more about z3c.form widgets, see the z3c.form documentation. To learn about setting custom widgets for Dexterity content types, see the schema introduction.

The table below shows some commonly used custom widgets.

Dexterity ships with several standard behaviors. The following table shows the interfaces you can list in the FTI behaviors properties and the resultant form fields and interfaces.

Dexterity uses the plone.autoform package to configure its z3c.form-based add and edit forms. This allows a schema to be annotated with "form hints", which are used to configure the form.

The easiest way to apply form hints in Python code is to use the directives from plone.directives.form and plone.directives.dexterity. These directives are used when the package is "grokked" (via the <grok:grok package="." /> ZCML directive) to apply the form hints to the interface where they are found. For this process to work, the schema must derive from plone.directives.form.Schema. Directives can be placed anywhere in the class body. By convention they are kept next to the fields they apply to.

For example, here is a schema that omits a field:

from plone.directives import form
from zope import schema

class ISampleSchema(form.Schema):
    
    title = schema.TextLine(title=u"Title")

    form.omitted('additionalInfo')
    additionalInfo = schema.Bytes()

The form directives take parameters in the form of a list of field names, or a set of field name/value pairs as keyword arguments. Each directive can be used zero or more times.

Form directives

The form directives in the plone.directives.form package are shown below.

The code sample below illustrates each of these directives:

from plone.directives import form
from zope import schema
from plone.app.z3cform.wysiwyg import WysiwygFieldWidget

class ISampleSchema(form.Schema):

    # A fieldset with id 'extra' and label 'Extra information' containing
    # the 'footer' and 'dummy' fields. The label can be omitted if the
    # fieldset has already been defined.
    
    form.fieldset('extra',
            label=u"Extra information",
            fields=['footer', 'dummy']
        )

    # Here a widget is specified as a dotted name.
    # The body field is also designated as the priamry field for this schema
    
    form.widget(body='plone.app.z3cform.wysiwyg.WysiwygFieldWidget')
    form.primary('body')
    body = schema.Text(
            title=u"Body text",
            required=False,
            default=u"Body text goes here"
        )

    # The widget can also be specified as an object
    
    form.widget(footer=WysiwygFieldWidget)
    footer = schema.Text(
            title=u"Footer text",
            required=False
        )
    
    # An omitted field. Use form.omitted('a', 'b', 'c') to omit several fields
        
    form.omitted('dummy')
    dummy = schema.Text(
            title=u"Dummy"
        )
    
    # A field in 'hidden' mode
    
    form.mode(secret='hidden')
    secret = schema.TextLine(
            title=u"Secret",
            default=u"Secret stuff"
        )
        
    # This field is moved before the 'description' field of the standard
    # IBasic behaviour, if this is in use.

    form.order_before(importantNote='IBasic.description')
    importantNote = schema.TextLine(
            title=u"Important note",
        )

Security directives

The security directives in the plone.directives.dexterity package are shown below. Note that these are also used to control reading and writing of fields on content instances.

The code sample below illustrates each of these directives:

from plone.directives import form, dexterity
from zope import schema

class ISampleSchema(form.Schema):

    # This field requires the 'cmf.ReviewPortalContent' to be read and
    # written
    
    dexterity.read_permission(reviewNotes='cmf.ReviewPortalContent')
    dexterity.write_permission(reviewNotes='cmf.ReviewPortalContent')
    reviewNotes = schema.Text(
            title=u"Review notes",
            required=False,
        )

Decorators from plone.directives.form allow you to set dynamic defaults and validators for schema fields. These are used outside the interface class, after its declaration.

Defaults

Use the plone.directives.form.default_value decorator to create an adaptor to dynamically set a default. For example, to set a Datetime field to default to the current time:

import datetime
from plone.directives import form
from zope import schema

class IMySchema(form.Schema):

    start = schema.Datetime(title=u"Start Date")

@form.default_value(field=IMySchema['start'])
def startDefaultValue(data):
    return datetime.datetime.today()

Validators

Use the plone.directives.form.validator decorator to create an adaptor to validate field input. For example, to validate that a field is not entered all uppercase:

from plone.directives import form
from zope import schema

class IMySchema(form.Schema):

    title = schema.TextLine(title=u"Title")

@form.validator(field=IMySchema['title'])
def validateTitle(value):
    if value and value == value.upper():
        raise schema.ValidationError(u"Please don't shout")

In this section, we will describe some of the more commonly used APIs that can be used to inspect and manipulate Dexterity content objects. In most cases, the content object is referred to as context, its parent folder is referred to as folder, and the type name is example.type. Relevant imports are shown with each code snippet, though of course you are more likely to place those at the top of the relevant code module.

Content object creation and folder manipulation

This section describes means to create objects and manipulate folders.

Creating a content object

The simplest way to create a content item is via its factory:

from zope.component import createObject
context = createObject('example.type')

At this point, the object is not acquisition wrapped. You can wrap it explicitly by calling:

wrapped = context.__of__(folder)

However, it's normally better to add the item to a folder and then re-get it from the folder.

Note that the factory is normally installed as a local utility, so the createObject() call will only work once you've traversed over the Plone site root.

There is a convenience method that can be used to create a Dexterity object. It is mostly useful in tests:

from plone.dexterity.utils import createContent
context = createContent('example.type', title=u"Foo")

Any keyword arguments are used to set properties on the new instance (via setattr() on the newly created object). This method relies on being able to look up the FTI as a local utility, so again you must be inside the site for it to work.

Adding an object to a container

Once an object has been created, it can be added to a container. If the container is a Dexterity container, or another container that supports a dict API (e.g. a Large Plone Folder in Plone 3 or a container based on plone.folder), you can do:

folder['some_id'] = context

You should normally make sure that the id property of the object is the same as the id used in the container.

If the object only supports the basic OFS API (as is the case with standard Plone Folders in Plone 3), you can use the _setObject() method:

folder._setObject('some_id') = context

Note that both of these approaches bypass any type checks, i.e. you can add items to containers that would not normally allow this type of content. Dexterity comes with a convenience function, useful in tests, to simulate the checks performed when content is added through the web:

from plone.dexterity.utils import addContentToContainer
addContentToContainer(folder, context)

This will also invoke a name chooser and set the object's id accordingly, so things like the title-to-id behavior should work. As before, this relies on local components, so you must have traversed into a Plone site (PloneTestCase takes care of this for you).

To bypass folder constraints, you can use this function and pass checkConstraints=False.

You can also both create and add an object in one call:

from plone.dexterity.utils import createContentInContainer
createContentInContainer(folder, 'example.type', title=u"Foo")

Again, you can pass checkConstraints=False to bypass folder constraints, and pass object properties as keyword arguments.

Finally, you can use the invokeFactory() API, which is similar, but more generic in that it can be used for any type of content, not just Dexterity content:

new_id = folder.invokeFactory('example.type', 'some_id')
context = folder['new_id']

This always respects add constraints, including add permissions and the current user's roles.

Getting items from a folder

Dexterity containers and other containers based on plone.folder support a dict-like API to obtain and manipulate items in folders. For example, to obtain an (acquisition-wrapped) object by name:

context = folder['some_id']

Folders can also be iterated over, and you can all items(), keys(), values() and so on, treating the folder as a dict with string keys and content objects as values.

Dexterity containers also support the more basic OFS API. You can call objectIds() to get keys, objectValues() to get a list of content objects, objectItems() to get an items()-like dict,and hasObject(id) to check if an object exists in a container.

Removing items from a folder

Again, Dexterity containers act like dictionaries, and so implement __delitem__:

del folder['some_id']

The OFS API uses the _delObject() function for the same purpose:

folder._delObject('some_id')

Object introspection

This section describes means of getting information about an object.

Obtaining an object's schema interface

A content object's schema is an interface, i.e. an object of type zope.interface.interface.InterfaceClass.

from zope.app.content import queryContentType
schema = queryContentType(context)

The schema can now be inspected. For example:

from zope.schema import getFieldsInOrder
fields = getFieldsInOrder(schema)

Finding an object's behaviors

To find all behaviors supported by an object, use the plone.behavior API:

from plone.behavior.interfaces import IBehaviorAssignable
assignable = IBehaviorAssignable(context)
for behavior in assignable.enumerateBehaviors():
    behavior_schema = behavior.interface
    adapted = behavior_schema(context)
    ...

The objects returned are instances providing plone.behavior.interfaces.IBehavior. To get the behavior schema, use the interface property of this object. You can inspect this and use it to adapt the context if required.

Getting the FTI

To obtain a Dexterity FTI, look it up as a local utility:

from zope.component import getUtility
from plone.dexterity.interfaces import IDexterityFTI
fti = getUtility(IDexterityFTI, name='example.type')

The returned object provides plone.dexterity.interfaces.IDexterityFTI. To get the schema interface for the type from the FTI, you can do:

schema = fti.lookupSchema()

Getting the object's parent folder

A Dexterity item in a Dexterity container should have the __parent__ property set, pointing to its containment parent:

folder = context.__parent__

Items in standard Plone folders won't have this property set, at least not in Plone 3.x.

The more general approach relies on acquisition:

from Acquisition import aq_inner, aq_parent
folder = aq_parent(aq_inner(context))

Workflow

This section describes ways to inspect an object's workflow state and invoke transitions.

Obtaining the workflow state of an object

To obtain an object's workflow state, ask the portal_workflow tool:

from Products.CMFCore.utils import getToolByName
portal_workflow = getToolByName(context, 'portal_workflow')
review_state = portal_workflow.getInfoFor(context, 'review_state')

This assumes that the workflow state variable is called review_state, as is the case for almost all workflows.

Invoking a workflow transition

To invoke a transition:

portal_workflow.doActionFor(context, 'some_transition')

The transition must be available in the current workflow state, for the current user. Otherwise, an error will be raised.

Cataloging and indexing

This section describes ways of indexing an object in the portal_catalog tool.

Reindexing the object

Objects may need to be reindexed if they are modified in code. The best way to reindex them is actually to send an event and let Dexterity's standard event handlers take care of this:

from zope.lifecycleevent import modified
modified(context)

In tests, it is sometimes necessary to reindex explicitly. This can be done with:

context.reindexObject()

You can also pass specific index names to reindex, if you don't want to reindex everything:

context.reindexObject(idxs=['Title', 'sortable_title'])

This method comes from the Products.CMFCore.CMFCatalogAware.CMFCatalogAware mix-in class.

Security

This section describes ways to check and modify permissions. For more information, see the section on permissions.

Checking a permission

To check a permission by its Zope 3 name:

from zope.security import checkPermission
checkPermission('zope2.View', context)

Note: In a test, you may get an AttributeError when calling this method. To resolve this, call newInteraction() from Products.Five.security in your test setup (e.g. the afterSetUp() method).

To use the Zope 2 permission title:

from AccessControl import getSecurityManager
getSecurityManager().checkPermission('View', context)

Sometimes, normally in tests, you want to know which roles have a particular permission. To do this, use:

roles = [r['name'] for r in context.rolesOfPermission('View') if r['selected']]

Again, note that this uses the Zope 2 permission title.

Changing permissions

Normally, permissions should be set with workflow, but in tests it is often useful to manipulate security directly:

context.manage_permission('View', roles=['Manager', 'Owner'], acquire=True)

Again note that this uses the Zope 2 permission title.

Content object properties and methods

The following table shows the more important properties and methods available on Dexterity content objects. In addition, any field described in the type's schema will be available as a property, and can be read and set using normal attribute access.