Document Actions

Fields

1. Overview

This is an overview of Archetypes' Fields.

Archetypes Fields - A Simple Explanation

Archetypes provides a robust framework for storing data attributes on content objects. This framework consist of a number of Fields stored in a container called a Schema. Fields are simply specialized Python classes that allow you to store and retrieve data associated with an Archetypes object.

Fields provide a few functionalities. First, there are specialized field types for strings, lists of strings, integers, floating-point numbers, etc., that allow special handling of fields based on the type of data stored.

Some Definitions

Before we go diving in, let's define some often-used terms:

Field: an Archetypes Field. This refers to an instance of a Field class defined in a Schema.
Schema: the "container" that Archetypes uses to store fields.
Schemata: a named grouping of fields. One Schema can have many schematas.
AT: abbreviation for Archetypes.

Some Pre-Requisites

The following pages assume that you have a solid working knowledge of Python.

Fields, Classes, and Objects

In Archetypes, Fields are Python objects contained within a Schema. A Field is defined once for an Archetypes class. This single Field instance is used for every instance of that class. Therefore, the relationship between Field instances and classes is described as such: "A field instance belongs to exactly one class."[1] A class, however, can have many different Field instances. Furthermore, every instance of an AT class uses the same set of Fields. AT objects themselves do not contain unique Fields.

[1]In some strange cases, this may be untrue, where the Schema from a base class is used directly in a new class without copying. In general, this is unwise and should be avoided.

2. Fields Reference

Attributes of standard Archetypes fields.

Topics
Common Field Attributes BooleanField ComputedField CMFObjectField DateTimeField	FileField FixedPointField FloatField ImageField IntegerField	LinesField ReferenceField StringField TextField

Common Field Attributes

These attributes are common to nearly all fields. Field-specific attributes follow, and are listed by field. Particular fields have different defaults, types, and some other specialized attributes.

Name	Description	Possible Values	Default
accessor	The name of a class method that will return the value of the field. Use this to change how the field is retrieved. If you don't provide a custom method name here, a default accessor, named getYourFieldName, is going to be created that just returns the value of the Field.	A class method name; for example, specialGetMethod	None
default	The default value for the field.	Type should be appropriate to the field.	None
default_method	The name of a class method returning a value for the field.	A class method name; for example, getSpecialDescription.	None
edit_accessor	The name of a class method that returns the raw value of a field.	Any method name (for example, rawGetMethod).	None
enforceVocabulary	Determines whether or not values outside the vocabulary will be accepted. If True, Archetypes will validate input for the field against the vocabulary. Only values already in the vocabulary will be accepted.	True or False.	False
index (Plone < 3 only)	If you want this field to be placed in its own catalog index, then specify the type of index here as a string. If you append :schema onto the end of the schema, then this will also be added as a metadata column. (The actual index will be on the field accessor, typically "getFieldName".) Ignored in Plone 3+; use GenericSetup profile for similar functionality.	The name of any index, such as KeywordIndex or KeywordIndex:schema.	None
index_method	May be used to specify the method called when indexing a field. Use '_at_accessor' to use the default accessor, '_at_edit_accessor' to use the edit accessor, or the name of a method returning the value to be indexed.	_at_accessor, _at_edit_accessor, getIndexAccessor and getIndexAccessorName	_at_accessor
languageIndependent	Flag for Fields that are independent of the language, such as dates. True tells LinguaPlone that no translation is necessary for this field.	True or False	False
isMetadata	Marks metadata fields. This is currently only needed as a convenience for the filterFields method of Schema. Fields marked as metadata are not displayed in the uncustomized base view.	True or False	False
mode	The read/write mode of field, as a string; the default is to be read and write. Accessors will not be created without the read mode, and Mutators will not be created without the write mode.	For read only: r, for write only: w, for read and write: rw.	rw
multiValued	Set this to True if the field can have multiple values. This is the case for fields like multiple-selection lists that allow the selection of multiple values.	True or False.	False
mutator	The string name of a class method that changes the value of the Field. If you don't provide a special method name here, a default mutator is generated with the name 'setYourFieldName' to simply store the value.	A class method name; for example, specialSetMethod.	None
name	A unique name for this field. Usually specified as the first item in the field definition.	Any string. Strongly recommended: lowercase, no punctuation or spaces, conforming to standard Python identifier rules. For example, description, user_name, or coffee_bag_6.	No default.
primary	If True, this will be the field that used for File Transfer Protocol (FTP) and WebDAV requests. There can be only field that does this; if multiple are defined, the first one in the schema will be used. You normally set this for the main body attribute. Only used for TextField and FileField field types.	True or False	False
read_permission	The permission required for the current user to allowed to view or access the field. Only useful if the read mode is activated. This read permission is checked when rendering the widget in read mode.	A permission identifier imported from Products.CMFCore.permissions	View
required	Specifies that some value for this field required.	True or False.	False
schemata	Use named schematas to organize fields into grouped views.	A short string that labels the group.	default
searchable	Specifies whether or not the field value will be indexed as part of the SearchableText for the content object. SearchableText is what is checked by the portal's main search.	True or False.	False
storage	The storage mechanism for the field. The default is Attribute Storage, which stores the field as an attribute of the object.	Any valid storage object such as AttributeStorage or SQLStorage. You can find these in the Archetypes Application Programming Interface (API).	AttributeStorage
type	Provided by the field class.. Should never be changed in a Schema.	None	None
validators	A list or tuple of strings naming validators that will check field input. If you only have one validator, you may specify it as a string. Validators may also be instances of a class implementing the IValidator interface from from Products.validation.interfaces.IValidator. Providing a class instance allows you more flexibility as you may set additional parameters. Validators are checked in order specified.	The names of validators registered via Products.validation; for example, isEmail.	()
vocabulary	Provides the values shown in selection and multi-selection inputs. This may be specified as a static list or as the name of a class method returning the choice list.	A list of strings (in which case keys and values will be the same); a list of 2-tuples of strings [("key1","value 1"),("key 2","value 2"),...]; a Products.Archetypes.utils.DisplayList. Or, the name of a class method returning any of the above.	()
vocabulary_factory	Like the vocabulary attribute, in Plone 3 provides the values shown in selection and multi-selection inputs.	A string name of a Zope 3 style vocabulary factory (a named utility providing zope.schema.interfaces.IVocabularyFactory)	None
widget	The widget that will be used to render the field for viewing and editing. See the widget reference for a list of available widgets.	An instance of a widget; for example, StringWidget().	StringWidget()
write_permission	The permission required for the current user to edit the field value. Only interesting if the write mode is activated. The write permission is checked when rendering the widget in write mode.	A permission identifier imported from Products.CMFCore.permissions	ModifyPortalContent

Standard Fields

BooleanField

Simple storage of True or False for a field.

Standard properties

Name	Type	Default	Description	example values
widget	widget	BooleanWidget	Implemented as a check box.	LabelWidget BooleanWidget
default	boolean	False
type		boolean

Note: The required attribute for the boolean field is often confusing. It does not require that the box be checked. Use a validator if you need to require the box be checked.

ComputedField

Read-only field, whose content cannot be edited directly by users, but is computed instead from a Python expression. For example, it can be the result of an operation on the contents from some other fields in the same schema, e.g. calculating the sum of two or more currency amounts, or composing a full name from first name and surname.
This field is usually not stored in the database, because its content is calculated on the fly when the object is viewed.

Standard properties

Name	Type	Default	some possible values
widget	widget	ComputedWidget	LabelWidget ComputedWidget
storage	storage	ReadOnlyStorage
type		computed
mode	string	r

Special properties

Name	Type	Default	Description	some possible values
expression			Evaluated on the object to compute a value.

CMFObjectField

Used for storing values inside a CMF Object, which can have workflow. Can only be used for BaseFolder-based content objects.

Standard properties

Name	Type	Default	some possible values
widget	widget	FileWidget	LabelWidget FileWidget
storage	storage	ObjectManagedStorage
type		object

Special properties

Name	Type	Default	Description	some possible values
portal_type		File
workflowable		True
default_mime_type		application/octet-stream

DateTimeField

Used for storing dates and times.

Standard properties

Name	Type	Default	some possible values
widget	widget	CalendarWidget	LabelWidget CalendarWidget
default	DateTime
type		datetime

Note: The default for the DateTimeField needs to be specified as a DateTime object. If you need to set the current date/time as the default, you'll need to use the default_method attribute to specify a class method returning the current date/time as a DateTime object.

FileField

Storage for large chunks of data such as plain-text files, office-automation documents, and so on.

Standard properties

Name	Type	Default	some possible values
widget	widget	FileWidget	FileWidget LabelWidget
default	string
type		file

Special properties

Name	Type	Default	Description
primary		False
default_content_type		application/octet
primary	boolean	False	Set this True to mark the field as primary for FTP or WebDAV.

Note: File field values are stored as strings. It's a common practice to use streams to read/write the values as if they were files.

FixedPointField

For storing numerical data with fixed points.

Standard properties

Name	Type	Default	some possible values
widget	widget	DecimalWidget	LabelWidget DecimalWidget
validators	validators	isDecimal
default	string	0.00
type		fixedpoint

Special properties

Name	Type	Default	Description	some possible values
precision		2

FloatField

For storing numerical data with floating points.

Standard properties

Name	Type	Default	Description	some possible values
default	string	0.0
type		float

ImageField

Stores an image and allows dynamic resizing of the image.

Standard properties

Name	Type	Default	Description	some possible values
widget	widget	ImageWidget		ImageWidget LabelWidget
default	string
type		image
allowable_content_types	tuple of MIME strings	Specifies the types of images that will be allowed.	('image/gif','image/jpeg','image/png')	('image/jpeg','image/png')

Note: Image field values are stored as strings. It's a common practice to use streams to read/write the values as if they were files.

Special properties

Name	Type	Default	Description	some possible values
original_size	tuple (w,h)	None	The size to which the original image will be scaled. If it's None, then no scaling will take place; the original size will be retained. Caution: the aspect ratio of the image may be changed.	(640,480)
max_size	tuple (w,h)	None	If specified then the image is scaled to be no bigger than either of the given values of width or height. Aspect ratio is preserved. Useful to prevent storage of megabytes of unnecessary image data.	(1024,768)
sizes	dict	{'thumb':(80,80)}	A dictionary of scales in which the image will be available. Dictionary entries should be of the form 'scaleName':(width,height).	{ 'mini' : (80,80), 'normal' : (200,200), 'big' : (300,300), 'maxi' : (500,500)}
pil_quality	integer	88	A JPEG quality setting (range 0 to 100). Lower numbers yield high compression and low image quality. High numbers yield low compression and better quality.	50 (a medium quality)

Using Image Scales

To display the original image (possibly rescaled if you used original_size or max_size attributes), you may use a URL like:
http://url_of_content_object/imageFieldName
as the SRC attribute of an IMG tag where url_of_content_object is the URL of the content object and imageFieldName is the name of the image field.

To display one of the scales, use a URL like:
http://url_of_content_object/imageFieldName_scale
where scale is one of the keys of the sizes dictionary.

Attention: The direct attribute access as shown above works only together with AttributeStorage, which will be used by default. To avoid heavy memory consumption on sites with many images it is recommended to use AnnotationStorage for the ImageField.

You may also generate a ready-to-insert IMG tag with the python code:

obj.getField('image').tag(obj, scale='mini')

if obj is your content object, image the name of your image field, and mini the name of your scale.

You may rescale to other sizes than those in the sizes field attribute with code like:

obj.getField('image').tag(obj, height=480, width=640, alt='alt text',
            css_class='css_class_selector', title='html title attribute')

IntegerField

For storing numerical data as integers.

Standard properties

Name	Type	Default	some possible values
widget	widget	IntegerWidget	LabelWidget IntegerWidget
default	integer	0
type		integer

Special properties

Name	Type	Default	Description	some possible values
size		10	Sets the size of the input field.

LinesField

Used for storing text as a list, for example a list of data such as keywords.

Standard properties

Name	Type	Default	some possible values
widget	widget	LinesWidget	KeywordWidget LinesWidget LabelWidget MultiSelectionWidget PicklistWidget InAndOutWidget
default	string	()
type		lines

ReferenceField

Used for storing references to other Archetypes Objects.

Standard properties

Name	Type	Default	Description	some possible values
widget	widget	ReferenceWidget		ReferenceWidget ReferenceBrowserWidget LabelWidget InAndOutWidget
index_method		_at_edit_accessor
type		reference
multiValued	boolean	False	Set multiValued True to allow multiple references (one-to-many), or False to allow only a single reference (one-to-one).

Special properties

Name	Type	Default	Description	some possible values
relationship			Specifes an identifier for the type of relationships associated with the field. This should be unique within your content type, but has no larger meaning. A ReferenceField allows you to edit the set of references with a particular relationship identifier from the current content object to other objects.	'KnowsAbout', 'Owns', 'WorksWith'
allowed_types	tuple of portal types	()	Determines all the portal types that will be searched to find objects that the user can make a reference to. It also specifies the Types that should be allowed to be added directly from the reference widget. This is only activated if the addable property is set. An empty list or tuple will allow references to all portal types.	('Document', 'File')
allowed_types_method	string	None	A string containing the name of a class method that will return a list of portal types to which references are allowed.
vocabulary_display_path_bound	integer	5	Sets a limit for presentation of reference items. Up to this limit, only titles are displayed. Above the limit, the path to the referenced object is also displayed. The idea is that if there are a large number of referenced items, the user will need help to differentiate them.
vocabulary_custom_label	string	None	A string containing a python expression that will be evaluated to get the displayed text for a referenced item. Your expression may use the variable "b" which will be a reference to the catalog brain returned by the reference lookup.	"b.getObject().title_or_id()"

StringField

A field for plain-text, unformatted strings.

Standard properties

Name	Type	Default	some possible values
default	string
type		string
widget	widget	StringWidget	LabelWidget StringWidget SelectionWidget

Special properties

Name	Type	Default	Description	some possible values
default_content_type	string MIME type	text/plain		Rarely changed.

TextField

A string field typically used for longer, multi-line strings. The string may also be transformed into alternative formats.

Standard properties

Name	Type	Default	some possible values
default	string
type		text
widget	widget	StringWidget	LabelWidget TextAreaWidget RichWidget

Special properties

Name	Type	Default	Description	some possible values
primary	boolean	False	Set this True to mark the field as primary for FTP or WebDAV.
default_content_type	string MIME type	text/plain	A string designating MIME the default input type for the field.	text/plain, text/html
allowable_content_types	tuple of MIME-type strings	('text/plain',)	Used in the TextArea and Rich widgets to let the user choose between different text formats in which the content is entered.	('text/plain', 'text/html',)
default_output_type	string MIME type	text/plain	This is used by the accessor (get) method to and decides which MIME-Type the content should be transformed into if no special MIME-Type is demanded.	'text/html', 'text/x-html-safe'

3. Widgets Reference

This page is a syntax reference and general guide for defining and using Widgets.

Widget Attribute Topics
Common Widget Attributes BooleanWidget CalendarWidget ComputedWidget DecimalWidget FileWidget ImageWidget	InAndOutWidget IntegerWidget KeywordWidget LabelWidget LinesWidget MultiSelectionWidget PasswordWidget	PicklistWidget ReferenceWidget ReferenceBrowserWidget RichWidget SelectionWidget StringWidget TextAreaWidget

Common Widget Attributes

The table below describes attributes common to nearly all widgets. Illustrations and special attributes listings for each of the standard widgets follows.

