/ 
Konstrukt-0.5-beta12
River stage zero No dependents
/ Konstrukt::Plugin::formvalidator

NAME

Konstrukt::Plugin::formvalidator - HTML form validator

SYNOPSIS

Usage:

<!-- add form validation code to your page -->
<& formvalidator form="some_dialogue.form" / &>

or

<!-- the same but explicitly define the JS files -->
<& formvalidator
	form="/some/dialogue.form"
   script="/formvalidator/formvalidator.js"
   strings="/formvalidator/formvalidator_strings.js"
/ &>

Result:

<!-- add form validation code to your page -->
<script type="text/javascript" src="/formvalidator/formvalidator.js"></script>
<script type="text/javascript" src="/formvalidator/formvalidator_strings.js"></script>
<script type="text/javascript">
	<!-- JS definitions of your form ... -->
</script>

DESCRIPTION

HTML form validator for the Konstrukt framework. Allows for both client- and server-side form-validation.

First of all you have to define the structure and the constraints of the form you want to validate. Therefor you have to create a file, which looks like this:

$form_name = 'fooform';
$form_specification = {
	a        => { name => 'Element A',      minlength => 1, maxlength => 64,  match => '' },
	b        => { name => 'Element B',      minlength => 4, maxlength => 4,   match => '' },
	email    => { name => 'E-Mail Address', minlength => 1, maxlength => 128, match => '^.+?\@.+\..+$' },
	homepage => { name => 'Homepage'      , minlength => 0, maxlength => 256, match => '^[hH][tT][tT][pP]\:\/\/\S+\.\S+$'},
	_ignored => {...}
	...
};

The name is only needed by the JavaScript-Part to identify the the form within the document.

The specification is an anonymous hash. Each element represents an input-field in the HTML-form. Note that the HTML-element has to be named like the elements in the hash:

<input name="email" maxlength="128" />

For each element you have to specify a descriptive "name", which will be used for error messages, when the form doesn't validate, the "minlength" and "maxlength" constraints, and the regular expression "match", to which the elements value has to match to get the form validated.

If you only want to check fields, that contain a value, you may use a regular expression like "(match pattern if not empty|^$)".

Note that fields, which names start with an underline ("_") will be ignored by the validation progress.

Server-side validation is be done like this:

#get the plugin object
my $form = use_plugin 'formvalidator';

#load the form specification
$form->load('/path/to/form.form');

#populate the form with the values, which have been passed via HTTP using
#the CGI module ($Konstrukt::CGI->param(name))
$form->retrieve_values('cgi');

#validate the form
my $ok = $form->validate();

#throw out the errors
if (!$ok) { $self->add_node($form->errors()); }

#use the form data:
print $form->get_value('fieldname');

Client-side validation is done with help of a JavaScript, which has to be included into the HTML-file.

The Konstrukt-Plugin "formvalidator" will put the additional code into the HTML-source, which is needed to validate the form using JavaScript.

<& formvalidator form="/path/to/form.form" script="/path/to/formvalidator.js" strings="/path/to/formvalidator_strings.js" / &>

The form will be validated by the JavaScript upon submission (you must do this in your template that contains the form):

<form id="fooform" onsubmit="return validateForm(document.getElementById('fooform'))">...</form>

CONFIGURATION

You may want to set up the template file, which will be used to format the found errors, and the default scripts in your konstrukt.settings. Defaults:

formvalidator/error_template /formvalidator/error.template
formvalidator/script         /formvalidator/formvalidator.js
formvalidator/strings        /formvalidator/formvalidator_string.js

METHODS

init

Inititalization of this class

install

Installs the templates.

Parameters:

none

load

Loads a form specification file.

Parameters:

  • $file - The path to the form specification file

retrieve_values

Populates the form with the values, which have been passed via HTTP.

Parameters:

  • $method - The method how the values should be retrieved. Currently only 'CGI' is supported.

validate

Validates the form data agains the given form specification.

If every check is passed true will be returned. Otherwise this functin will throw out some error messages in template syntax an false will be returned.

Additionally all values will be freed of leading and trailing whitespaces.

Returns true, if the data is valid, false otherwise.

Parameters:

  • $dont_trim_values - If true, leading and trainling whitespaces will not be removed from the values.

  • $silent - Don't throw out an error message, when a field doesn't validate. Just remove that field from the form-hash.

get_value

Returns the value of a form field. Should only be called after the form values have been retrieved with the method retrieve_values().

If called in a list context, returns the fields values as an array, if the field exists. () otherwise.

If called in a scalar context, returns the fields first (maybe only) value, if the field exists. undef otherwise.

Parameters:

  • $fieldname - The name of the field, whose value is requested

errors

Returns an node with the errors that were found during form validation.

Parameters:

  • $templatefile - The file which will be used to format the found validation errors. Defaults to the formvalidator/error_template setting in your konstrukt.settings or to 'error.template', if not specified. This file should contain an template list named "list" with the template field named "error" which will contain the error message.

prepare

We can already return the form in the prepare step.

execute

All the work is done in the prepare step.

AUTHOR

Copyright 2006 Thomas Wittek (mail at gedankenkonstrukt dot de). All rights reserved.

This document is free software. It is distributed under the same terms as Perl itself.

SEE ALSO

Konstrukt::Plugin, Konstrukt