form - Ariadne CMS

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_int`	A positive integer.
`abs_money`	A positive decimal number, using '.' for thousands and '.' as decimal point.
`abs_money_us`	A positive decimal number, using ',' for thousands and ',' as decimal point.
`abs_number`	A positive number.
`alpha`	Only letters.
`alphanumeric`	Letters and numbers.
`credit_card`	A credit card number.
`date`	A date in the form dd/mm/yyyy or mm-dd-yyyy or dd.mm.yyyy.
`domain_name`	A domain name.
`email`	An email address.
`int`	An integer.
`money`	A decimal number, positive or negative.
`money_us`	A decimal number, positive or negative, using ',' for thousands and '.' as decimal point.
`number`	A number.
`time`	Time in the format HH:MM(:SS).
`url`	A 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>

More than a CMS