Developers/Concepts/CustomFields

From Tine 2.0 - Wiki

< Developers

Custom Fields

NOTE: Beginning with version Milan (2012/03), you can edit custom fields directly in the (Admin) GUI. The following steps are no longer needed.

Custom Fields are record properties which could be defined in user space. A user with appropriate rights could define additional fields e.g. for a contact record. Per default this Custom Fields show up in a "Custom Fields" tab in the corresponding edit dialog.

Custom Fields are also available In standard grid panels as columns and filters.

Configuration

Custom Field Configuration is placed in the tine20_customfield_config table. Each Custom Field has a unique name for an application and model. The definition of the Custom Field is placed in the definition column which is a JSON encoded array/struct with the following properties:

  • label Custom Field label
  • type Data Type. One of {string|int|date|time|datetime|bool|keyfield}
  • value_search support type ahead suggestions on DISTINCT basis
  • uiconfig struct with ui/client configuration. Supported properties:
    • group field set name for field grouping
    • order field order
    • xtype force a certain xtype on field generation
  • options struct to place options for custom types here
  • keyFieldConfig (type keyfield only) struct:

Examples

// type string:
{"label":"suggeststring","type":"string","value_search":1}


// type date with grouping:
{"label":"Date","type":"Date", "uiconfig":{"order":"10","group":"My Fieldset"}} 


// type keyfield:
{"label":"definedkeyfield","type":"keyField","keyFieldConfig":{"value":{"records":[{"id":"LOW","value":"Low"},{"id":"MID","value":"Mid"},{"id":"HIGH","value":"High"}],"default":"MID"}}}


As the Custom Field Configuration is cached, you need to clear the cache when manually editing the configs/definitions!


How to add customFields http://www.tine20.org/wiki/index.php/CLI_Functions#Tinebase.addCustomfield

Grants

Custom Fields have an own grants concept which extends the normal grants concept of the corresponding record. For a given Custom Field, a user must have explicit grants to see or edit this field.

Custom Field Rights are stored in the tine20_customfield_acl table. The grants column supports two grants:

  • readGrant The Grant to read a Custom Field value
  • writeGrant The Grant to add/edit/delete a Custom Field value

If no Grant is active, the user can not see the presece and value of a certain Custom Field.


Storage

Custom Field Values are stored in the tine20_cutomfield table. In DB the value is always stored as a string. Custom Field Values are transported as a strcut through the customfield property of the records. That means, that only records which have defined the customfields property can use Custom Fields. As all Values are transported as strings, no conversions like timezone adoptions or record creations are done on sever/client side automatically atm.

Discussion/TODO

  • dynamic server client model extension with single cf properties if cf's are defined
  • transform values according to their definitions -> this would help to support types like record/recordset
  • have a customfield prefix like #?
  • have customfield admin interfaces which support all types and acl