Fields Reference

Description

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	description	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	description	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	Description	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.

Example:

from DateTime.DateTime import DateTime

# inside the schema definiton
    DateTimeField('dateAdded',
        searchable = 1,
        required = 0,
        default_method = 'getDefaultTime',
        widget = CalendarWidget(
            label = 'Date Added'
        ),
    ),

...

#inside the content class definition
    def getDefaultTime(self):  # function to return the current date and time
        return DateTime()

FileField

Storage for large chunks of data such as plain-text files, office-automation documents, and so on. If you're using Plone 4 or newer, consider using plone.app.blob.field.BlobField instead, that stores the file data outside of the ZODB and accepts the same parameters as atapi.FileField. See this page for info about migration.

Standard properties

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

Special properties

Name	Type	Default	Description	some possible values
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	Description	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. If you're using Plone 4 or newer, consider using plone.app.blob.field.ImageField instead, that stores the image data outside of the ZODB, and accepts the same parameters as atapi.ImageField. See this page for info about migration.

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: Archetypes 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 specifying any additional scales in which the image will be available. Dictionary entries should be of the form 'scaleName':(width,height). The scaled versions will be accessible as object/<imagename>_<scalename>, e.g. object/image_mini.	{ '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')

From Plone 4 on, the plone.app.imaging package introduces a new way to control image scales, factoring this functionality out of Archetypes for reutilization. For example:

<img tal:define="scales context/@@images;
                 thumbnail python: scales.scale('image', width=64, height=64);"
     tal:condition="thumbnail"
     tal:attributes="src thumbnail/url;
                     width thumbnail/width;
                     height thumbnail/height" />

Would create an up to 64 by 64 pixel scaled down version of the image stored in the "image" field of the context. For further info, check the plone.app.imaging README file.

IntegerField

For storing numerical data as integers.

Standard properties

Name	Type	Default	Description	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	Description	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()"

 

More about References

Archetypes References work with any object providing the IReferenceable interface. They are mantained in the uid_catalog and reference_catalog catalogs. You can find both at the root of your Plone site. Check them to see their indexes and metadata.

Althought you could use the ZCatalogs API to manage Archetypes references, these catalogs are rarely used directly. A ReferenceField and its API is used instead.

To set a reference, you can use the setter method with either a list of UIDs or one UID string, or one object or a list of objects (in the case the ReferenceField is multi-valued) to which you want to add a reference to. Note that None and [] are equal.
For example, to set a reference from the myct1 object to the areferenceableobject object using the MyReferenceField field:

    >>> myct1.setMyReferenceField(areferenceableobject)

To get the referenced object(s), just use the getter method. Note that what you get are
the objects themselves, not their catalog brains.

    >>> myct1.getMyReferenceField()

StringField

A field for plain-text, unformatted strings.

Standard properties

Name	Type	Default	Description	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	Description	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'