Skip to content

Commit

Permalink
Update docs, remove input_to_value from WeekdayStr
Browse files Browse the repository at this point in the history
  • Loading branch information
@gshank
gshank committed Apr 23, 2009
1 parent 7844711 commit 422ac8b
Show file tree
Hide file tree
Showing 5 changed files with 86 additions and 73 deletions.
15 changes: 11 additions & 4 deletions TODO
View file
Original file line number Diff line number Diff line change
@@ -1,12 +1,20 @@
09/04/23
default apply actions and/or merging of apply actions
regularize usage of name/accessor/full_name/prename. which methods
(field(), field_exists(), field_index()) use which names?
add tests for apply actions
deflation support
re-factor field processing. move setting parent to field construction time.
will require processing all parent fields first (in order) followed by child fields
error messages issues for nested forms: prefix with field name?
improve field HTML produced in Render::Simple to include error messages or special css

09/04/09
rebuild book.db automatically when running make test
09/04/05
recursive automatic construction of fif?

09/04/01 gshank
09/04/04 - deleted stuff zby
refactor to handle calling form methods for validate_<fieldname> and
options_<fieldname> from fields (probably with coderefs)
improve auto field support
investigate a Catalyst View to provide better template support (like Reaction)
investigate other Form processing HTML generation
Expand All @@ -17,7 +25,6 @@
View::TT FillInForm role (check with jhannah)

bigger stuff
field constraints
support related rows, multiple rows
first step? handle related records with custom code. Gradually move to generic.

Expand Down
18 changes: 6 additions & 12 deletions lib/HTML/FormHandler.pm
View file
Original file line number Diff line number Diff line change
Expand Up @@ -663,20 +663,13 @@ The method does the following:
1) sets required dependencies
2) trims params and saves in field 'input' attribute
3) calls the field's 'process' routine which:
1) validates that required fields have a value
2) calls the field's 'validate' routine (the one that is provided
by custom field classes)
3) calls 'input_to_value' to move the data from the 'input' attribute
to the 'value' attribute if it hasn't happened already in 'validate'
4) calls the form's validate_$fieldname, if the method exists and
if there's a value in the field
5) calls cross_validate for validating fields that might be blank and
3) calls the 'fields_validate' routine from HTML::FormHandler::Fields
4) calls cross_validate for validating fields that might be blank and
checking more complex dependencies. (If this field, then not that field...)
6) calls the model's validation method. By default, this only checks for
5) calls the model's validation method. By default, this only checks for
database uniqueness.
7) counts errors, sets 'ran_validation' and 'validated' flags
8) returns 'validated' flag
6) counts errors, sets 'ran_validation' and 'validated' flags
7) returns 'validated' flag
Returns true if validation succeeds, false if validation fails.
Expand All @@ -692,6 +685,7 @@ sub validate_form
# Trim values and move to "input" slot
if ( exists $params->{$field->full_name} )
{
# trim_value may be replaced by some kind of filter in the future
$field->input( $field->trim_value( $params->{$field->full_name} ) )
}
elsif ( $field->has_input_without_param )
Expand Down
44 changes: 21 additions & 23 deletions lib/HTML/FormHandler/Field.pm
View file
Original file line number Diff line number Diff line change
Expand Up @@ -137,8 +137,22 @@ has 'value' => (
}
);

=head2 parent
A reference to the parent of this field.
=cut

has 'parent' => ( is => 'rw', predicate => 'has_parent' );

=head2 errors_on_parent
Flag indicating that errors should not be set on this field class
=cut

has 'errors_on_parent' => ( isa => 'Bool', is => 'rw' );

sub has_fields { }

=head2 input
Expand Down Expand Up @@ -295,7 +309,7 @@ sub build_prename
{
my $self = shift;
my $prefix = $self->form ? $self->form->name . "." : '';
return $prefix . $self->name;
return $prefix . $self->full_name;
}

=head2 widget
Expand Down Expand Up @@ -420,12 +434,12 @@ has 'range_end' => ( isa => 'Int|Undef', is => 'rw', default => undef );

sub value_sprintf
{
die "The 'value_sprintf' attribute has been removed. Please use a Moose coercion instead.";
die "The 'value_sprintf' attribute has been removed. Please use a transformation instead.";
}

