CGI::FormBuilderX::More - Additional input gathering/interrogating functionality for CGI::FormBuilder
Version 0.020
use CGI::FormBuilderX::More; my $form = CGI::FormBuilderX::More( ... ); if ($form->pressed("edit")) { my $input = $form->input_slice(qw/title description/); # $input is { title => ..., description => ... } *ONLY* ... } elsif ($form->pressed("view") && ! $form->missing("section")) { # The paramter "section" is defined and is not '' ... } print $form->render; ... # Using the alternative, subroutine-driven, validation my $form = CGI::FormBuilderX::More( ..., validate => sub { my ($form, $error) = @_; if (! exists $_{username}) { $error->("username is required"); # Register the error } elsif ($_{username} =~ m/\W/) { $error->("username is malformed"); # A username was given but it's bad } if (! exists $_{password}) { $error->("password is required"); # Another error... } return if $error->(); # See if we've accumulated any errors unless (&authenticate({ $form->input_slice(qw/username password/) })) { $error->("no such username or incorrect password"); } }); if ($form->validate) { } else { }
CGI::FormBuilderX::More extends CGI::FormBuilder by adding some convenience methods. Specifically, it adds methods for generating param lists, generating param hash slices, determining whether a param is "missing", and finding out which submit button was pressed.
Returns 1 if <value> is not defined or the empty string ('') Returns 0 otherwise
Note, the number 0 is NOT a "missing" value
Returns a new CGI::FormBuilderX::More object
Configure exactly as you would a normal CGI::FormBuilder object
Returns the value of ->param(_submit_<name>) if _submit_<name> exists and has a value
If not, then returns the value of ->param("_submit_<name>.x") if "_submit_<name>.x" exists and has a value
If <name> is not given, then it will use the form's default submit name to check.
To suppress the automatic prefixing of <name> with "_submit", simply prefix a "+" to <name>
If <name> already has a "_submit" prefix, then none will be applied.
Otherwise, returns undef
Essentially, you can use this method to find out which button the user pressed. This method does not require any javascript on the client side to work
It checks "_submit_<name>.x" because for image buttons, some browsers only submit the .x and .y values of where the user pressed.
Returns 1 if value of the param <name> is not defined or the empty string ('') Returns 0 otherwise
value missing ===== ======= "xyzzy" no 0 no 1 no "" yes undef yes
Returns a list of values based on the param names given
By default, this method will "collapse" multi-value params into the first value of the param. If you'd prefer an array reference of multi-value params instead, pass the option { all => 1 } as the first argument (a hash reference).
Returns a hash of key/value pairs based on the param names given
The behavior of this method is similar to input_slice, except instead of returning a new hash, it will modify the hash passed in as the first argument.
input_slice
Returns the original hash passed in
In list context, returns the all the param values associated with <name> In scalar context, returns only the first param value associated with <name>
The main difference between input_param and input is that input_param only accepts a single argument AND input_param addresses the param object directly, while input will access the internal input_fetch/input_store hash
input_param
input
input_fetch
input_store
In CGI::FormBuilderX::More, we overload to the validate method to offer different behavior. This different behavior is conditional, and depends on the optional first argument, or the value of validate passed in to new.
validate
new
If either the first argument or ->new( validate => ... ) is a code reference then $form->validate takes on different behavior:
1. %_ is tied() to the form's input parameters 2. An error subroutine for recoding errors is passed through as the first argument to the validation subroutine 3. Any additional arguments to validate are passed through to the validation subroutine 4. The errors are available via $form->errors, which is a list reference 5. The errors are also available in the prepared version of $form (e.g. for template rendering) 6. $form->validate returns true or false depending on whether any errors were encountered
Here is an example validation subroutine:
sub { my ($form, $error) = @_; if (! exists $_{username}) { $error->("username is required"); # Register the error } elsif ($_{username} =~ m/\W/) { $error->("username is malformed"); # A username was given but it's bad } if (! exists $_{password}) { $error->("password is required"); # Another error... } return if $error->(); # See if we've accumulated any errors unless (&authenticate({ $form->input_slice(qw/username password/) })) { $error->("no such username or incorrect password"); } }
Given a hash reference, input_tie will tie the hash to form input. That is, accessing a hash entry is actually accessing the corresponding form param. Currently, only STORE, FETCH, and EXISTS are implemented.
input_tie
my %hash; $form->input_tie(\%hash); my $value = $hash{username}; # Actually does: $form->input_fetch("username"); $hash{password} = "12345"; # Actually does: $form->input_store(password => "12345"); return unless exists $hash{extra}; # Actually does: ! $form->missing("extra"); # Which checks to see if "extra" is defined and a non-empty string.
Given a key, input_fetch will return the value of first an internal attribute stash, and then request paramters (via input_param).
This allows you get/set values in the form without affecting the underlying request param.
In array context, the entire value list is returned. In scalar context, only the first value is returned.
Given a key and some values, input_store will store the values (as an array reference) in an internal attribute stash.
In scalar context, returns an array reference of errors found during validation, if any. In list context, returns the same, but as a list.
Prepares a hash containing information about the state of the form and returns it.
Essentially, returns the same as CGI::FormBuilder->prepare, with the addition of errors, which is a list of any errors found during validation.
errors
Returns a hash reference in scalar context, and a key/value list in array context.
Robert Krimen, <rkrimen at cpan.org>
<rkrimen at cpan.org>
Please report any bugs or feature requests to bug-cgi-formbuilderx-more at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=CGI-FormBuilderX-More. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
bug-cgi-formbuilderx-more at rt.cpan.org
You can find documentation for this module with the perldoc command.
perldoc CGI::FormBuilderX::More
You can also look for information at:
RT: CPAN's request tracker
http://rt.cpan.org/NoAuth/Bugs.html?Dist=CGI-FormBuilderX-More
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/CGI-FormBuilderX-More
CPAN Ratings
http://cpanratings.perl.org/d/CGI-FormBuilderX-More
Search CPAN
http://search.cpan.org/dist/CGI-FormBuilderX-More
Copyright 2007 Robert Krimen, all rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install CGI::FormBuilderX::More, copy and paste the appropriate command in to your terminal.
cpanm
cpanm CGI::FormBuilderX::More
CPAN shell
perl -MCPAN -e shell install CGI::FormBuilderX::More
For more information on module installation, please visit the detailed CPAN module installation guide.