======
Fields
======

:Revision: $Id: fields.txt 30588 2005-12-13 19:19:00Z dkuhlman $

.. sectnum::    :depth: 4
.. contents::   :depth: 4


The fields represent the semantics of an attribute of an object.
The object can be an actual ZODB object, or could be a directory
entry; knowing this is not the field's concern but the job of the
StorageAdapter.

The basic field types represent the standard types one can find in
python


Basic field types
=================

- String Field -- A string

- Password Field -- A password

  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.

- StringList Field -- A list of strings

- Int Field -- An integer

- Long Field -- A long

- Float Field -- A float

- DateTime Field -- A DateTime

- File Field -- A File object

- Image Field -- An Image object


Basic field properties
======================

Fields are configured using the following properties.

- default_expr -- Default value expression

  The default value for this field at creation time. It is also
  used if the attribute is not found on an object when it is
  accessed, this can happen on an old instances if its schema is
  edited later. In the expression the following namespace is
  available:

  - datamodel: the datamodel

  - field: the current field

  - user: the current user

  - portal: the portal

  - DateTime: a DateTime constructor

  - nothing: None

- is_indexed -- Indexed in SearchableText

  If true the field is indexed in SearchableText. This only has
  meaning for String and String List fields.

- acl_read_permissions -- ACL: Read permissions

  A ';'-separated list of permissions. If not empty, the user must
  have at least one of the permissions on the object to have read
  access to the field.

- acl_read_roles -- ACL: Read roles

  A ';'-separated list of roles. If not empty, the user must have
  at least one of the roles on the object to have read access to
  the field.

  When dealing with member directory entries, the user is deemed
  to have the role 'Owner' if the entry in question is his.

- acl_read_expr -- ACL: Read expression

  A TALES expression which returns a boolean describing on what
  condition read access to the field is allowed. In the expression
  the following namespace is available:

  - datamodel: the datamodel

  - field: the current field

  - user: the current user

  - roles: the current user's roles

  - context: the context (the container in creation mode) (the
    directory for directory entries)

  - proxy: the proxy (None in creation mode)

  - dir: an alias for the context

  - nothing: None

- acl_write_permissions -- ACL: Write permissions

- acl_write_roles -- ACL: Write roles

- acl_write_expr -- ACL: Write expression

  Conditions to have write access to the field. See the read
  access description above.

- read_ignore_storage -- Read: ignore storage

  If true, nothing is actually read from the storage (object or
  directory entry). The default value or the 'read expression'
  will be used.

- read_process_expr -- Read: expression

  If not empty, the value read from the storage is further
  processed through this TALES expression. The expression's return
  value is what the rest of CPSSchemas will see. The following
  namespace is available:

  - value: the value that was really read from the storage

  - data: a mapping of the values read from the storage for this entry

  - field: the current field

  - user: the current user

  - portal: the portal

  - proxy: the potentially associated proxy 

  - object: the context object

  - DateTime: a DateTime constructor

  - nothing: None

  - context: deprecated, use the "object" key instead

  Note that the context object is the object on which the read is
  being done, it is not the proxy (in the case of attribute
  storage).

- read_process_dependent_fields -- Read: expression dependent fields

  If the above expression uses some other fields, they must be
  specified here so that the back-end knows what to fetch when a
  re-computation is done.

- write_ignore_storage -- Write: ignore storage

  If true, nothing will actually be written to the storage.

- write_process_expr -- Write: expression

  If not empty, the written value will be processed though this
  TALES expression before being really written to the storage. The
  same namespace than for 'read_process_expr is available, except
  that 'value' and 'data' refer to the value as seen by the rest
  of CPSSchemas before writing.


Additional properties
=====================

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

- File Field

  - suffix_text -- Suffix for field containing Text conversion

    Describes which String Field will hold the text conversion.

  - suffix_html -- Suffix for field containing HTML conversion

    Describes which File Field will hold the HTML conversion.

    These two properties, if not empty, define the id of another
    field of the schema (derived from the id of the current field
    by adding the specified suffix) that will store an
    automatically generated conversion to text or HTML.

    The conversion is currently done using the PortalTransforms
    framework.

- Disk File Field
      
  This field stores the file on the disk instead of in the ZODB.
    
  - 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.
        
      
.. Emacs
.. Local Variables:
.. mode: rst
.. End:
.. Vim
.. vim: set filetype=rst:
