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

Examples:
closure.php, elements.php, js-validation.php, lists.php, populate.php, reallife.php, redirect.php, session-timeout.php, simple.php, steps.php, and subclass.php.

Definition at line 217 of file htmlform.php.

Inheritance diagram for htmlform:

Public Member Functions

 __construct ($name, $parameters=array(), $form=null)
 htmlform class constructor More...
 
 updateInputValue ($name)
 Updates the value of an associated input element. More...
 
 getSteps ()
 Returns an array of steps. More...
 
 getCurrentStepId ()
 Returns the current step id. More...
 
 __toString ()
 Renders form to HTML. More...
 
 process ()
 Calls form validation and handles redirects. More...
 
 buildUrlQuery ($args=array())
 Adding step parameter to already existing query. More...
 
 getFirstInvalidStep ()
 Returns first step that didn't pass validation. More...
 
 redirect ($url)
 Redirects Browser to a different URL. More...
 
 validate ()
 Validates the forms subelements. More...
 
 validateAutosave ()
 
 isEmpty ()
 Returns wether form has been submitted before or not. More...
 
 populate ($data=array())
 Fills subelement values. More...
 
 getValues ()
 Gets form-data from current PHP session. More...
 
 getValuesWithLabel ()
 Gets form-data from current PHP session but also contain elemnt labels. More...
 
 checkElementName ($name)
 Checks for duplicate subelement names. More...
 
 clearSession ()
 Deletes the current forms' PHP session data. More...
 
- Public Member Functions inherited from container
 __construct ($name, $parameters, $form)
 container class constructor More...
 
 __call ($function, $arguments)
 HTML escaping and add subelements. More...
 
 addChildElements ()
 Sub-element generator hook. More...
 
 addHtml ($html)
 Adds a new custom HTML element to the container. More...
 
 addStepNav ($parameter=array())
 Adds automatic step navigation to output. More...
 
 validate ()
 Validates container and its contents. More...
 
 setRequired ($required=true)
 Sets required-attribute. More...
 
 getElements ($includeFieldsets=false)
 Returns containers subelements. More...
 
 getElement ($name)
 Gets subelement by name. More...
 
 clearValue ()
 Deletes values of all child elements. More...
 
- Public Member Functions inherited from element
 __construct ($name, $parameters, $form)
 element class constructor More...
 
 __call ($function, $arguments)
 HTML escaping. More...
 
 clearValue ()
 resets the value to null More...
 
 getName ()
 Returns the element name. More...
 

Data Fields

 $valid
 Form validation result/status. More...
 
- Data Fields inherited from element
 $valid
 Contains element validation status/result. More...
 

Protected Member Functions

 setDefaults ()
 Collects initial values across subclasses. More...
 
 addElement ($type, $name, $parameters)
 Adds input or fieldset elements to htmlform. More...
 
 getNewCsrfToken ()
 Returns new XSRF token. More...
 
 onValidate ()
 Validation hook. More...
 
- Protected Member Functions inherited from container
 addElement ($type, $name, $parameters)
 Generates sub-elements. More...
 
- Protected Member Functions inherited from element
 setDefaults ()
 Collects initial values across subclasses. More...
 
 checkParameters ($parameters)
 checks element parameters More...
 
 log ($argument, $type=null)
 error & warning logger More...
 
 htmlEscape ($options=array())
 Escapes HTML in strings and arrays of strings. More...
 

Protected Attributes

 $method
 HTML form method attribute. More...
 
 $submitURL
 HTML form action attribute. More...
 
 $successURL
 Specifies where the user is redirected to, once the form-data is valid. More...
 
 $label
 Contains the submit button label of the form. More...
 
 $class
 Contains the additional class value of the form. More...
 
 $sessionSlotName
 Contains the name of the array in the PHP session, holding the form-data. More...
 
 $sessionSlot
 PHP session handle. More...
 
 $ttl
 Time until session expiry (seconds) More...
 
- Protected Attributes inherited from container
 $elements = array()
 References to input elements and fieldsets. More...
 
 $elementsAndHtml = array()
 Input element, fieldset and custom HTML object references. More...
 
 $form
 Parent form object reference. More...
 
- Protected Attributes inherited from element
 $name
 Element name. More...
 
 $validated = false
 True if the element has been validated before. More...
 
 $log
 Log object reference. More...
 

Constructor & Destructor Documentation

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

htmlform class constructor

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

Definition at line 272 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 518 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
string$typeinput type or fieldset
string$namename of the element
array$parameterselement attributes: HTML attributes, validation parameters etc.
Returns
object $newElement element object

Definition at line 377 of file htmlform.php.

buildUrlQuery (   $args = array())

Adding step parameter to already existing query.

Returns
new query

Definition at line 615 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
string$namename to check
Returns
void

Definition at line 837 of file htmlform.php.

clearSession ( )

Deletes the current forms' PHP session data.

Returns
void

Definition at line 851 of file htmlform.php.

getCurrentStepId ( )

Returns the current step id.

Returns
int current step

Definition at line 470 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
int $stepNumber 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 655 of file htmlform.php.

getNewCsrfToken ( )
protected

Returns new XSRF token.

Returns
array element objects

Definition at line 505 of file htmlform.php.

getSteps ( )

Returns an array of steps.

Returns
array step objects

Definition at line 460 of file htmlform.php.

getValues ( )

Gets form-data from current PHP session.

Returns
array form-data

Definition at line 788 of file htmlform.php.

getValuesWithLabel ( )

Gets form-data from current PHP session but also contain elemnt labels.

Returns
array form-data with labels

Definition at line 811 of file htmlform.php.

isEmpty ( )

Returns wether form has been submitted before or not.

Returns
bool session status

Definition at line 759 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 868 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
array$datainput element names (key) and values (value)
Returns
void

Definition at line 773 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 570 of file htmlform.php.

redirect (   $url)

Redirects Browser to a different URL.

Parameters
string$urlurl to redirect to

Definition at line 680 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

Definition at line 322 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
string$namename of the input element
Returns
void

Definition at line 400 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()

Definition at line 700 of file htmlform.php.

validateAutosave ( )

If the form is autosaving the validation property is defaulted to false.

This function returns the actual state of input validation. It can therefore be used to test autosave fields are correct without forcing the form save.

Returns
bool $partValid - whether the autosave postback data is valid

Definition at line 731 of file htmlform.php.

Field Documentation

$class
protected

Contains the additional class value of the form.

Definition at line 238 of file htmlform.php.

$label
protected

Contains the submit button label of the form.

Definition at line 234 of file htmlform.php.

$method
protected

HTML form method attribute.

Definition at line 222 of file htmlform.php.

$sessionSlot
protected

PHP session handle.

Definition at line 246 of file htmlform.php.

$sessionSlotName
protected

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

Definition at line 242 of file htmlform.php.

$submitURL
protected

HTML form action attribute.

Definition at line 226 of file htmlform.php.

$successURL
protected

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

Definition at line 230 of file htmlform.php.

$ttl
protected

Time until session expiry (seconds)

Definition at line 258 of file htmlform.php.

$valid

Form validation result/status.

Definition at line 262 of file htmlform.php.


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