Fields
Contents
Fields#
This chapter describes the standard schema fields for Plone forms and content types.
The following tables show the most common field types for use in Forms and Dexterity Content Types. See schemas for information about how fields compose a schema for a form or content type data model.
Tip
In VS Code editor, you can install the Plone Snippets extension. This will give you snippets for most fields, widgets, and autoform directives in Python and XML based schemas.
Field properties#
You can initialize fields by passing properties into their constructors. To avoid repeating 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.
Interface |
Property |
Type |
Description |
---|---|---|---|
|
|
|
The title of the field. Used in the widget. |
|
|
A description for the field. Used in the widget. |
|
|
|
Whether or not the field is required. Used for form validation. The default is |
|
|
|
Whether or not the field is read only. Default is |
|
|
The default value for the field. Used in forms and sometimes as a fallback value. Must be a valid value for the field if set. The default is |
||
|
The default factory method for the field. Used in forms and sometimes as a fallback value. This is a name of a method which returns a dynamic default value. |
||
|
A value that represents "this field is not set." Used by form validation. Defaults to |
||
|
|
|
The minimum required length or minimum number of elements. Used for |
|
|
The maximum allowed length or maximum number of elements. Used for |
|
|
|
The minimum allowed value. Must be a valid value for the field, for example, an |
|
|
The maximum allowed value. Must be a valid value for the field, for example an |
||
|
|
Another |
|
|
|
Whether or not values in the collection must be unique. Usually not set directly. Use a |
|
|
|
Another |
|
|
Another |
||
|
|
|
An interface that must be provided by any object stored in this field. |
|
|
|
Default MIME type for the input text of a rich text field. Defaults to |
|
|
Default output MIME type for the transformed value of a rich text field. Defaults to |
|
|
|
A list of allowed input MIME types. The default is |
See IField
interface and field
implementation in zope.schema
documentation for details.
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
#
Name |
Type |
Description |
Properties |
---|---|---|---|
|
n/a |
Used to model selection from a vocabulary, which must be supplied. Often used as the |
See Vocabularies. |
|
|
Used for binary data. |
|
|
|
ASCII text (multi-line). |
|
|
|
A single line of binary data, in other words a |
|
|
|
A single line of ASCII text. |
|
|
|
Unicode text (multi-line). Often used with a WYSIWYG widget, although the default is a text area. |
|
|
|
A single line of Unicode text. |
|
|
|
|
|
|
|
An integer number. Both |
|
|
|
A floating point number. |
|
|
|
A tuple (non-mutable). |
|
|
|
A list. |
|
|
|
A set. |
|
|
|
A |
|
|
|
Stores a simple string, but implies a password widget. |
|
|
|
Stores a dictionary. Both |
|
|
|
Stores a Python |
|
|
|
Stores a Python |
|
|
|
Stores a Python |
|
|
|
A text field intended to store source text, such as HTML or Python code. |
|
|
n/a |
Stores a Python object that conforms to the interface given as the |
|
|
|
A URI (URL) string. |
|
|
|
A unique identifier, either a URI or a dotted name. |
|
|
|
A dotted name string. |
|
|
|
A Zope interface. |
|
|
|
Stores a Python |
|
Fields in plone.namedfile.field
#
See plone.namedfile
and plone.formwidget.namedfile for more details.
Name |
Type |
Description |
Properties |
---|---|---|---|
|
|
A binary uploaded file. Normally used with the widget from |
|
|
|
A binary uploaded image. Normally used with the widget from |
|
|
|
A binary uploaded file stored as a ZODB blob. Requires the |
|
|
|
A binary uploaded image stored as a ZODB blob. Requires the |
|
NamedBlobImage
#
The following example shows how to create an Image
object, and attach the image file to it.
img_obj = api.content.create(
container=ww_article,
type="Image",
id="test.jpg",
image=NamedBlobImage(
data=img_file,
filename="test.jpg",
)
)
Fields in z3c.relationfield.schema
#
See z3c.relationfield
for more details.
Name |
Type |
Description |
Properties |
---|---|---|---|
|
|
Stores a single |
|
|
|
A |
See List |
|
|
A |
See Choice |
Fields in plone.app.textfield
#
See plone.app.textfield
for more details.
Name |
Type |
Description |
Properties |
---|---|---|---|
|
|
Stores a |
|
The RichText
field allows for alternative markups and content filtering.
The following code sample shows how to create a schema with a RichText
field.
from plone.app.textfield import RichText
from plone.supermodel import model
class ITestSchema(model.Schema):
body = RichText(title="Body text")
The RichText
field constructor can take the following arguments, in addition to the usual arguments for a Text
field.
default_mime_type
A string representing the default MIME type of the input markup. This defaults to
text/html
.output_mime_type
A string representing the default output MIME type. This defaults to
text/x-html-safe
, which is a Plone-specific MIME type that disallows certain tags. Use the HTML Filtering control panel in Plone to control the tags.allowed_mime_types
A tuple of strings giving a vocabulary of allowed input MIME types. If this is
None
(the default), the allowable types will be restricted to those set in Plone's Markup control panel.
The default field can be set to either a Unicode object (in which case it will be assumed to be a string of the default MIME type) or a RichTextValue.
reStructuredText transformation#
Below is an example of a field that allows StructuredText and reStructuredText, transformed to HTML by default.
from plone.app.textfield import RichText
from plone.supermodel import model
defaultBody = """\
Background
==========
Please fill this in
Details
-------
And this
"""
class ITestSchema(model.Schema):
body = RichText(
title="Body text",
default_mime_type="text/x-rst",
output_mime_type="text/x-html",
allowed_mime_types=("text/x-rst", "text/structured",),
default=defaultBody,
)
RichTextValue
#
The RichText
field usually does not store a string.
Instead, it stores a RichTextValue
object.
This is an immutable object that has the following properties.
raw
A Unicode string with the original input markup.
mimeType
The MIME type of the original markup, for example,
text/html
ortext/structured
.encoding
The default character encoding used when transforming the input markup. Most likely, this will be UTF-8.
raw_encoded
The raw input encoded in the given encoding.
outputMimeType
The MIME type of the default output, taken from the field at the time of instantiation.
output
A Unicode object representing the transformed output. If possible, this is cached persistently, until the
RichTextValue
is replaced with a new one (as happens when an edit form is saved, for example).
The storage of the RichTextValue
object is optimized for the case where the transformed output will be read frequently (for example, on the view screen of the content object) and the raw value will be read infrequently (for example, on the edit screen).
Because the output value is cached indefinitely, you will need to replace the RichTextValue
object with a new one if any of the transformation parameters change.
However, as we will see below, it is possible to apply a different transformation on demand, if you need to.
The code snippet below shows how a RichTextValue
object can be constructed in code.
In this case, we have a raw input string of type text/plain
that will be transformed to a default output of text/html
.
Note that we would normally look up the default output type from the field instance.
from plone.app.textfield.value import RichTextValue
context.body = RichTextValue("Some input text", mimeType="text/html", outputMimeType="text/x-html-safe")
The standard widget used for a RichText
field will correctly store this type of object for you, so it is rarely necessary to create one yourself.
RichText
fields in templates#
If you use a DisplayForm
, the display widget for the RichText
field will render the transformed output markup automatically.
If you write TAL manually, you may try something like the following.
<div tal:content="structure context/body" />
This, however, will render a string as follows.
RichTextValue object. (Did you mean <attribute>.raw or <attribute>.output?)
The correct syntax is:
<div tal:content="structure context/body/output" />
This will render the cached, transformed output.
This operation is approximately as efficient as rendering a simple Text
field, since the transformation is only applied once, when the value is first saved.
Alternative transformations#
Sometimes, you may want to invoke alternative transformations.
Under the hood, the default implementation uses the portal_transforms
tool to calculate a transform chain from the raw value's input MIME type to the desired output MIME type.
If you need to write your own transforms, take a look at Changing Portal Transforms Settings via Python.
This is abstracted behind an ITransformer
adapter to allow alternative implementations.
To invoke a transformation in code, you can use the following syntax.
from plone.app.textfield.interfaces import ITransformer
transformer = ITransformer(context)
transformedValue = transformer(context.body, "text/plain")
The __call__()
method of the ITransformer
adapter takes a RichTextValue
object and an output MIME type as parameters.
If you write a page template, there is an even more convenient syntax.
<div tal:content="structure context/@@text-transform/body/text/plain" />
The first traversal name segment gives the name of the field on the context (body
in this case).
The second and third segments give the output MIME type.
If the MIME type is omitted, the default output MIME type will be used.
Note
Unlike the output
property, the value is not cached, and so will be calculated each time the page is rendered.
Fields in plone.schema
#
See plone.schema versus zope.schema for more details.
Name |
Type |
Description |
Properties |
---|---|---|---|
|
str |
A field containing an email address |
|
|
Schema#
With plone.autoform
and plone.supermodel
we can use directives to add information to the schema fields.
Protect a field with a permission#
By default, fields are included in the form regardless of the user's permissions.
Fields can be protected using the read_permission
and write_permission
directives.
The read permission is checked when the field is in display mode, and the write permission is checked when the field is in input mode.
The permission should be given with its Zope 3-style name, such as cmf.ManagePortal
instead of Manage portal
.
In this example, the secret
field is protected by the cmf.ManagePortal
permission as both a read and write permission.
This means that in both display and input modes, the field will only be included in the form for users who have that permission:
from plone.supermodel import model
from plone.autoform import directives as form
class IMySchema(model.Schema):
form.read_permission(secret="cmf.ManagePortal")
form.write_permission(secret="cmf.ManagePortal")
secret = schema.TextLine(
title = "Secret",
)
In supermodel XML, the directives are security:read-permission
and
security:write-permission
:
<field type="zope.schema.TextLine"
name="secret"
security:read-permission="cmf.ManagePortal"
security:write-permission="cmf.ManagePortal">
<title>Secret</title>
</field>