sub input_to_value
{
die "The 'input_to_value' method has been removed.";
die "The 'input_to_value' method has been removed. Use a transformation or move to the 'validate' method.";
}

=head2 id, build_id
Expand Down Expand Up @@ -804,10 +818,7 @@ sub process

$field->clear_value;

# the trim_value here should be removed after we have support
# for default actions, when it should be done in '_apply_actions'
# and deprecated
$field->value( $field->trim_value($field->input) );
$field->value( $field->input );

# allow augment 'process' calls here
inner();
Expand Down Expand Up @@ -1023,22 +1034,9 @@ sub input_defined
return defined $value && $value =~ /\S/;
}

=head2 fif_value
A field class can use this method to format an internal
value into hash for form parameters.
A Date field subclass might expand the value into:
my $name = $field->name;
return (
$name . 'd' => $day,
$name . 'm' => $month,
$name . 'y' => $year,
);
=cut

# removed pod to discourage use of fif_value
# This method will probably be replaced by deflate or something
# similar in the near future
sub fif_value
{
my ( $self, $value ) = @_;
Expand Down
13 changes: 6 additions & 7 deletions lib/HTML/FormHandler/Field/WeekdayStr.pm
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,18 +2,17 @@ package HTML::FormHandler::Field::WeekdayStr;

use Moose;
extends 'HTML::FormHandler::Field::Weekday';
our $VERSION = '0.01';
our $VERSION = '0.02';

__PACKAGE__->meta->make_immutable;

# Join the list of values into a single string

sub input_to_value {
my $field = shift;

my $input = $field->input;

return $field->value( join '', ref $input ? @{$input} : $input );
sub validate
{
my $field = shift;
my $input = $field->input;
$field->value( join '', ref $input ? @{$input} : $input );
}

sub fif_value {
Expand Down
69 changes: 42 additions & 27 deletions lib/HTML/FormHandler/Manual/Intro.pod
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ and validation routines. Because it's a Perl class, you have a lot of
flexibility.

You can use transformations. Moose type constraints, and coercions, listed
in the 'apply' field array, to validate or inflate the fields
in the field's 'apply' attribute, to validate or inflate the fields
(see L<HTML::FormHandler::Field/apply>). You can define your own
L<HTML::FormHandler::Field> classes to create your own field types, and
perform specialized validation. And you can subclass the methods in
Expand Down Expand Up @@ -253,16 +253,18 @@ database, such as L<HTML::FormHandler::Model::DBIC> or
L<HTML::FormHandler::Model::CDBI>.

When using a database model, form field values for the row are retrieved from
the database using the field names as database class accessors.
the database using the field 'accessor' attributes (defaults to fieldname)
as database class accessors.
FormHandler will use relationships to populate single and multiple
selection lists, and validate input. It doesn't yet do anything with other
relationships, although it will return a hash of the relationship.
relationships (though there are plans), but it will return a hash of the
relationship created with HashRefInflator.

You can pass in either the primary key or a row object to the form. If a
primary key (item_id) is passed in, the model will use the item_class
(DBIC source name) to fetch the row from the database. If you pass in
a row object (item), the schema, source_class, and item_id will be set
from the row.
You can pass in either the primary key and or a row object to the form. If a
primary key (item_id) is passed in, you must also provide the schema.
The model will use the item_class (DBIC source name) to fetch the row from the
database. If you pass in a row object (item), the schema, source_class, and
item_id will be set from the row.

The C<< $form->process >> or C<< $form->update >> methods will validate
the parameters and then update or create the database row object.
Expand Down Expand Up @@ -292,15 +294,18 @@ using one of the methods mentioned above.

=head1 has_field

This is not actually a Moose attribute. It is just sugar to allow the
This is not actually a Moose attribute. It is sugar to allow the
declarative specification of fields. It will not create accessors for the
fields. The 'type' is not a Moose type, but an L<HTML::FormHandler::Field>
type. To use this sugar, you must do
class name. To use this sugar, you must do

use HTML::FormHandler::Moose;

instead of C< use Moose; >. Don't forget C< no HTML::FormHandler::Moose; > at
the end of the package. Use the syntax:
instead of C< use Moose; >. (Moose best practice advises putting
C< no HTML::FormHandler::Moose; > or C<< use namespace:clean -except => 'meta' >> at
the end of the package to keep the namespace clean of imported methods.)

To declare fields use the syntax:

has_field 'title' => ( type => 'Text', required => 1 );
has_field 'authors' => ( type => 'Select' );
Expand Down Expand Up @@ -352,6 +357,14 @@ classes using 'with':
no HTML::FormHandler::Moose;
1;

If you prefix the field name with a '+' the attributes in this definition
will modify existing attributes or be added to an existing field definition:

has_field 'user' => ( type => 'Text', ...., required => 1 );
....
has_field '+user' => ( required => 0 );


=head1 The form field_list

Returns a hashref of field definitions.
Expand Down Expand Up @@ -430,6 +443,8 @@ The 'guess_field_type' method could be customized to provide more
sophisticated determination of types. For the DBIC model, the schema
class must be available when the auto fields are constructed.

Note that field_lists do not have the same flexibility in subclassing
that 'has_field' fields do.

=head1 Fields

Expand Down Expand Up @@ -458,18 +473,15 @@ be set with the form's "field_name_space" attribute:
has_field 'name' => ( type => 'Text' ); # HTML::FormHandler::Field::Text
has_field 'foo' => ( type => +Foo' ); # MyApp::Form::Field::Foo

The most basic type is "Text", which takes a single scalar value. A "Select"
The most basic type is "Text", which takes a single scalar value. (If the
type of a field is not specified, it will be set to 'Text'.) A "Select"
class is similar, but its value must be a valid choice from a list of options.
A "Multiple" type is like "Select" but it allows selecting more than one value
at a time.

Each field has a "value" method, which is the field's internal value. This is
the value your database object would have (e.g. scalar, boolean 0 or 1,
DateTime object). A field's internal value is converted to the external value
by use of the field's C< fif_value > method. This method returns a hash which
allows a single internal value to be made up of multiple fields externally.
For example, a DateTime object internally might be formatted as a day, month, and
year externally.
DateTime object).

When data is passed in to validate the form, it is trimmed of leading and trailing
whitespace by the base field class and placed in the field's "input" attribute.
Expand All @@ -479,7 +491,8 @@ it's this internal value that is stored or used by your application.

By default, the validation is simply to copy the data from the "input" to the "value"
field attribute, but you might have a field that must be converted from a text
representation to an object (e.g. month, day, year to DateTime).
representation to an object (e.g. month, day, year to DateTime). These sorts of
conversions can also be done by Moose type constraints or apply transformations.

=head2 Filters, transformations, and constraints

Expand All @@ -489,6 +502,13 @@ inflate the HTML field input, such as for a DateTime. You can also create
non-Moose transformations and constraints. See the 'apply' attribute
in L<HTML::FormHandler::Field>.

has_field 'some_field' => ( apply => [ 'MooseType',
{ transform => sub {...}, message => 'xxxx' },
{ check => sub { ... }, message => 'xxxx' } ] );

The actions in the 'apply' array will be performed in the order they are
specified, allowing fine-grained control over inflation and validation.

You can also create a simple subroutine in your form class to perform validation.
The default name of this subroutine is 'validate_<fieldname>', but the name can
also be set in the field with the 'set_validate' attribute.
Expand All @@ -500,7 +520,9 @@ either method.
=head2 Creating custom fields

Subclass a custom field from L<HTML::FormHandler::Field>, or one of the
existing subclasses.
existing subclasses. Almost everything that is done in a custom field
class can also be done declaratively. The advantage of a field class
is that it can simplify declaration of often-repeated sets of attributes.

The simplest subclasses contain only a 'validate' routine or an 'apply' attribute,
which is called by the base Field class from 'process'. Look at
Expand All @@ -518,13 +540,6 @@ L<HTML::FormHandler::Field::IntRange>. A field may add additional
attributes, such as 'label_format' in L<HTML::FormHandler::Field::IntRange>,
or set the 'required_message'.

Some fields subclass 'input_to_value' to change the way that the form
input is converted to the value, in addition to providing 'fif_value'
to convert the other way.

The DateTime field even subclasses 'process' in order to skip
the other standard validations.

An alternative to new field classes for many field validations might
be roles with collections of validations.

Expand Down

0 comments on commit 422ac8b

Please sign in to comment.