API >> mvc >> helpers >> form

Helper methods to simply form creation and automatically meet XHTML and accessibility standards. To simplify form validation, all form elements automatically maintain their values when the form is submitted to the same page.

open(array $args = array())

Opens the form container. This method will not let you open a second form if one is already open; if you try while debug mode is enabled this will throw a PHP user notice.
All $args are optional and turn into properties of the HTML form tag, a few are handled specially:

• action - where the form gets submitted to, if omitted the current REQUEST_URI is used.
• method - either get or post (default is post)
• title - if you set the title it is used for both title and form legend
• legend - if you set legend and omit title, then legend is used as the title too
• alert - displays a message at the top of the form wrapped in the errormessage CSS class

close()

Closes the form container. This method will not let you close a form if one is not open; if you try while debug mode is enabled this will throw a PHP user notice.

label - property available to all form elements

Adds a label tag to the input; if omitted it will generate a label based on the element name.
Two optional properties are available to control label display:

• addBreak - Boolean, default is true - if true a BR tag is added between the label and the form element.
• labelFirst - Boolean - determines if the label should preceed or follow the form element, the default is true for most elements, false for radio and checkboxes.

$_POST['errors']

Set a key to the name of any form element and the value will be displayed next to it with the errormessage CSS class applied, eg.:
if (!isset($_POST['fullname'])) {
    $_POST['errors']['fullname'] = 'Fullname is required';
}
echo $html->input(array('name' => 'fullname'));
This will display the "Fullname is required" message in red above the fullname input if the fullname is omitted. (Note that this is only a sample for illustrative purposes and not the proper way to do form validation.)

input(array $args)

Valid $args keys are any properties that are valid within the HTML input. Options for $args['type'] must correspond to:

• text (default, this is used if type is omitted)
• hidden
• password
• file
• button
• image
• submit
• textarea
• select - alias for the select() method
• checkbox - alias for the checkboxes() method
• radio - alias for the radios() method

Any input can specify the focus property which will cause the input to be in focus (the cursor will be in the box) upon page load.
Setting the maxlength property works with any element including textareas.
Textareas used for inputting HTML can utilize the Boolean preview property. When set to true a live-preview box appears under the textarea and shows a rendered display of the HTML that is entered into the textarea as it gets typed.
Textareas have an extra property of wysiwyg, which can be set to Boolean true or an array of options and the textarea will be displayed as a WYSIWYG textarea (requires the TinyMCE package to be installed.) Options can be any setting within the TinyMCE API.
Sample usage:
echo $form->input(array('name' => 'email'));
echo $form->input(array('type' => 'password', 'name' => 'password', 'label' => 'Confirm your password'));
echo $form->input(array('type' => 'textarea', 'name' => 'content', 'wysiwyg' => true));
echo $form->input(array('type' => 'hidden', 'name' => 'id', 'value' => '123456789'));
echo $form->input(array('name' => 'submit'));

validatedInput(array $args)

Returns an input that is initialized to be validated using the Validator package. $args are the same as input().

select(array $args)

Returns a form select pulldown or multiple-select box. Operates like input() except adds keys for:

• options - the selection options
• leadingOptions - same as options but display before all the other options
• optgroups - seperates options into subgroups, the group title is not selectable, only the options within it
• value - the preselected options - this is only used when a $_POST value for the input does not exist
• multiple - Boolean, default is false - if false returns a pull-down menu, if true a multiple-select box will be returned and the value properties can accept either a string or an array of values

Sample usage:
typical select pulldown with leading option prepended
$args = array(
    'name' => 'mySelectPulldown',
    'leadingOptions' => array('' => 'Choose an option below'),
    'options' => array('value1' => 'text1', 'value2' => 'text2', 'value3' => 'text3'), 
    'value' => 'value3'
); 
echo $html->select($args);
Multiple select box
$args = array(
    'name' => 'myMultiSelectBox', 
    'multiple' => true, 
    'options' => array('value1' => 'text1', 'value2' => 'text2', 'value3' => 'text3'), 
    'value' => array('value2', 'value3') 
);
echo $html->select($args);
Multiple select box with option groups
$group1 = array('g1value1' => 'g1text1', 'g1value2' => 'g1text2', 'g1value3' => 'g1text3'); 
$group2 = array('g2value1' => 'g2text1', 'g2value2' => 'g2text2', 'g2value3' => 'g2text3'); 
$args = array( 
    'name' => 'myMultiSelectBoxWithOptionGroups', 
    'multiple' => true, 
    'optgroups' => array('group 1' => $group1, 'group 2' => $group2),
    'value' => array('g1value2', 'g2value1') 
); 
echo $html->select($args);

radios(array $args)

Returns a set of radio inputs. Operates like input() except adds:

• options - the array of radio options, can be either an associative array or dynamically-assigned numeric (but cannot mix the two)
• optionBreak - set the text or HTML to appear between each option, default is the BR tag (for full display control use the $radios and $checkboxes array properties instead of echoing out the response of radios())
• addFieldset - unless this is set to false, a fieldset will automatically wrap radio arrays consisting of two or more radio elements

Sample usage:
$args = array(
    'name' => 'myRadios', 
    'options' => array('value1' => 'text1', 'value2' => 'text2', 'value3' => 'text3'), 
    'value' => 'value3' 
); 
echo $html->radios($args);
$args = array( 
    'name' => 'myRadios', 
    'options' => array('text1', 'text2', 'text3'), 
    'value' => 2
 ); 
echo $html->radios($args);

checkboxes(array $args)

Works the same as radios() except allows value to be either a string or an array (to have multiple checkboxes checked by default.) Also, if you have 2 or more checkboxes in your options and your checkbox name is not in array form the PHP array brackets will be added for you.

$radios and $checkboxes array properties

These contain an array of the form radio or checkbox elements created in the last instance of radios() or checkboxes(). These properties allow fine-grained display control over your checkbox and radio elements. Sample usage:
$html->radios($args); 
echo implode(' -- ', $html->radios);

$months property

Contains an array mapping month numbers to human-friendly numer-name captions. This array is ideal to use as options for a credit card expiration month select box.

dateSelect(array $args)

Returns an array of selection boxes to select the date and/or time. Keys for $args are:

• time - boolean, if true time selection will also be added - will be set true automatically if you set any options for the hour, minute or mil (below)
• year, month, day, hour, minute, ampm - each has an array with possible keys:

• options - an array of options that are available
• label - the label to appear with it, default values are set if this is omitted - Note: the default CSS will hide the labels on a date select, so you will need to adjust this to use the label option.

• minute has an additional key of increment that can be set to an integer of: 5, 10, 15, 20, 30 (default is 1)
• year has additional keys of start and end which must be set to valid years
• mil - sets to 24-hour military time, the ampm setting is ignored and the default hours are 0-23 instead of 1-12
• addBreak - add a BR between each selection box, default is false
• value - an array with a key for year, month, day, hour, minute or ampm will let you set the default value of each date/time segment