Data::Form::Elements

Data::Form::Elements - a wrapper API for Data::FormValidator and a module for providing elemental access to the fields of a form, from a generic perspective. The form in question does not need to be an HTML form. Basically, if Data::FormValidator can use it as a form, so can we.

Version

Version 0.60

Synopsis

A quick example of using this module for a login form:

    use Data::Form::Elements;

    my $form = Data::Form::Elements->new();

    # add a couple elements
    $form->add_element( "username", { 
        required => 1, errmsg => "Please provide your username." } );
    $form->add_element( "password", { 
        required => 1, errmsg => "Please provide your password." } );

    ...

    $form->validate( %ARGS );

    if ( $form->is_valid() ) {
        # continue logging on ...
    }
    

Functions

new()

Simple constructor.

add_element()

Add an element to the form object. A full form element looks like this

    $form->add_element( "sort_position" , { 
        required => 0,
        valid  => 0,
        value => '',
        errmsg => 'Please choose where this section will show up on the list.',
        constratints => qr/^\d+$/,
        invmsg => 'Only numbers are allowed for this field.  Please use the dropdown to select the position for this section.' });
 

By default, only the name (key) is required. the required element will default to 0 if it is not specified. If required is set to 1 and the errmsg has not been initialized, it will also be set to a default.

_params()

Deprecated for external use. Returns a list of the elements in this form.

This was changed to be an "internal" method at the behest of David Baird for compatibility with Apache::Request and CGI. If you really need to get the list of form elements, call $form->param().

dump_form()

use Data::Dumper to help debug a form.

dump_validator()

use Data::Dumper to help debug a form's underlying Data::FormValidator.

validate()

Takes a hash of values, a CGI object or an Apache::Request object for the form elements and validates them against the rules you have set up. Support for CGI and Apache::Request objects sent in by David Baird http://www.riverside-cms.co.uk/.

Hash Ref Example: $form->validate( \%ARGS ); if ( $form->is_valid() ) { # continue processing form... }

CGI object Example

    $form->validate( \$query );
    if ( $form->is_valid() ) {
        # continue processing form...
    }
    

Apache::Request Example

    $form->validate( \$r );
    if ( $form->is_valid() ) {
        # continue processing form...
    }
    

is_valid()

Returns true/false.

param()

Getter/Setter methods for setting an individual form element.

Example: # getter print $form->param("username");

    # setter
    $form->param("username", "jason");
    

message()

returns the error or invalid message for a form element, if there is one. Returns undef if no message exists.

Field Name Accessor Methods

Thanks to Dr. David R. Baird, we now also have basic accessor methods for form elements. For example, now you can use either of the following lines to get a value.

    # normal, function based method.
    print $form->param("username"), "<br />\n";
    # accessor method
    print $form->username, "<br />\n";
    

Thanks a ton, David!

Author

jason gessner, <jason@multiply.org>

Bugs

Please report any bugs or feature requests to bug-testing@rt.cpan.org, or through the web interface at http://rt.cpan.org. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

Copyright & License

Copyright 2004 me, All Rights Reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Data::Form::Elements

perl -MCPAN -e shell
install Data::Form::Elements