1   Generalities

The fields represent the semantics of a named value for a storage object, for instance an attribute of a ZODB persistent object, a value in a dict, a getter/setter pair, a column in SQL.

Fields are grouped in schemas. Storage objects can typically have several schemas.

Fields are abstractions : whatever the actual storage object is, its scope of persistence (ZODB, session, request) and how to read/write from it are outside the scope of fields. Read about storage adapters to learn about that. In the scope of this text, it is enough to know that storage for fields from a same schema on a given object will be accessed in the same way (namely through the same storage adapter).

In normal circumstances, accessing data from downstream code should always be done through data models (instances of the DataModel class). Most concrete CPS components (CPSDocument, CPSDirectory) provide the logic to build data models and use it.

Data models bootstrap everything in a transparent way, and in particular the logic defined and provided by fields :

As of CPS 3.5.1 (CPSSchemas >= 1.11.0, issue #2178), fields also guarantee type uniformity (both by rejecting invalid values and by transtyping if needed).

All of this allows downstream code to focus on its own business logic by eliminating exceptional cases, while (read/write expressions) leaving a handle open for easy configuration-only tweaks.

2   Basic field types

Most basic field types represent the standard types one can find in python, but some represent standard Zope 2 types.

The predefined default value is the default value of a freshly created field, prior to configuration. See "common properties" below for details on default values.

2.1   Simplest fields

These are straightforward:

  • Int Field (predefined default value: 0)
  • Long Field (predefined default value: 0L)
  • Float Field (predefined default value: 0.0)
  • Boolean Field (predefined default value: False)

2.2   String Field

As of CPS 3.5.1 (CPSSchemas >= 1.11.0), this is a unicode string. Before that, it used to be an instance of str. Predefined default value: empty string.

2.3   Ascii String Field

A string that's guaranteed to be either an str instance made of ASCCI characters only, so that downstream code does not need to care about automatic promotion to unicode. If there's a problem, it won't be because of content managed by an Acii String Field.

Because Zope 2 traversal does not understand unicode path, any field for a Zope path should be an Ascii String Field.

There are very rare cases where the content of this field can be a unicode string, namely instances upgraded to a version close to 3.5.1, and not upgraded again. Running the unicode upgrade steps meant for the relevant content (again) will clean them, because type coercition is done at the write time.

Predefined default value : empty string.

2.4   Password Field

The difference from a string is that there could be restrictions on the way this field is read, because passwords may be stored hashed or nor readable at all.

2.5   StringList Field

A list of strings. Actually, the read value is a tuple. Predefined default value: ()

2.6   Ascii StringList Field

As expected, this is to StringListField what Ascii String Field is to String Field.

2.7   DateTime Field

Represent Zope's DateTime objects, not to be confused with more recent python datetime objects. Predefined default value: None

2.8   File Field

Usually, this represents instances of OFS.Image.File, but other file objects are allowed, provided they have the same interface, such as CPSTramline's TramlineFile.

As of CPS 3.5.2 (CPSSchemas >= 1.13.0), Products.CPSUtil.file has helpers to access in turn data from these "File" objects uniformly, through the usual (basic python's) file API : read(), write(), seek(), etc.

Also, to instantiate the correct "File" object, there is a pluggable factory in CPSSchemas.FileUtils. All file objects creation (prior to setting in data model) should go through it. Sample use-case: CPSDocument's bulk upload (#2205) capability uses this factory. This allows CPSTramline to plug a simple logic to decide whether to spawn an ordinary OFS.Image.File object or a TramlineFile object.

2.9   Image Field

Same remark as for the File Field, except that the stored value is an image, with type OFS.Image.Image or a derivative. The aforementioned factory can handle image creation as well.

3   Common field properties

Fields are configured using the following properties.

4   Additional properties

Some specific fields have additional properties beyond the basic ones, to configure their specific behavior.

4.1   File Field

The File Field has automatic conversion capabilities and stores at write time the result of the conversion in auxiliary fields of the same schema. Those fields ids are deduced from the current's by application of a suffix.

In case the suffix is not provided, the corresponding conversion will not occur.

These are:

  • suffix_text -- Suffix for field containing Text conversion. Prime use-case : indexing.
  • suffix_html -- Suffix for field containing HTML conversion. Prime use-case: in-browser preview.

The conversion is currently done using the PortalTransforms framework, through the dependent fields system mentioned above. PortalTransforms is a separate Zope2 product, that's itself very pluggable (see PortalTransforms documentation)

4.2   Disk File Field

This field stores the file on the disk instead of in the ZODB. This field is currently deprecated in favor of the ordinary File field, together with CPSTramline for better transactional behaviour and upload/download efficiency.

It has all the properties of the ordinary File Field, plus:

  • disk_storage_path -- path relative to $INSTANCE_HOME for file storage.

If this path is not set, it will check if portal_schemas has a disk_storage_path property. If neither is set then var/files will be used.