Archetypes schemas

by Plone Documentation Team — last modified Mar 14, 2009 01:48 PM
Contributors: Mikko Ohtamma, Martin Aspeli, Kamon Ayeva, Israel Saeta Pérez
Introducing Archetypes-based schemas and fields.

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.

Fields, Classes, and Objects

Archetypes Fields are Python objects contained within the Schema. A Field is defined once for an Archetypes content class. This single Field instance is used for every instance of that class.  Therefore, the relationship between Field instances and content classes is described as such: "A field instance belongs to exactly one class." 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.

When Zope starts up, during product initialization, Archetypes reads the schema of the registered classes and "automagically" generates methods to read (the accessor) and change (the mutator) each of the fields defined.

Stock schemas

Archetypes includes three stock schemas:

  • BaseSchema: defines a normal content type,
  • BaseFolderSchema: defines a folderish content type (object can contain other objects),
  • BaseBTreeFolderSchema: for folders which need to handle hundreds or thousands of objects (even up to millions).

All three include two fields, id and title, as well as the standard Dublin Core metadata fields.

Modifying the fields of an existing schema

Modifying an existing schema field is possible using the syntax schema['<field_name>'].attribute = value. For example, to change the label of the description field widget (already available in BaseSchema), you can write (in your defined schema definition that reuses BaseSchema):

schema['description'].widget.label = u'Summary'

The fields in the schema are ordered, and normally first fields come first in "add" and "edit" forms. To rearrange a field within the schema use the moveField method:

  • Place it before a specific field: schema.moveField('<field_to_move>', before='<field_to_place_it_before>')
  • Place it after a specific field: schema.moveField('<field_to_move>', after='<field_to_place_it_after>')
  • Place it at the top of the schema: schema.moveField('<field_to_move>', pos='top')
  • Place it at the bottom: schema.moveField('<field_to_move>', pos='bottom')
  • Place it in a specific position: schema.moveField('<field_to_move>', pos=0)