Form Fields: Difference between revisions
Line 11: | Line 11: | ||
A MAP or MAP_MULT takes values in a list, which is any form whose implementing class subclasses I2CE_List. | A MAP or MAP_MULT takes values in a list, which is any form whose implementing class subclasses I2CE_List. | ||
A field of type MAP or MAP_MULT can specify the following 'default' sub-node. | ===Meta Magic Data for MAP Fields=== | ||
A field of type MAP or MAP_MULT can specify the following 'default' sub-node. | |||
Under the magic data node: | |||
/modules/forms/formClasses/$formClass/fields/$field/meta | |||
We can specify some further information which affects how a field is used as follows: | |||
*form: an optional parent node. The child nodes are all scalar nodes which specify the forms that this field can take values in. If not set, the name of the form is assumed to be the name of the field, $field. | |||
*display: An optional parent node. Each child node is a "named" display for that field which can be referenced in .html templale files. | |||
**default: Optional parent node. When displaying a field, if no display is specified, the data under the node "default" is used to determine the display. | |||
***fields: Optional scalar node. This node describe the hierarchy of how the data should be displayed, for example, in a tree view of the data, when selecting the value of this field. It has the general structure "mapform1+mapfield1:mapform2+mapfield2:...:mapformN". If the ''+mapFieldX'' is not present, then we use ''mapFormX+1'' for the value of ''mapFieldX''. If the 'fields' entry is is not set, then it is the mapped form is the the name of field. <p/> When we select a value for the field, we start by displaying all the values for ''mapFormN''. Under each one of these values, we display all values for ''mapFormN-1'' whose field ''mapFieldN-1'' is ''mapFormN'' is and continue down until we get to ''mapForm1''. <p/> If ''mapFormXX+mapFieldXX'' is surrounded in square brackets, [ ], then we don't display the data for that mapped form. | |||
***limits: | |||
***orders: | |||
See also: [[Defining Forms#Lists | Defining List Forms]] | |||
===Meta Magic Data Example=== | |||
For example, iHRIS_Person has a mapped field, 'residence'. It's meta node contains the following sub-nodes: | |||
<source lang='php'> | |||
'form' => Array [ | |||
0 => county | 0 => county | ||
1 => district | 1 => district | ||
] | ], | ||
'display' => Array [ | |||
default => Array [ | default => Array [ | ||
fields => county:district:[region]:country | fields => county:district:[region]:country | ||
] | ] | ||
] | ], | ||
'limits' => Array [ | |||
'default'=> Array [ | |||
'country'=> Array[ | |||
'operator'=>'FIELD_LIMIT', | |||
'field'=>'location', | |||
'style'=>'yes' | |||
] | |||
] | |||
] | ] | ||
</source> | |||
The optional 'forms' is an array of list that tell us which lists this field is allowed to take values in. In this case, any member of the county or district list may be chosen as the residence for a person. | The optional 'forms' is an array of list that tell us which lists this field is allowed to take values in. In this case, any member of the county or district list may be chosen as the residence for a person. | ||
In the above example, when selecting a residence for a person, you first choose the country, then the region, then the district. You may further specify the county. When displaying a selected residence it will display either: | In the above example, when selecting a residence for a person, you first choose the country, then the region, then the district. You may further specify the county. When displaying a selected residence it will display either: | ||
Line 37: | Line 54: | ||
County, Country District | County, Country District | ||
depending if you have selected the district or county. | depending if you have selected the district or county. | ||
==Field Types== | ==Field Types== |
Revision as of 09:50, 17 August 2011
Each form class $formClass contains a list of fields. A field $field in $formClass is defined at:
/modules/forms/formClasses/$formClass/fields/$field
which has the following sub-nodes
- formfield: Required. Needs should be on of the field type such as INT
- in_db: Optional. It should be either 0 or 1. If not set, defaults to 1. If 1, then this field should be saved into the database
- required: Optional. It should be either 0 or 1. If not set, defaults to 0. If 1, then this field needs to be set before it can be considered valid
- unique: Optional. It should be either 0 or 1. If not set, defaults to 0. If 1, then the value of this field needs to be unique among all instances of the form
- headers: Optional. It is itself a parent node, each child node is a string value. You can choose a different header by specifying the header attribute in a template file.
- default: Optional. The default title/header displayed for the field.
Map Fields
A MAP or MAP_MULT takes values in a list, which is any form whose implementing class subclasses I2CE_List.
Meta Magic Data for MAP Fields
A field of type MAP or MAP_MULT can specify the following 'default' sub-node. Under the magic data node:
/modules/forms/formClasses/$formClass/fields/$field/meta
We can specify some further information which affects how a field is used as follows:
- form: an optional parent node. The child nodes are all scalar nodes which specify the forms that this field can take values in. If not set, the name of the form is assumed to be the name of the field, $field.
- display: An optional parent node. Each child node is a "named" display for that field which can be referenced in .html templale files.
- default: Optional parent node. When displaying a field, if no display is specified, the data under the node "default" is used to determine the display.
- fields: Optional scalar node. This node describe the hierarchy of how the data should be displayed, for example, in a tree view of the data, when selecting the value of this field. It has the general structure "mapform1+mapfield1:mapform2+mapfield2:...:mapformN". If the +mapFieldX is not present, then we use mapFormX+1 for the value of mapFieldX. If the 'fields' entry is is not set, then it is the mapped form is the the name of field.
When we select a value for the field, we start by displaying all the values for mapFormN. Under each one of these values, we display all values for mapFormN-1 whose field mapFieldN-1 is mapFormN is and continue down until we get to mapForm1.
If mapFormXX+mapFieldXX is surrounded in square brackets, [ ], then we don't display the data for that mapped form.
- limits:
- orders:
- fields: Optional scalar node. This node describe the hierarchy of how the data should be displayed, for example, in a tree view of the data, when selecting the value of this field. It has the general structure "mapform1+mapfield1:mapform2+mapfield2:...:mapformN". If the +mapFieldX is not present, then we use mapFormX+1 for the value of mapFieldX. If the 'fields' entry is is not set, then it is the mapped form is the the name of field.
- default: Optional parent node. When displaying a field, if no display is specified, the data under the node "default" is used to determine the display.
See also: Defining List Forms
Meta Magic Data Example
For example, iHRIS_Person has a mapped field, 'residence'. It's meta node contains the following sub-nodes: <source lang='php'> 'form' => Array [
0 => county 1 => district ],
'display' => Array [
default => Array [ fields => county:district:[region]:country ] ],
'limits' => Array [
'default'=> Array [ 'country'=> Array[ 'operator'=>'FIELD_LIMIT', 'field'=>'location', 'style'=>'yes' ] ]
] </source> The optional 'forms' is an array of list that tell us which lists this field is allowed to take values in. In this case, any member of the county or district list may be chosen as the residence for a person.
In the above example, when selecting a residence for a person, you first choose the country, then the region, then the district. You may further specify the county. When displaying a selected residence it will display either:
District, Country
or
County, Country District
depending if you have selected the district or county.
Field Types
Each field has a type. The types define how they are displayed to the end user in both an edit and view only context. It also contains information about the type of column the data should be saved in a database. The available types are:
- BOOL is implemented by the class I2CE_FormField_BOOL is a choice between true and false
- CURRENCY is implemented by the class iHRIS_FormField_CURRENCY and is a currency type and an amount
- DATE_HMS is implemented by the class I2CE_FormField_DATE_HMS is a time only
- DATE_MD is implemented by the class I2CE_FormField_DATE_MD is a month and day
- DATE_TIME is implemented by the class I2CE_FormField_DATE_TIME is a year, month, day and time
- DATE_YMD is implemented by the class I2CE_FormField_DATE_YMD and is a year, month and day
- DATE_Y is implemented by the class I2CE_FormField_DATE_Y and is a year
- INT_GENERATE is implemented by the class I2CE_FormField_INT_GENERATE and is integer sequence that will populate the next value in the sequence
- INT is implemented by the class I2CE_FormField_INT is an integer
- INT_LIST is implemented by the class I2CE_FormField_INT_LIST is an array of integers
- INT_RANGE is implemented by the class I2CE_FormField_INT_RANGE is a ranged drop down of integers and was introduced in version 4.1. The range is specified by setting start (defaults to 0), end (defaults to 10) and step (defaults to 1) in the meta section of the field's options.
- MAP is implemented by the class I2CE_FormField_MAP and is the name and id of a list form
- MAP_MULT is implemented by the class I2CE_FormField_MAP_MULT and is an array of names and ids for list forms
- REFERENCE is a field which is a reference to another form and whose display value is based on the fields in that referenced form. You can see the defintion here
- STRING_LINE is implemented by the class I2CE_FormField_STRING_LINE and is a string
- STRING_MLINE is implemented by the class I2CE_FormField_STRING_MLINE and is multi-line string
- STRING_PASS is implemented by the class I2CE_FormField_STRING_PASS is a password value
- STRING_TEXT is implemented by the class I2CE_FormField_STRING_TEXT is a large multi-line string
- YESNO is implemented by the class I2CE_FormField_YESNO and is a choice between Yes and No