Konstrukt::Plugin::formvalidator - HTML form validator
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>
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|^$)".
"(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>
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
Inititalization of this class
Installs the templates.
Parameters:
none
Loads a form specification file.
$file - The path to the form specification file
Populates the form with the values, which have been passed via HTTP.
$method - The method how the values should be retrieved. Currently only 'CGI' is supported.
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.
$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.
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.
$fieldname - The name of the field, whose value is requested
Returns an node with the errors that were found during form validation.
$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.
We can already return the form in the prepare step.
All the work is done in the prepare step.
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.
Konstrukt::Plugin, Konstrukt
To install Konstrukt, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Konstrukt
CPAN shell
perl -MCPAN -e shell install Konstrukt
For more information on module installation, please visit the detailed CPAN module installation guide.