Name	Description	Possible Values
condition	A string containing a TALES expression to determine whether or not a field/widget is included on a view or edit page. This does not distinguish between view and edit mode.	Your TALES expression may referenc the current context as 'object' and the Plone site root as 'portal'
description	Help or explanatory text for the field. Usually shown on the edit form under the label and above the input field.
description_msgid	The i18n identifier for the description message. Used to translate the message. Should be unique within your product's i18n domain.	'help_type_field'
label	The label that will appear in the field.	Any string, for example, Start Date for a field start_date. Also label_msgid (takes string message ids for i18n.)
label_msgid	The i18n identifier for the label message. Should be unique within your product's i18n domain.	'label_type_field'
i18n_domain	The i18n domain specifier for your product. This should be unique for your product, and will be used to find the translation catalogs for your product.	'productname'
modes	The modes that this widget will be shown in; by default there are two modes: view and edit.	A list of modes as strings; by default ("view", "edit").
populate	If this is enabled, the view and edit fields will be populated. Usually this is enabled, but for fields such as a password field, this shouldn't be the case. Usually this is true by default.	True or False
postback	If this is enabled, then when an error is raised, the field is repopulated; for fields such as a password field, this shouldn't be the case. Usually this is True by default.	True or False
visible	Determines whether or not the field is visible view and edit mode. This is a dictionary mapping the view mode to a string describing the visibility. Choices are visible, hidden (rendered in an HTML hidden form value), invisible (not rendered at all).	For example, {'view': 'visible', 'edit': 'hidden' } means that the view will show, but the edit page will hide the value.

Standard Widgets

BooleanWidget

Renders an HTML checkbox, from which users can choose between two values such as on/off, true/false, yes/no.

CalendarWidget

Renders a HTML input box with a helper popup box for choosing dates.

Special Properties

