How To Use Property Sheets

The need

is very rare. Most properties are already defined in exising property sheets, of which there is plenty. If you don't see a property you need, look closer, and think about a more generic name to it. If you are 100% sure it is not there because it is very specific, then create a new Property Sheet, through Portal Classes or directly in INSTANCE_HOME/PropertySheets directory.

Property definitions

Let's look at an excerpt from Person property sheet (the parts which do not use programmable acquisition, which is described later):

class Person:
    Person properties and categories
  _properties = (
    { 'id'         : 'prefix'
    , 'description': 'Name prefix.'
    , 'type'       : 'string'
    , 'mode'       : 'w'

  _categories = ('nationality', )

This is pretty straightforward: any person has a property "prefix" which is string (mode is required but not used - whether you can set it or no depends on security). Type is meant rather for conversion then checking - you can set it to 1, but you will get '1' anyway.

Every person has also a base category "nationality", so it can be classified to one of subcategories of portal_categories/nationality.


The properties and categories define the data model, and also create and API. From the above definitions, the Person gets a number of methods:


which do what their names suggest. Hint: if you set a list of nationalities (whether it makes any sense or not is out of scope of this article), getNationality will return the first one.

Hooking up to portal types

"The core way" is to add it to class definition - Products/ERP5/Document/ has it:

    property_sheets = ( PropertySheet.Base
                      , PropertySheet.XMLObject
                      , PropertySheet.CategoryCore
                      , PropertySheet.DublinCore
                      , PropertySheet.Reference
                      , PropertySheet.Person
                      , PropertySheet.Mapping
                      , PropertySheet.Task

There is also "the ZMI way" - in portal_types there is a box where you can choose additional property sheets for your type definition. This has the same effect.

Useful tricks

Attribute with a default value equal to another attribute

Let's say we have a form which displays two names of something: "long_name" and "short_name". short_name should by default be equal to long_name, unless the user overwrites it. We could do it by adding formulas to form fields, or by using interaction workflow etc, but the simplest and the most generic way would be to define a property in a property sheet. We can achieve this effect by using dynamic acquisition with masking:

   1 class TwoNames:
   2     """
   3         Defines 
   4     """
   6     _properties = (
   7         {   'id'          : 'long_name',
   8             'description' : 'normal name',
   9             'type'        : 'string',
  10             'mode'        : ''},
  12         {   'id'          : 'short_name',
  13             'description' : 'nickname',
  14             'type'        : 'string',
  15             'acquisition_base_category':('object',),
  16             'acquisition_portal_type':('Type',),
  17             'acquisition_accessor_id':'getLongName',
  18             'acquisition_mask_value':1,
  19             'alt_accessor_id' : ('getLongName',),
  20             'mode'        : '' },
  21     )

This way, the property short_name if not set will acquire value from the object itself, using getLongName accessor; and if set, it will "mask", or overwrite, the acquired value.

All magic is done by defining alt_accessor_id to methods tuple, which shall get value if none is set on object.

Programmable Acquisition in Property Sheets

Using special techniques it is possible to extend Zope's acquisition by special definitions in Property Sheets. All information are provided on another wikipage.

Default attribute

   1 class DefProp:
   2   """
   3     Property with default value
   4   """
   5   _properties = (
   6     {
   7       'id'          : 'def_prop',
   8       'description' : 'Property with default value',
   9       'type'        : 'string',
  10       'mode'        : 'w',
  11       'default'     : '',
  12     },
  13   )
  14   _categories = ( )

Above example will create property def_prop, which default value will be '' - empty string. You may access it by object.getProperty('def_prop') or object.getDefProp().

Keep in mind, that user interface in ERP5 is setting properties to None, when user clear field on form and not - as some developers think - to its default value. Look at this code snippet:

   1 # associate DefProp PropertSheet with portal type,
   2 # create new object of that type
   3 # create my_def_prop StringField in form associated with that portal type
   4 # and now fetch def_prop from created object:
   6 print repr(object.getDefProp()) # will print ''
   8 # now by user interface set def_prop to 'aaaa', and:
  10 print repr(object.getDefProp()) # will print 'aaaa'
  12 # and now using UI reset def_prop value to empty one, and:
  14 print repr(object.getDefProp()) # will print None

Own getter for special attribute

Let assume that your have two properties on object: colour_reference and size_reference. But you'd like to have special accessor getSizeCoulourReference, which will be composition of those two.

The simplest approach would be to modify object class and add new accessor. But if that class is defined in ERP5 code, than you'd have to modify this code, and updates will be much more difficult.

So define property in such way:

   1 from Products.CMFCore.Expression import Expression
   3 class SizeColourComposition:
   4   """
   5       Size colour composition reference.
   6   """
   7   _properties = (
   8     {
   9       'id'          : 'size_colour_reference',
  10       'description' : 'Reference made as size-colour composition',
  11       'type'        : 'string',
  12       'mode'        : 'w',
  13       'acquisition_base_category' : ('object',),
  14       'acquisition_portal_type' : Expression('python: []'),
  15       'acquisition_accessor_id' : 'getSizeColourReference',
  16       'alt_accessor_id' : ('Object_getSizeColourReference',),
  17       'acquisition_mask_value' : 0,
  18       'default'     : '',
  19     },
  20   )
  21   _categories = ( )

And Object_getSizeColourReference is a Script (Python) in your ZODB, which do all that magic:

   1 return 's:%s c:%s'%(context.getSizeReference(),context.getColourReference())

Try to invoke object/getSizeColourReference - voilĂ  - you have composition of size and colour.

/!\ Note: The acquisition_mask_value is set to 0 - this makes sure the property getter will ALWAYS call the script, event if you explicitly set property size_colour_reference.

Replacing an accessor

A propertysheet can override a property that have previously been added by another propertysheet. This will happen if you specify override=1 in the property sheet definition. For example, you can override getTitle for a given portal type with a property sheet similar to this one:

   1 class FunkyTitle:
   3      _properties = (
   4          {   'id'          : 'title',
   5              'type'        : 'string',
   6              'default'     : '',
   7              'acquisition_base_category'     : (),
   8              'acquisition_portal_type'       : (),
   9              'acquisition_copy_value'        : 0,
  10              'acquisition_mask_value'        : 1,
  11              'acquisition_depends'           : None,
  12              'acquisition_accessor_id'       : 'getTitle',
  13              'acquisition_depends'           : None,
  14              'alt_accessor_id'               : ('Base_getFunkyTitle', ),
  15              'override'    : 1,
  16              'mode'        : 'w' },
  17      )

The general problem with override is that it can only be used once per property, if two propertysheets wants to override the same accessor, the behaviour will be undefined (because it depends on accessors generation order). It's better to avoid using override on stock propertysheets, so that properties can still be overriden by customisation propertysheets if needed.

HowToUsePropertySheets (last edited 2008-03-28 13:13:05 by JeromePerrin)