NAME

Oogly::Aagly - A form building, processing and data validation system!

VERSION

version 0.03

SYNOPSIS

Oogly-Aagly is basically form building on top of the Oogly data validation framework. This means that existing packages and code using Oogly can be easily converted to utilize this new functionality.

The following is an example of that...

    use MyApp::FormFu;
    my $form = MyApp::FormFu->new(\%params);
    my @flds = qw/search/;
    if ($form->validate(@flds)){
        ...
    }
    else {
	print $form->render('form_name', '/url', @flds);
    }

    package MyApp::FormFu;
    use Oogly::Aagly;

    # cpan and see Oogly for all the gritty details ...
    field 'search' => {
        label => 'user search',
        error => 'your search must contain a valid id number',
	element => {
	    type => 'input',
	    template => ''
	},
        validation => sub {
            my ($form, $field, $params) = @_;
            $form->error($field, $field->{error})
                if $field->{value} =~ /\D/;
        }
    };

METHODS

render

The render method returns an html form using the supplied url, and fields.

templates

The templates method is used to define the absolute path to where the form element templates are stored.

$form->templates('/var/www/templates/');

template

The template method is used to define the relative path to where the specified form element template is stored.

$form->template(input => 'elements/input_text.tt');

Warning!

Oogly-Aagly is still undergoing testing, etc. The package is being published as a proof-of-concept sort-a-thing. Use at your own risk, although I am confident you'll love the simplicity, syntax and DRY nature.

Building Forms

Ok really quickly, the idea behind Oogly-Aagly (derived from Oogly) is to define each piece of incoming data individually for DRY (dont repeat yourself) purposes. It stands-to-reason that you'll need to use/create a form element or validate the same data input more than once in an application of any complexity, that said, say your application (and probably your database) has a email field, chances are the validation rules, form element look and feel, etc, are the same each time you request it from the user, so it makes sense to define it only once and call it when we need it, this is the where Oogly/Oogly-Aagly concept of fields come in. Anyway...

package Foo;
use Oogly::Aagly ':all';

field 'email' => {
    'label' => 'Email address',
    'error' => 'Please use a valid email address',
    'element' => {
        type => 'input_text',
    },
    validation => sub {
        return $_[1]->{value} =~ /\@/ if $_[1]->{value};
    }
};

my $form = Foo->new($params_hashref);
$form->render('form_name', 'url', 'email');

In the code above we have labeled the input parameter, given it a label, specified which type of html form element should represent it when called, and defined a simple validation rule to validate input.

If you are used to using Oogly the only difference you'll notice s the existence of the `element` hashref. This key is used to defined all form element related options.

Forms are rendered using HTML Templates marked-up using Template-Toolkit syntax and are stored in the Perl library. The `goat.pl` (Get Oogly-Aagly Template) utility can be used to copy those templates to the current work directory for customization. Oogly-Aagly only has templates for HTML form input elements, the following is a guide to each element and how it might be defined.

Form Templates

form

... form.tt
This template is a wrapper that encapsulates the selected form elements
rendered.

input_checkbox

... input_checkbox

field 'languages' => {
    element => {
        type => 'input_checkbox',
        options => {
            { value => 100, label => 'English' },
            { value => 101, label => 'Spanish' },
            { value => 102, label => 'Russian' },
        }
    },
    default => 100
};

... or ...

field 'languages' => {
    label => 'US Languages',
    element => {
        type => 'input_checkbox',
        options => {
            { value => 100, label => 'English' },
            { value => 101, label => 'Spanish' },
            { value => 102, label => 'Russian' },
        }
    },
    default => [100,101]
};

input_file

... input_file

field 'avatar_upload' => {
    element => {
        type => 'input_file'
    }
};

input_hidden

... input_hidden

field 'sid' => {
    element => {
        type => 'input_hidden'
    },
    value => $COOKIE{SID} # or whatever
};

input_password

... input_password

field 'password_confirm' => {
    element => {
        type => 'input_password'
    }
};

input_radio

... input_radio

field 'payment_method' => {
    element => {
        type => 'input_radio',
        options => {
            { value => 100, label => 'Visa' },
            { value => 101, label => 'MasterCard' },
            { value => 102, label => 'Discover' },
        },
        default => 100
    }
};

input_text

... input_text

field 'login' => {
    element => {
        type => 'input_login'
    }
};

select

... select

field 'payment_terms' => {
    element => {
        type => 'select',
        options => {
            { value => 100, label => 'Net 10' },
            { value => 101, label => 'Net 15' },
            { value => 102, label => 'Net 30' },
        },
    }
};

select_multiple

... select_multiple

field 'user_access_group' => {
    element => {
        type => 'select_multiple',
        options => {
            { value => 100, label => 'User' },
            { value => 101, label => 'Admin' },
            { value => 102, label => 'Super Admin' },
        },
    }
};

textarea

... textarea

field 'myprofile_greeting' => {
    element => {
        type => 'textarea',
    }
};

Validating Forms

Validating forms is the point, simply pass and array list of field names to the validate method in the order in which you would like them validated and presto.

package Foo;
use Oogly::Aagly ':all';

field 'email' => {
    'label' => 'Email address',
    'error' => 'Please use a valid email address',
    'element' => {
        type => 'input_text',
    },
    validation => sub {
        return $_[1]->{value} =~ /\@/ if $_[1]->{value};
    }
};

my $form = Foo->new($params_hashref);

if ($form->validate(@form_fields)) {
    # redirect ...
}
else {
    print $form->render('form_name', 'url', @form_fields);
}

Customizing Forms

Included with this package is a command-line utility, `goat.pl`, which should be used to copy Oogly-Aagly templates from the Perl library to your current-working-directory, once there you can specify that using the template method and customize your html elements any way you see fit.

my $form = Foo->new($params);
$form->templates('/var/www/view/elements');

You can expand the Oogly-Aagly template library using the template method to add custom templates.

my $form = Foo->new($params);
$form->template('input_jstree' => '/var/www/view/elements/input_jstree.tt');

More to come, try it for yourself...

AUTHOR

Al Newkirk <awncorp@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2010 by Al Newkirk.

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

cpanm Oogly::Aagly

perl -MCPAN -e shell
install Oogly::Aagly