The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
CGI-FormBuilderX-More-0.020
River stage zero No dependents
++
/ CGI::FormBuilderX::More

NAME

CGI::FormBuilderX::More - Additional input gathering/interrogating functionality for CGI::FormBuilder

VERSION

Version 0.020

SYNOPSIS

    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 {

    }

DESCRIPTION

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.

EXPORT

missing( <value> )

Returns 1 if <value> is not defined or the empty string ('') Returns 0 otherwise

Note, the number 0 is NOT a "missing" value

METHODS

CGI::FormBuilderX::More->new( ... )

Returns a new CGI::FormBuilderX::More object

Configure exactly as you would a normal CGI::FormBuilder object

pressed( <name> )

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.

missing( <name> )

Returns 1 if value of the param <name> is not defined or the empty string ('') Returns 0 otherwise

Note, the number 0 is NOT a "missing" value

    value       missing
    =====       =======
    "xyzzy"     no
    0           no
    1           no
    ""          yes
    undef       yes

input ( <name>, <name>, ..., <name> )

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).

input_slice( <name>, <name>, ..., <name> )

Returns a hash of key/value pairs 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).

input_slice_to( <hash>, <name>, <name>, ..., <name> )

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.

Returns the original hash passed in

input_param( <name> )

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

validate( [<code>] )

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.

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");
        }
    }

input_tie( <hash> )

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.

    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.

input_fetch( <key> )

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.

input_store( <key>, <value>, <value>, ..., <value> )

Given a key and some values, input_store will store the values (as an array reference) in an internal attribute stash.

This allows you get/set values in the form without affecting the underlying request param.

errors

In scalar context, returns an array reference of errors found during validation, if any. In list context, returns the same, but as a list.

prepare

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.

Returns a hash reference in scalar context, and a key/value list in array context.

AUTHOR

Robert Krimen, <rkrimen at cpan.org>

BUGS

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.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc CGI::FormBuilderX::More

You can also look for information at:

ACKNOWLEDGEMENTS

COPYRIGHT & LICENSE

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.