jason gessner > Data-Form-Elements-0.61 > Data::Form::Elements

Download:
Data-Form-Elements-0.61.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  1
Open  0
View/Report Bugs
Module Version: 0.60   Source  

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.

syntax highlighting: