ar\html\form

This module provides a simple way to generate standards compliant forms and validate input.

A form is created using the ar_html::form() method:

(object) ar('html')->form( $formFields, $buttons = null, $action = null, $method = 'POST' )

The $formFields argument is defined as an array of fields. Each field must have a name, a label and a type. In addition each field can have additional arguments. You don't have to specify every argument for each field, default settings will be used for everything not specified. In fact you can create the most basic form like this:

Example 1 - a very basic form.

<pinp>
  echo ar('html')->form( array('Name', 'Address') );
</pinp>

Which will output:

<form action="" method="POST"> 
  <div class="formField formText">
    <label>Name</label>
    <input type="text" name="Name" id="Name" value="">
  </div>
  <div class="formField formText">
    <label>Address</label>
    <input type="text" name="Address" id="Address" value="">
  </div>
  <div class="formButtons">
    <input type="submit" name="button_0" value="Ok">
  </div>
</form>

This will show a form with two text fields labelled 'Name' and 'Address'. If you want to specify more arguments, use a nested array like this:

Example 2 - specifying multiple arguments per field.

<pinp>
  echo ar('html')->form( array(
    'name' => array(
      'label'    => 'Name',
      'required' => true
    ),
    'address' => 'Address'
  ) );
</pinp>

Results in:

<form action="" method="POST"> 
  <div class="formField formText">
    <label>Name<span title="Required" class="formRequired">*</span></label>
    <input type="text" name="name" id="name" value="">
  </div>
<div class="formField formText">
    <label>Address</label>
    <input type="text" name="address" id="address" value="">
  </div>
  <div class="formButtons">
    <input type="submit" name="button_0" value="Ok">
  </div>
</form>

This makes the 'name' field required and the label and name of the field are no longer the same. The address field now also has a label which differs from the name.

The form api also supports handling and validating submitted form data. This is a simple form handle script:

 $form = ar('html')->form( array( 'Name', 'Address' ) );
 if ( $form->isSubmitted('button_0') )
{
  if ( $form->isValid() )
{
    $values = $form->getValues();
  }
else
{
    $invalid = $form->validate();
// you may add extra information about the invalid form fields
   echo $form;
  }  
 }
else
{
  echo $form;
 }

Below is a list of arguments available for most input fields.

(mixed) checks One or more validation checks. This can be a regular expression (must start with '/'), the name of a previously registered check or a callback ( see ar_pinp::getCallback() ).
See the checks list below for a list of predefined checks you can use.
(string) class An additional classname for the form field.
(mixed) default The default value of this field. If value is not set, this will be shown instead.
(bool) disabled If set to true, the field will be shown but disabled.
(string) id An optional html id for the form field.
(string) label The label to be shown next to the input field. If set to false, the label will be skipped (Ariadne > 2.7.2 ).
(string) name The name of the input field.
(bool) required If set to true, a value must be entered for this field.
(string) type The type of the input field. Valid types are listed above at 'available form input types'.
(mixed) value An optional value for the input field. If not set the form lib checks if the form input field has been entered already and if so pre-fills the field with that value.

The following types have additional arguments:

Checkbox:

(string)

checkedValue The value of the checkbox when checked.
(string) uncheckedValue The value of the checkbox when not checked. If set a hidden input is added before the checkbox with the same name as the checkbox, with this value.

Fieldset:

(array) children A list of child fields, just like the form array.

Image: (button type)

(string) src The source url for the image.

Select and Radio:

(array) options A list of options or radio buttons. The key is used as the option value and the value is used as the option name or radio label.

Buttons Format

The buttons list is an array containing the buttons to show below the form. Each button entry may consist of a number of arguments, just like form fields. The arguments for each button are:

(string) alt Only for type 'image'. This specifies the alternative text for the image.
(string) class The class name of the button
(string) id The id of the button
(string) name The name of the button
(string) src Only for type 'image'. This specifies the src url of the image.
(string) title The title attribute of the button.
(string) type The type of the button, 'button', 'submit', 'image' or 'reset'.
(string) value The label text of the button

methods

(void) addField Adds a form input field to the form.
(void) addButton Adds a button to the form.
(object) getHTML Returns the ar_html_tag for the form. (Ariadne > 2.7.2 )
(mixed) getValue Returns the current value for an input field.
(array) getValues Returns an array with all current values for all input fields. The name of the field is used as the key in this array.
(bool) isSubmitted Returns true when the form input fields are sent with the current HTTP request.
(bool) isValid Returns true when all form fields pass their validation checks.
(void) setValue Sets the current value for a form input field.
(array) validate Validates all form input fields and returns an array with the validation failures.
(void) registerInputType Registers a new form input type.
(void) registerValidateCheck Registers a new form input validation check.

properties

(string) action The action attribute of the form tag.
(string) class The class name of the form tag.
(string) encType The enctype (encryption type) attribute of the form tag.
(string) id The id of the form tag.
(string) method The method attribute of the form tag.
(string) name The name attribute of the form tag.
(string) requiredLabel The string to append to the label of required form fields.

The above properties are available on form objects, as generated by ar_html::form().

CSS Classes

div.formButtons Wrapper for the form submit buttons.
div.formField Wrapper for each form input field, except fieldset.
div.formFieldType Each form input type adds its name as a class to the field wrapper, e.g.: div.formText or div.formRadio
div.formRadioButtons Wrapper for a set of radio button fields.
div.radioButton Wrapper for a single radio button and its label.

