====================
Descriptor Array
====================
While this descriptor array originated with [Savant](http://phpsavant.com) and
Solar, the structure is generic enough for any framework to generate, and for
any template system to render. The structure is composed of an array of
elements, where each element is itself an associative array.
An example element array looks like this:
{{code: php
$element = array(
'name' => 'addr',
'type' => 'text',
'label' => 'Street Address:',
'value' => '101 Main Street'
);
}}
Using this array, the view logic has all the information it needs to to
generate the form element output; similarly, the controller logic has
enough information to know what form element is mapped to which data
element, and what the current value is.
Of course, this describes only one element in a form; to describe a
series of form elements, put them into an array. The following array is
a representation of how the [[Solar_Form::$elements]] property is
structured:
{{code: php
$elements = array(
'addr' => array(
'name' => 'addr',
'type' => 'text',
'label' => 'Street Address:',
'value' => '101 Main Street'
),
'city' => array(
'name' => 'city',
'type' => 'text',
'label' => 'City:',
'value' => 'Beverly Hills'
),
'state' => array(
'name' => 'state',
'type' => 'select',
'label' => 'State:',
'value' => 'CA',
'options' => array('AL' => 'Alabama', 'CA' => 'California'),
),
'zip' => array(
'name' => 'zip',
'type' => 'text',
'label' => 'ZIP:',
'value' => '90210',
'attribs' => array('maxlength' => 5, 'size' => 5),
),
);
}}
--------------------
Element Keys
--------------------
These are the element information array keys, and their expected values.
Remember, these are generally hints to the template or view output
generator, and may or may not be honored by different template systems
(although Solar_View does honor them all).
| Key | Type | Description
| --------- | ------------- | ---------------------------------------------------------
| `name` | string | the element name
| `type` | string | the element type; e.g. text, radio, select, checkbox, etc
| `label` | string | a short label for the element
| `descr` | string | a longer description of the element
| `value` | string\|array | the value of the element, or the value of the selected option; if the element has multiple values (as from a multiple select), this is a sequential array of values
| `require` | bool | whether or not the element is required
| `disable` | bool | whether or not editing of the value should be disabled (i.e., read-only)
| `options` | array | key-value pairs of options for select, radio, checkbox, etc; each array key is the actual value of the option, and the corresponding array value is the displayed label of the option
| `attribs` | array | key-value pairs for additional attributes to be applied
| `filters` | array | array of Solar_Filter methods to validate and sanitize user input
| `invalid` | array | "validation failed" messages
Note that you don't need to specify all of these keys for every element
info array. Thus, in many cases, you can get away with just specifying
the type, label, and default value; if you want filtering and
validation, of course, you'll need to add those too.
`type` string
-------------
The 'type' is the XHTML element type. Strictly speaking, you can use any
string you like here, in case your particular template or view system
supports added element types. In general, though, you can expect to use
these values:
| type | maps to... | uses 'options'?
| ----------- | ----------------------------- | ---------------
| `button` | | no
| `checkbox` | | yes
| `file` | | no
| `hidden` | | no
| `image` | | no
| `password` | | no
| `radio` | | yes
| `reset` | | no
| `select` | | yes
| `submit` | | no
| `text` | | no
| `textarea` | | no
In some cases, you can use the 'options' key (described below) to tell
the form output generator what options are available for the input type;
e.g., in a select list, or a set of radio buttons, or the
checked/unchecked values for a checkbox.
`label` string
--------------
This is a short descriptive label string for the form element.
`descr` string
--------------
This is a longer description of the form element, generally for
tooltips, help functions, and so on.
`value` string or array
-----------------------
The default value of the form element. In cases where 'options' are
used, this is the default selected or checked option key. If the `value`
is an array and the element is a multiple-select, all the `value` option
keys should show as selected by default.
`require` bool
--------------
A boolean flag indicating whether or not an element should be noted as
"required" by the form output generator. The output noting a field as
"required" may change from system to system (Solar_View by default shows
a red ##red|*## by the label to note required items).
`disable` bool
--------------
A boolean flag indicating whether or not the element should be displayed
as read-only by the form output generator. If the element is disabled,
the user should see the element and its value, but not be able to change
it.
`options` array
--------------------
The options array tells the form what values to allow for selection, and
is treated differently by the different element types (and ignored most
of them except for 'select', 'radio', and 'checkbox').
For 'select' and 'radio' elements, the options array is a set of
key-value pairs where the array key is the "real" value for the option
when selected or checked, and the array value is the label for that
option. For example, if you create a 'select' element with these options
...
{{code: php
$info = array(
'type' => 'select',
'value' => 'TN',
'options' => array(
'AL' => 'Alabama',
'KY' => 'Kentucky',
'TN' => 'Tennessee',
'VA' => 'Virginia',
),
);
$form->setElement('state', $info);
}}
... you should see output that looks something like this:
{{code: html
}}
For 'checkbox' elements, the options array is sequential, where element
0 is the **checked** value, and element 1 is the **unchecked** value.
(This may not be intuitive; the elements are in this order because an
unchecked value may not always be necessary, but a checked value is.)
For example, you can create a 'checkbox' element with these options ...
{{code: php
$info = array(
'type' => 'checkbox',
'value' => 'y',
'options' => array('y', 'n'),
);
$form->setElement('contact_me', $info);
}}
... and see output something like this:
{{code: html
}}
(Note that this is Solar_View output, which uses a hidden value to
indicate the unchecked value; the later checkbox value, if checked, will
override the hidden value on form submission.)
`attribs` array
--------------------
This is an array of XHTML attributes to apply to the element. In the
case of 'select' elements, this will apply to the