view release on metacpan or  search on metacpan

lib/Form/Processor.pm  view on Meta::CPAN

    return $field->required_text;
}


sub value {
    my ( $form, $name, $no_die ) = @_;
    my $field = $form->field( $name, $no_die ) || return;
    return $field->value;
}



sub value_changed {
    my ( $self, $name ) = @_;
    croak "value_chagned requires a field name" unless $name;

    my $field = ref( $name ) ? $name : $self->field( $name );
    croak "Failed to lookup field name [$name]\n" unless $field;

    return $field->value_changed;
}



sub set_existing_values {
    my $form = shift;

    my $params = $form->params;

    for my $field ( $form->fields ) {

        # Does the field insist that the value must be provided?
        next if $field->must_submit;

        my $name = $field->name;
        next if exists $params->{$name};

        next if $field->writeonly;

        my %hash_params = $field->format_value;

        $form->params( %hash_params );
    }
}





sub uuid {
    my $form = shift;
    require Data::UUID;
    my $uuid = Data::UUID->new->create_str;
    return qq[<input type="hidden" name="form_uuid" value="$uuid">];
}



sub parent_field {
    my $self = shift;
    return Scalar::Util::weaken( $self->{parent_field} = shift ) if ( @_ );
    return $self->{parent_field};
}





1;

__END__

=pod

=encoding UTF-8

=head1 NAME

Form::Processor - validate and process form data

=head1 VERSION

version 1.162360

=head1 SYNOPSIS

In an application you might want a controller to handle creating and updating a
"User" record.  And not want to write much code.  Here's using L<Catalyst> as
an example:

    package MyApplication::Controller::User;
    use strict;
    use MyApplication::Form::User;

    sub edit : Local {
        my ( $self, $c, $id ) = @_;

        # Create the form object
        my $form = MyApplication::Form::User->new( $id );


        # Update or create the user record if form posted and form validates
        $form->update_from_from( $c->request->parameters  )
            if $c->form_posted;


        $c->stash->{form} = $form;
    }

The above form class might then look like this:

    package MyApplication::Form::User;
    use strict;
    use base 'Form::Processor::Model::CDBI';

    sub object_class { 'DB::User' }

    sub profile {
        my $self = shift;

        return {

lib/Form/Processor.pm  view on Meta::CPAN

field's value.

This only does a string compare (arrays are sorted and joined).
And note that:

    'foo' != ['foo']

which is probably incorrect.

=item use_existing_values

Default: false

By default all required fields MUST be supplied to the validate method.
This works great for forms submitted by browsers because browsers
submit all fields (except un-selected checkboxes and radio buttons).

When used with an API or AJAX it may be useful to allow a subset
of fields to be submitted.  Fields not submitted retain their
existing value.

When this flag is true if the field is not supplied in the hash
supplied to the validate method then will default to the field's
current formatted value, if any.

Do not enable this on web forms, though.  Otherwise, any checkboxs
will always remain checked once checked.

If this feature is enabled it can be selectively disabled on a field
by setting the field's "allow_existing" attribute.  This simply
means that a key of the field's name must be supplied.  It does
not inspect the key's value.

This is implemented by set_existing_values.

=item set_existing_values EXPERIMENTAL

This method will load existing values into params for any not supplied.

This does not work on compound fields.

=item uuid

Generates a hidden html field with a unique ID which
the model class can use to check for duplicate form postings.

=item parent_field

This value can be used to link a sub-form to the parent field.

One way to create a compound field -- a field that is composed of
other fields -- is by having the field include a form that is made up of
fields.  For example, a date field might be made up of a form that includes
fields for the day, month, and year.

If a form has a parent_field associated with it then any errors will be pushed
onto the parent_field instead of the current field.  In the date example, an error
in the year field will cause the error to be assigned to the date field, not directly
on the year field.

This stores a weakened value.

=back

=head1 CREATING A MODEL CLASS

Form model classes are used to moved form data between a
database and the form, typically via an object relational
mapping tool (ORM).

See L<Form::Processor::Model> for details.

=head1 THINGS TO WONDER ABOUT

The CGI parameters passed in are stored in Form::Processor instead of in
each field object.

When a field is entered and then changed to a different format, what format
should be displayed?  That is, a form with a date is updated.  The text
"tomorrow" is entered.  If the form doesn't validate what should display?
The actual formatted date for tomorrow, or still the text "tomorrow"?

Currently, if the form doesn't validate "tomorrow" is displayed.  But if
the form validates (and is updated by the model class) then the form will
display the formatted date for tomorrow.  That still may be different from
what the date might look like next time it's fetched from the database 
(due to timezone settings).  Another way to go would be to re-load from the
database object to make the date look like it will next time it's fetched
on a fresh form.

Init from object happens in Form::Processor, too.  It would be nice to have each
field know how to initalize from the source object.  But, that doesn't work well
with overriding Form::Processor with the Model class.

=head1 SUPPORT / WARRANTY

L<Form::Processor> is free software and is provided WITHOUT WARRANTY OF ANY KIND.
Users are expected to review software for fitness and usability.

=head1 AUTHOR

Bill Moseley <mods@hank.org>

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2012 by Bill Moseley.

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

=cut