package Data::MuForm::Manual::Errors;
# ABSTRACT: MuForm error methods

__END__

=pod

=encoding UTF-8

=head1 NAME

Data::MuForm::Manual::Errors - MuForm error methods

=head1 VERSION

version 0.05

=head1 SYNOPSIS

L<Manual Index|Data::MuForm::Manual>

Errors and error messages for L<Data::MuForm>.

=head1 DESCRIPTION

Errors are added to field or form objects by the field 'add_error' method
or the form 'add_form_error' method. MuForm will perform the 'add_error'
for you for built-in validation or 'apply' actions. When performing your
own validation in a validation method, you must do the 'add_error'
yourself.

Errors, along with 'input' and 'value' attributes, are collected in the
'error_fields' and 'errors' arrays in fields that contain other fields and
in the form.

The existence (or not) of errors determines whether or not the form has
been 'validated'.

=head1 Form methods

=over 4

=item errors, all_errors

Returns an arrayref of localized error strings (both field and
form errors):

    my $errors = $form->errors;
    my @errors = $form->all_errors;

=item has_errors

Both 'form' errors and errors from the tree of subfields

    if( $form->has_errors ) {
        <do something>
    }

=item form_errors, all_form_errors

Returns an arrayref / array of error strings on the form (not including
field errors).

    foreach my $err ( $self->all_form_errors ) {
        $output .= "<span class="error">$err</span>";
    }

=item has_form_errors

Does the form have form_errors?

=item add_form_error

Add an error to the form which is not associated with a specific field.

    sub validate {
        my $self = shift;
        unless( <some condition> ) {
            $self->add_form_error('....');
        }
    }

=item push_form_error

Add a non-localized error to the form.

=back

=head1 Field methods

The most common error method is probably 'add_error', which you
use in the validation process.

    sub validate_foo {
        my ( $self, $field ) = @_;
        unless ( <some_condition> ) {
            $field->add_error('Error condition');
        }
    }

=over 4

=item errors

Returns an array of error strings.

=item has_errors

Does the field have errors? Note that a compound field that contains subfields
with errors will not return true for this method. If you want to know if there
are errors in the subfields, do 'has_error_fields'.

=item num_errors

=item add_error

Add an error to the field. Localization is performed.

=item push_error

Add an error without localization.

=item error_fields

In a compound field (and its subclasses, like 'Repeatable'), the list
of fields with errors.

=back

=head1 Messages

The base field class and the field subclasses have some 'built-in' error messages.
These can be modified by setting the 'messages' hashref in the form or the
individual fields, or with the shortcut 'msg.<message name' key in a field definition.

When a message is retrieved in a field with C<< $field->get_message('upload_file_') >>
for example, the 'get_message' method will look first in user-set field specific messages,
then in user-supplied form messages, finally in messages provided by the field classes.

   package MyApp::Form;
   use Moo;
   use Data::MuForm::Meta;
   extends 'Data::MuForm';

   sub build_messages {
       return { required => '....', my_message => '....' };
   }
   has_field 'my_field' => ( 'msg.required => 'Please provide a my_field',
       required => 1 );

=head1 AUTHOR

Gerda Shank

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2018 by Gerda Shank.

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
