Descriptor Array

While this descriptor array originated with Savant 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:

<?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:

<?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).

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:

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 ...

<?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:

<select name="state">
    <option value="AL" label="Alabama">Alabama</option>
    <option value="KY" label="Kentucky">Kentucky</option>
    <option value="TN" label="Tennessee" selected="selected">Tennessee</option>
    <option value="VA" label="Virginia">Virginia</option>
</select>

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 ...

<?php
$info = array(
    'type' => 'checkbox',
    'value' => 'y',
    'options' => array('y', 'n'),
);
$form->setElement('contact_me', $info);
?>

... and see output something like this:

<input type="hidden" name="contact_me" value="n" />
<input type="checkbox" name="contact_me" value="y" checked="checked" />

(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 <select> tag and not to the <option> tags. For example, a textarea element can specify the cols and rows ...

<?php
$info = array(
    'type' => 'textarea',
    'value' => 'type something here',
    'attribs' => array(
        'rows' => 24,
        'cols' => 80,
    ),
);
$form->setElement('body_text', $info);
?>

... and would generate something like the following output:

<textarea name="body_text" rows="24" cols="80">type something here</textarea>

filters array

This is an array of Solar_Filter callbacks to apply to the element as part of user input validation (cf. the Solar_Form::validate() method). For example:

<?php
$info = array(
    'type' => 'text',
    'filters' => array(

        // trim spaces with PHP trim()
        'sanitizeTrim',

        // text must be only characters a-z, A-Z, and 0-9.
        'validateAlnum',

        // text must be at least 6 chars long.
        array('validateMinLength', 6),

        // text must be no longer than 12 chars 
        array('validateMaxLength', 12),
    ),
);
?>

invalid array

This is an array of messages to give to the user, generally related to user input not passing validation rules. Typically you will not need to specify feedback yourself; instead, the Solar_Form::validate() method will populate it for you.