Name	Type	Default	Description
format	string		Defines the date/time format using strftime, e.g. '%d.%m.%Y', for the view. (See the strftime section of the Python time documentation. If this is not specified, the long form of the portal's local time format is used.
future_years	integer	5	Specifies the number of future years offered by the year drop-down portion of the date widget. Do not use both future_year and end_year. (Plone 2.5+)
starting_year	integer	1999	The first year offered by the year drop-down. (Plone 2.5+)
ending_year	integer	None	The final year offered by the year drop-down. Do not use both future_years and end_year. (Plone 2.5+)
show_hm	boolean	True	Should the widget ask for a time as well as a date? (Plone 2.5+)

ComputedWidget

Generally used for ComputedField field type, it renders the computed value. Note that if your field has a vocabulary, and the field value is a key in that vocabulary, the widget will lookup the key in the vocabulary and show the result.

Standard Properties

Name	Type	Default	Description
modes	tuple	('view', 'edit')	As ComputedField is a read-only field, this property can be used to prevent the widget from appearing in edit templates, by setting it to just ('view',).

DecimalWidget

In edit mode, renders an HTML text input box which accepts a fixed point value.

Special Properties

Name	Type	Default	Description
thousands_commas	boolean	False	In view mode, formats the value to shows commas for thousands. For example, when thousands_commas is True, "7632654849635.02" is displayed as "7,632,654,849,635.02". (Note: this feature is not localized; it uses commas independent of locale.
whole_dollars	boolean	False	Shows whole dollars in view, leaving out the cents. Enter "1.123", and "$1" is shown. (Note: this feature is not localized; it uses the dollar sign independent of locale.)
maxlength		255	Maximum input size; sets the HTML input tag's maxlength attribute.
dollars_and_cents	boolean	False	In view mode, shows dollars and cents. Enter "123.123" and "$123.12" is shown. (Note: this feature is not localized; it always uses the dollar sign, period, and two digits precision.)
size		5	Size of the input field; sets the HTML input tag's size attribute.

FileWidget

Renders an HTML widget so a user can upload a file.

ImageWidget

Renders an HTML widget that can be used to upload, display, delete, and replace images. You can provide a display_threshold that allows you to set the size of an image; if it's below this size, the image will display in the Web page.

Special Properties

Name	Type	Default	Description
display_threshold	integer	102400	Only display the image inline if img.getSize() <= display_threshold

InAndOutWidget

In edit mode, renders a widget for moving items from one list to another. Items are removed from the source list. This can be used to choose multiple values from a list. This provides a good alternative to the MultiSelectionWidget when the vocabulary is too long for checkboxes.

Special Properties

IntegerWidget

A simple HTML input box for a string.

Special Properties

Name	Type	Default	Description
size		6	Size of the select widget; sets the HTML select tag's size attribute.

Name	Type	Default	Description
maxlength		255	Maximum input size; sets the HTML input tag's maxlength attribute
size		5	Size of the input field; sets the HTML input tag's size attribute.

KeywordWidget

This widget allows the user to select keywords or categories from a list. It is used for the Categories field in the Categorization Schema (Plone 3+) or the equivalent Keywords field on the Properties Tab (Plone < 3) of a content object.
Keywords are drawn from the field vocabulary and/or the unique values for the field in a specified catalog.
Additional keywords may be added unless the enforceVocabulary property of the field is True.

Special Properties

Name	Type	Default	Description
vocab_source		portal_catalog	Sets the catalog to search for additional vocabulary to be combined with the vocabulary defined for the field. Additional keywords from existing content are found using catalog.uniqueValuesFor(fieldName).
roleBasedAdd		True	Only shows the "New keywords" input for adding keywords if the current user has one of the roles stored in the allowRolesToAddKeywords property in the site_properties property sheet in portal_properties

LabelWidget

Used to display labels on forms -- without values or form input elements.

LinesWidget

Displays a text area so that users can enter a list of values, one per line.

Special Properties

Name	Type	Default	Description
rows	integer	5	Rows of the lines widget; sets the HTML textarea tag's rows attribute.
cols	integer	40	Columns of the lines widget; sets the HTML textarea tag's cols attribute.

MultiSelectionWidget

A selection widget; by default it's an HTML select widget which can be used to choose multiple values. As a checkbox users can choose one or more values from a list (useful if the list is short).

Special Properties

Name	Type	Default	Description
format	string	select	Possible values: 'select' or 'checkbox'. Uses a either a series of checkboxes or a multi-selection list. Note that checkboxes have much better usability for short vocabularies. Consider using the InAndOutWidget for longer vocabularies.
size		5	Defines the size of the multi-select list. Does not apply for checkboxes.

PasswordWidget

Renders an HTML password input.

Special Properties

Name	Type	Default	Description
maxlength		255	Maximum input size; sets the HTML input tag's maxlength attribute.
size		20	Size of the input field; sets the HTML input tag's size attribute.

Standard Properties

Name	Type	Default
populate	boolean	False
postback	boolean	False
modes		('edit',)

PicklistWidget

Similar to the InAndOutWidget, but the values stay in the source list after selection.

Special Properties

Name	Type	Default	Description
size	integer	6	Size of the selection box; sets the HTML select tag's size attribute.

ReferenceWidget

Renders an HTML text input box which accepts a list of possible reference values. Used in combination with the Reference Field.
Note: In Plone 2.5 and above, the ReferenceBrowserWidget is a usually a better choice for a reference widget due to its ability to browse for content referenceable objects.

Special Properties

Name	Default	Description
checkbox_bound	5	When the number of items exceeds this value, multi-selection lists are used. Otherwise, radio buttons or checkboxes are used.
destination	None	May be: ".", context object; None, any place where Field.allowed_types can be added; string path; name of method on instance (it can be a combination list); a list, combining all item above; a dict, where {portal_type:} destination is relative to portal root
addable	False	Create createObject link for every addable type
destination_types	None	Either a single type given as a string, or a list of types given as a string, defining what types we allow adding to. Only applies when addable is set on the widget.

ReferenceBrowserWidget

A sophisticated widget for browsing, adding and deleting references.
Standard in Plone 2.5+, available for earlier versions as an add-on product.
Import from Products.ATReferenceBrowserWidget.ATReferenceBrowserWidget.

Special Properties

Name	Type	Default	Description
size	integer		Size of the field if not multiValued; sets the HTML input tag's size attribute.
default_search_index	string	SearchableText	when a user searches in the popup, this index is used by default
show_indexes	boolean	False	If True, a drop-down list is shown in the popup to select the index used for searching. If set to False, default_search_index will be used.
available_indexes	dict	{}	Optional dictionary containing all the indexes that can be used for searching along with their friendly names. Format: {'catalogindex':'Friendly Name of Index', ... } The friendly names are shown in the widget. Caution: If you set show_indexes True, but do not use this property to specify indexes, then all the indexes will be shown.
allow_search	boolean	True	If True, a search form is included in the popup.
allow_browse	True	Allows the user to browse content to find referenceable content.
startup_directory	string	''	Directory shown when the popup opens. Optional. When empty, the current folder is used. See the ATReferenceBrowser readme.txt for advanced usage.
base_query	dict or name of method		Defines query terms that will apply to all searches, mainly useful to create specific restrictions when allow_browse=0. Can be either a dictonary with query parameters, or the name of a method or callable available in cotext that will return such a dictionary.
force_close_on_insert	boolean	False	If true, closes the popup when the user choses insert. This overrides the default behavior in multiselect mode.
search_catalog	string	'portal_catalog'	Specifies the catalog used for searches
allow_sorting	boolean	False	Allows changing the order of referenced objects (requires multiValued).
show_review_state	boolean	False	If True, popup will display the workflow state for objects.
show_path	boolean	False	If True, display the relative path (relative to the portal object) of referenced objects.
only_for_review_states		None	If set, content items are only referenceable if their workflow state matches one of the specified states. If None there will be no filtering by workflow state.
image_portal_types	sequence	()	Use to specify a list of image portal_types. Instances of these portal types are previewed within the popup widget
image_method	string	None	Specifies the name of a method that is added to the image URL to preview the image in a particular resolution (e.g. 'mini' for thumbnails).
history_length	integer	0	If not zero, enables a history feature that show the paths of the last N visited folders.
restrict_browsing_to_startup_directory	boolean	False	If True, the user will not be able to browse above the starting directory.

RichWidget

Allows the input of text, or upload of a file, in multiple formats that are then transformed as necessary for display. For example, allows you to type some content, choose formatting and/or upload a file. If available, the visual editor set in personal preferences is used for editing and formatting.

Special Properties

Name	Type	Default	Description
rows	integer	5	Number of rows. (Since the visual mode of the RichWidget is controlled by JavaScript, this is not very useful.)
cols	integer	40	Number of columns. (Since the visual mode of the RichWidget is controlled by JavaScript, this is not very useful.)
allow_file_upload	boolean	True	If True, a file upload option is included with the field.

SelectionWidget

Renders an HTML selection widget, which can be represented as a dropdown, or as a group of radio buttons.

Special Properties

Name	Type	Default	Description
format	string	'flex'	Possible values: 'flex', 'select', 'radio'. Uses radio buttons when set to radio, and a single-selection list when set to select. Using flex will automatically use single-selection lists for more than three settings at a time, and a single-select list for up to three settings.

StringWidget

Renders an HTML text input box which accepts a single line of text. For simple text lines such as author.

Special Properties

Name	Type	Default	Description
maxlength	integer	255	Maximum input length in characters; sets the HTML input tag's maxlength attribute.
size		30	Size of the input widget; sets the HTML input tag's size attribute.

TextAreaWidget

Renders an HTML text area for typing a few lines of text. Also provides for the entry of the content in multiple formats when allowed_content_types in the enclosing TextField allows it.

Special Properties

Name	Type	Default	Description
rows	integer	5	Number of rows for the edit widget; sets the HTML textarea tag's rows attribute.
cols	integer	40	Column width of the edit widget; sets the HTML textarea tag's cols attribute.
append_only	boolean	False	Set this attribute to True to make an append-only TextArea widget. New text gets added to the top of the existing text, dividing the new text from the existing text using the divider property. The existing text is shown below the TextArea, and is not editable. This currently works with TextArea widgets and using plain text format.
divider	string	========================	Divider text marker to use for append only text areas. Only used then the append_only property is True.
maxlength	integer	False	If non-zero, sets a maximum input length in characters. Since the HTML textarea tag has no maxlength property, this is enforced via a JavaScript snippet. So, it is is not applicable when JavaScript is unavailable.

4. Validator Reference

A quick reference to the built-in Archetypes validators.

Using Validators

Archetypes fields may have validators specified in the Field schema. For example, the schema for the basic page type includes the stanza:

ATDocumentSchema = ATContentTypeSchema.copy() + Schema((
    TextField('text',
...
              validators = ('isTidyHtmlWithCleanup',),
...
    ),

This specifies that the isTidyHtmlWithCleanup test will be applied to validate form input.

You may specify a sequence of validators:

validators = ('isMaxSize', 'isTidyHtmlWithCleanup',),

and the validators will tested in order.

The validators sequence may contain two kinds of entries:

The string names of validators registered with the validation service (see Products.validation);
Instances of classes implementing the IValidator interface (Products.validation.interfaces.IValidator.IValidator).

A validation specification using a validator class instance can look like:

validators = ( ExpressionValidator('python: int(value) == 5'), )

Registered Validators

These are validators pre-registered with the validation service. They may be specified by name.

Name	Use	Details
isDecimal	Is the input a decimal number.	Allows exponent notation.
isInt	Is the input an integer.
isPrintable	Does not contain unprintable characters	r'[a-zA-Z0-9\s]+$'
isSSN	Is a well-formed social-security number	Very naive: r'^\d{9}$'
isUSPhoneNumber	Is a valid US phone number	Looks for 10 digits, ignores spaces, parens and dashes
isInternationalPhoneNumber	Is a valid international phone number	Looks for any number of digits, ignores spaces, parens and dashes
isZipCode	Very naive: is five or nine digits
isURL	Is a valid URL	Recognizes most protocols
isEmail	Is a valid e-mail address	A pretty good regular expression test
isMailTo	Is an e-mail address preceded by "mailto:"
isUnixLikeName	Passes the basic test to be a Unix-style name	r"^[A-Za-z][\w\d\-\_]{0,7}$"
isMaxSize	Tests if an upload, file or something supporting len() is smaller than a given max size value.	Tests against a maxsize attribute on the field
isValidDate	Tests whether or not input value can be converted to a DateTime object.
isEmpty	Input value must be empty.
isEmptyNoError	Input value must be empty.	Validation will fail if input value is not empty; but no error will show.
isValidId	Input value is a valid identifier.
isTidyHtml	Uses mx.Tidy to validate HTML input. Fails on errors and warnings.
isTidyHtmlWithCleanup	Uses mx.Tidy to validate HTML input. Fails only on errors; cleans up.
isNonEmptyFile	The uploaded file is not empty.
isTAL	Validates as Template Attribute Language

Useful Validation Classes

These classes are useful for creating your own validation class instances. Imports and prototypes are shown. See source for details.

ExpressionValidator

Evaluates an expression to test the input value.

from Products.validation.validators.ExpressionValidator import ExpressionValidator

def ExpressionValidator(expression=None, errormsg=None)

RegexValidator

Tests value against a regular expression after removing ignore

characters.

from Products.validation.validators.RegexValidator import RegexValidator

def RegexValidator(name, regex, title=name, description='',
 errmsg='fails tests of %s' % name, ignore=None)

RangeValidator

Tests to see if specified minval <= input_value < maxval

from Products.validation.validators.RangeValidator import RangeValidator

def RangeValidator(name, minval=0.0, maxval=0.0, title='', description='')

Plone CMS: Open Source Content Management

Sections

Personal tools

Find Documentation by Topic

Document Actions

Fields

1. Overview

Archetypes Fields - A Simple Explanation

Some Definitions

Some Pre-Requisites

Fields, Classes, and Objects

2. Fields Reference

Topics

Common Field Attributes

Standard Fields

BooleanField

ComputedField

CMFObjectField

DateTimeField

FileField

FixedPointField

FloatField

ImageField

Using Image Scales

IntegerField

LinesField

ReferenceField

StringField

TextField

3. Widgets Reference

Widget Attribute Topics

Common Widget Attributes

Standard Widgets

BooleanWidget

CalendarWidget

Special Properties

ComputedWidget

Standard Properties

DecimalWidget

Special Properties

FileWidget

ImageWidget

Special Properties

InAndOutWidget

Special Properties

IntegerWidget

Special Properties

KeywordWidget

Special Properties

LabelWidget

LinesWidget

Special Properties

MultiSelectionWidget

Special Properties

PasswordWidget

Special Properties

Standard Properties

PicklistWidget

Special Properties

ReferenceWidget

Special Properties

ReferenceBrowserWidget

Special Properties

RichWidget

Special Properties

SelectionWidget

Special Properties

StringWidget

TextAreaWidget

Special Properties

4. Validator Reference

Using Validators

Registered Validators

Useful Validation Classes

ExpressionValidator

RegexValidator

RangeValidator