Available Form Input Types

checkbox Shows a single checkbox.
fieldset Shows a fieldset with an optional legend. May contain a list of any form input type.
hidden Adds a hidden input field.
html Shows a field with static HTML.
password Shows a password input field.
radio Shows a list of radio buttons.
select Shows a single or multiple select list.
text Shows a text input field.
textarea Shows a textarea field.

Predefined validation checks

abs_intA positive integer.
abs_money
A positive decimal number, using '.' for thousands and '.' as decimal point.
abs_money_usA positive decimal number, using ',' for thousands and ',' as decimal point.
abs_number
A positive number.
alphaOnly letters.
alphanumericLetters and numbers.
credit_cardA credit card number.
dateA date in the form dd/mm/yyyy or mm-dd-yyyy or dd.mm.yyyy.
domain_nameA domain name.
emailAn email address.
intAn integer.
moneyA decimal number, positive or negative.
money_usA decimal number, positive or negative, using ',' for thousands and '.' as decimal point.
numberA number.
timeTime in the format HH:MM(:SS).
urlA url.

addField

(void) $htmlForm->addField( $field )

(mixed) $field The field definition for the form field.

This method adds a form field to an existing form. 

<pinp>
$form->addField( array(
'type' => 'select',
'label' => 'Color:',
'name' => 'color',
'class' => 'colorpicker',
'options' => array(
'#FFFFFF' => 'White',
'#CCCCCC' => 'Grey',
'#000000' => 'Black'
)
) );

addButton

(void) $htmlForm->addButton( $button )

(mixed) $button The field definition for the form button.

This method adds a form button to an existing form. 

getHTML

(object) $htmlForm->getHTML()

(Ariadne > 2.7.2) Returns the ar_html_tag for this form, including all its fields and buttons. This object can be simply echoed or manipulated with its built in dom manipulation methods, e.g:

$html = $form->getHTML();
$html->childNodes->setAttribute('class', array(
   'stripes' => ar::listPattern( '(odd even?)*' )
) );
echo $html;

getValue

(mixed) $htmlForm->getValue( $fieldName )

(string) $fieldName The name of the form field.

This method returns the current value for the named form input field.

getValues

(array) $htmlForm->getValues( )

This method returns and array with all the current values for all the form input fields. The keys of the array are the names of the input fields. 

isSubmitted

(bool) $htmlForm->isSubmitted( $fieldName = null )

(string) $fieldName The name of the form field to check against.

This method checks whether the named field has been submitted through either GET or POST methods. If no input field name is specified it will return true if any input field is found to be submitted. 

isValid

(bool) $htmlForm->isValid( )

Returns true if and only if all input field values pass all defined validation checks and if all required fields have been entered. 

setValue

(void) $htmlForm->setValue( $fieldName, $value )

(string) $fieldName The name of the form field.
(mixed) $value The new value for the form field.

Sets a new value for the form field. This will override any value entered through either the POST or GET request. 

validate

(array) $htmlForm->validate( )

Returns an array with all form fields which do not pass their validation checks or which are required but no data is entered. If all form fields validate, this method will return an empty array. 

( Ariadne > 2.7.2 ) The key for each entry is the name of the field, the value is the error message for that field.

registerInputType

(void) ar('html/form')->registerInputType( $type, $getInput,
            $getValue = null, $getLabel = null, $getField = null )

(string) $type The name of the input field type.
(mixed) $getInput Either a function callback or a template name which will generate the input field.
(mixed) $getValue Optional function or template to override the default getValue behaviour.
(mixed) $getLabel Optional function or template to override the default getValue behaviour.
(mixed) $getField Optional function or template to override the default getField behaviour. This overrides the full form field creation, so this must manually generate a label and input field.

Adds a new form input type to the global ar_html_form registry. Any form may use it after it is defined.e.g:

<pinp>
ar('html/form')->registerInputType( 'custom', 'get.custom.html' );
$form = ar('html')->form( array( 'name' => array( 'type' => 'custom' ) ) );
echo $form;
</pinp>

With get.custom.html as:

<pinp>
$field = ar::getvar('field'); // the full field object
return ar('html')->tag('input', array(
'type' => 'text',
'value' => $field->value
) );
</pinp>

This template uses the html writer module, since the form API wants the template to return a html string instead of echo├»ng it. 

registerValidateCheck

(void) ar('html/form::registerValidateCheck( $name, $check, $message )

(string) $name The name of the new validation check.
(mixed) $check The validation check as callback function or regular expression (must start with a '/').
(string) $message The error message to return when this check fails.

Adds a new validation check to the global ar_html_form registry. Any form element may use it after it is defined.

<pinp>
  ar('html/form')
->registerValidateCheck( 'custom', 'check.custom.html' );

  $form = ar('html')->form(
'name' => array( 'type' => 'text', 'checks' => 'custom' )
);

if ( $form->isSubmitted() )
{
  if ( !$form->isValid() )
{
echo 'Incorrect Form';
}
else
{
echo 'Correct Form';
}
}
else
{
echo $form;
}
</pinp>

And check.custom.html like this:

<pinp>
$value = ar::getvar( 'value' );
return ( $value == 'custom' );
</pinp>