required, required_when¶

Setting the 'required' flag on a field initiates a check for the existence of some value. If the field does not have a value, the 'required' error message is issued.

   has_field 'section' => ( required => 1,
       messages => { required => 'Please provide a section' } );

Note that a required flag on a subfield -- a field inside a compound field or repeatable field -- does not cause the containing field to be required. You need to set 'required' all the way up, if that's the behavior that you want.

If a field is empty and *not* required, no other field validation will be performed unless the 'validate_when_empty' flag (see below) is set. The form's 'validate' method, however, will always be called.

There is also the 'required_when' attribute, which works the same way as the 'when' key on the apply actions.

    has_field 'fee' => ( required_when => { 'fie' => 2 } );

When a 'required' or 'required_when' check fails, a 'missing' flag is set in the result:

    if ( $field->missing ) { ... }

range_start, range_end¶

Starting and ending range for number fields.

unique¶

Attribute used by the DBIC model to check for uniqueness.

validate_when_empty¶

If its 'validate_when_empty' flag is set to a true value, then a field will always undergo validation when its form is processed, even when that field is empty.

validate_method¶

You can provide a validation method for a field by setting a coderef with 'validate_method'.

    has_field 'fox' => ( validate_method => \&check_fox );
    sub check_fox {
        my $self = shift; # self is the fox field
        unless( $self->value eq .... ) {
            $self->add_error('....');
        }
    }

validate_<field_name>¶

If you provide a 'validate_<field_name>' method it will be automatically used.

    has_field 'cat';
    sub validate_cat {
        my ( $self, $field ) = @_; # self is the form
        unless ( $field->value eq  ... ) {
            $field->add_error( '...' );
        }
    }

If the field name has periods in it, they should be replaced with underscores.

form validate method¶

A form validation method can be used to do cross-validation or validation checks that need information from more than one field.

    sub validate {
        my $self = shift;
        $self->field('foo')->add_error('....')
            if( $self->field('foo')->value eq '..' &&
                    $self->field('bar')->value eq '..' );
    }

field validate method¶

You can create a custom field to contain a commonly used validation. The validation in a custom field can be done with 'apply' or by using a 'validate' method.

    package MyApp::Form::Field::Custom;
    use HTML::FormHandler::Moose;
    extends 'HTML::FormHandler::Field'; # or a subclass of Field
    sub validate {
        ....
    }

Moose types¶

Moose types can be used to do both constraints and transformations. If a coercion exists it will be applied, resulting in a transformation. After coercing, the result is checked. You can use type constraints from MooseX::Types libraries or defined using Moose::Util::TypeConstraints.

FormHandler supplies a library of Moose types in HTML::FormHandler::Types.

    use HTML::FormHandler::Types ('NotAllDigits');
    has_field 'foo' => ( apply => [ NotAllDigits ] );

You can create your own library of types, too. Or you can create a type constraint in the form:

  use Moose::Util::TypeConstraints;
  subtype 'GreaterThan10'
     => as 'Int'
     => where { $_ > 10 }
     => message { "This number ($_) is not greater than 10" };
  has_field 'text_gt' => ( apply=> [ 'GreaterThan10' ] );

Moose types can also be used for their coercions to do transformations.

  subtype 'MyInt'
      => as 'Int';
  coerce 'MyInt'
      => from 'MyStr'
      => via { return $1 if /(\d+)/ };

You can also use the 'type' keyword with a Moose type if you want to change the message:

    has_field 'text_gt' => ( apply => [
        { type => 'GreaterThan10',
          message => 'Number is too small' } ] );

transform¶

A 'transform' changes the format of a field's value, and does not need a message. It takes a coderef.

   has_field 'another_field' => (
      apply => [ { transform => sub{ sprintf '<%.1g>', $_[0] } } ]
   );

Note that transformed values are not displayed in the HTML form unless the 'fif_from_value' flag is set. The transformed values are saved to the database or returned in "$form->value".

'check' regex¶

Checks that field value matches the regex.

   has_field 'some_field' => (
      apply => [ { check => qr/aaa/, message => 'Must contain aaa' } ],
   );

You can use regex libraries like Regexp::Common too:

    use Regexp::Common ('URI');
    ...
    has_field 'my_url' => ( apply => [
        { check => qr/$RE{URI}{HTTP}/,
           message => 'Invalid URL' } ] );

'check' arrayref (matches)¶

Provide an arrayref of strings to match against.

   has_field 'set_error' => (
      apply => [
         { check   => [ 'abc', 'bbb' ],
            message => 'Must be "aaa" or "bbb"' }
      ]
   );

'check' coderef¶

Provide a validation function to check. A 'check' coderef will be passed the current value of the field and should return true or false. Note that the field is passed in as the second argument, to allow simple functions to work properly.

   has_field 'callback_pass' => (
      apply => [
         { check => \&check_callback_pass,
             message => 'Must contain number greater than 10', }
       ]
   );
   sub check_callback_pass {
       my ( $value, $field ) = @_;
       if( $value =~ /(\d+)/ ) {
           return $1 > 10;
       }
   }

message¶

The message for the above checks can also be an arrayref or coderef. The arrayref is useful for localized messages. You can also provide error messages for Moose types.

   has_field 'message_sub' => (
      apply => [
         { check   => [ 'abc' ],
            message => \&err_message }
      ]
   );
   sub err_message {
       my ($value, $field ) = @_;
       return $field->name . ': Must be "abc"';
   }
   has_field 'message_arrayref' => (
      apply => [ { check => qr/aaa/,
          message => ['Must contain [_1]', 'aaa'] } ],
   );
   has_field 'my_moose_type_field' => (
      apply => [ { type => SomeType,
         message => 'Invalid ...' } ] );

actions in a field class¶

To declare actions inside a field class use HTML::FormHandler::Moose and 'apply' sugar:

   package MyApp::Field::Test;
   use HTML::FormHandler::Moose;
   extends 'HTML::FormHandler::Field;
   apply [ 'SomeConstraint', { check => ..., message => .... } ];
   1;

Actions specified with apply are cumulative. Actions may be specified in field classes and additional actions added in the 'has_field' declaration.

You can see examples of field classes with 'apply' actions in the source for HTML::FormHandler::Field::Money and HTML::FormHandler::Field::Email, and in t/constraints.t.