Public Member Functions | Data Fields | Protected Member Functions | Protected Attributes
htmlform Class Reference

Detailed Description

main interface to users

The class htmlform is the main tool of the htmlform library. It generates input elements and container elements. It also contains the PHP session handlers.

When you use depage-forms this is probably the only class you will instantiate directly.

In general:

 <?php 
     $form = new depage\htmlform\htmlform('simpleForm');

     // add form fields
     $form->addText('username', array('label' => 'User name', 'required' => true));
     $form->addEmail('email', array('label' => 'Email address'));

     // process form
     $form->process();
     
     if ($form->validate()) {
         // do something with your valid data
         var_dump($form->getValues());
     } else {
         // Form was empty or data was not valid:
         // Display the form.
         echo ($form);
     }
 ?>

You can find a list of available input-class in elements.

See examples at

Definition at line 183 of file htmlform.php.

Inheritance diagram for htmlform:
[legend]

Public Member Functions

 __construct ($name, $parameters=array(), $form=null)
 htmlform class constructor
 updateInputValue ($name)
 Updates the value of an associated input element.
 getSteps ()
 Returns an array of steps.
 getCurrentStepId ()
 Returns the current step id.
 __toString ()
 Renders form to HTML.
 process ()
 Calls form validation and handles redirects.
 getFirstInvalidStep ()
 Returns first step that didn't pass validation.
 redirect ($url)
 Redirects Browser to a different URL.
 validate ()
 Validates the forms subelements.
 isEmpty ()
 Returns wether form has been submitted before or not.
 populate ($data=array())
 Fills subelement values.
 getValues ()
 Gets form-data from current PHP session.
 checkElementName ($name)
 Checks for duplicate subelement names.
 clearSession ()
 Deletes the current forms' PHP session data.

Data Fields

 $valid
 Form validation result/status.

Protected Member Functions

 setDefaults ()
 Collects initial values across subclasses.
 addElement ($type, $name, $parameters)
 Adds input or fieldset elements to htmlform.
 onValidate ()
 Validation hook.

Protected Attributes

 $method
 HTML form method attribute.
 $submitURL
 HTML form action attribute.
 $successURL
 Specifies where the user is redirected to, once the form-data is valid.
 $label
 Contains the submit button label of the form.
 $class
 Contains the additional class value of the form.
 $sessionSlotName
 Contains the name of the array in the PHP session, holding the form-data.
 $sessionSlot
 PHP session handle.
 $ttl
 Time until session expiry (seconds)

Constructor & Destructor Documentation

__construct ( $  name,
$  parameters = array(),
$  form = null 
)

htmlform class constructor

Parameters:
$name(string) form name
$parameters(array) form parameters, HTML attributes
$form(object) parent form object reference (not used in this case)
Returns:
void

Reimplemented from container.

Definition at line 237 of file htmlform.php.

Member Function Documentation

__toString ( )

Renders form to HTML.

Renders the htmlform object to HTML code. If the form contains elements it calls their rendering methods.

Returns:
(string) HTML code

Definition at line 442 of file htmlform.php.

addElement ( $  type,
$  name,
$  parameters 
) [protected]

Adds input or fieldset elements to htmlform.

Calls parent class to generate an input element or a fieldset and add it to its list of elements.

Parameters:
$type(string) input type or fieldset
$name(string) name of the element
$parameters(array) element attributes: HTML attributes, validation parameters etc.
Returns:
$newElement (object) element object

Reimplemented from container.

Definition at line 320 of file htmlform.php.

checkElementName ( $  name)

Checks for duplicate subelement names.

Checks within the form if an input element or fieldset name is already taken. If so, it throws an exception.

Parameters:
$namename to check
Returns:
void

Definition at line 634 of file htmlform.php.

clearSession ( )

Deletes the current forms' PHP session data.

Returns:
void

Definition at line 647 of file htmlform.php.

getCurrentStepId ( )

Returns the current step id.

Returns:
(int) current step

Definition at line 407 of file htmlform.php.

getFirstInvalidStep ( )

Returns first step that didn't pass validation.

Checks steps consecutively and returns the number of the first one that isn't valid (steps need to be submitted at least once to count as valid). Form must have been validated before calling this method.

Returns:
$stepNumber (int) number of first invalid step

If there aren't any invalid steps there must be a fieldset directly attached to the form that's invalid. In this case we don't want to jump back to the first step. Hence, this little hack.

Definition at line 513 of file htmlform.php.

getSteps ( )

Returns an array of steps.

Returns:
(array) step objects

Definition at line 398 of file htmlform.php.

getValues ( )

Gets form-data from current PHP session.

Returns:
(array) form-data

Definition at line 612 of file htmlform.php.

isEmpty ( )

Returns wether form has been submitted before or not.

Returns:
(bool) session status

Definition at line 585 of file htmlform.php.

onValidate ( ) [protected]

Validation hook.

Can be overridden with custom validation rules, field-required rules etc.

Returns:
void
See also:
validate()

Definition at line 668 of file htmlform.php.

populate ( $  data = array())

Fills subelement values.

Allows to manually populate the forms' input elements with values by parsing an array of name-value pairs.

Parameters:
$data(array) input element names (key) and values (value)
Returns:
void

Definition at line 598 of file htmlform.php.

process ( )

Calls form validation and handles redirects.

Implememts the Post/Redirect/Get strategy. Redirects to success Address on succesful validation otherwise redirects to first invalid step or back to form.

Returns:
void
See also:
validate()

Definition at line 486 of file htmlform.php.

redirect ( $  url)

Redirects Browser to a different URL.

Parameters:
$url(string) url to redirect to

Definition at line 537 of file htmlform.php.

setDefaults ( ) [protected]

Collects initial values across subclasses.

The constructor loops through these and creates settable class attributes at runtime. It's a compact mechanism for initialising a lot of variables.

Returns:
void

Reimplemented from element.

Definition at line 269 of file htmlform.php.

updateInputValue ( $  name)

Updates the value of an associated input element.

Sets the input elements' value. If there is post-data - we'll use that to update the value of the input element and the session. If not - we take the value that's already in the session. If the value is neither in the session nor in the post-data - nothing happens.

Parameters:
$name(string) name of the input element
Returns:
void

Definition at line 342 of file htmlform.php.

validate ( )

Validates the forms subelements.

Form validation - validates form elements returns validation result and writes it to session. Also calls custom validator if available.

Returns:
(bool) validation result
See also:
process()

Reimplemented from container.

Definition at line 556 of file htmlform.php.

Field Documentation

$class [protected]

Contains the additional class value of the form.

Definition at line 203 of file htmlform.php.

$label [protected]

Contains the submit button label of the form.

Definition at line 199 of file htmlform.php.

$method [protected]

HTML form method attribute.

Definition at line 187 of file htmlform.php.

$sessionSlot [protected]

PHP session handle.

Definition at line 211 of file htmlform.php.

$sessionSlotName [protected]

Contains the name of the array in the PHP session, holding the form-data.

Definition at line 207 of file htmlform.php.

$submitURL [protected]

HTML form action attribute.

Definition at line 191 of file htmlform.php.

$successURL [protected]

Specifies where the user is redirected to, once the form-data is valid.

Definition at line 195 of file htmlform.php.

$ttl [protected]

Time until session expiry (seconds)

Definition at line 223 of file htmlform.php.

$valid

Form validation result/status.

Reimplemented from element.

Definition at line 227 of file htmlform.php.

The documentation for this class was generated from the following file: