view release on metacpan or  search on metacpan

lib/Data/MuFormX/Registry.pm  view on Meta::CPAN

Data::MuFormX::Registry - Registry of Form classes

=head1 SYNOPSIS

Given some L<Data::MuForms> in a common namespace:

    package MyApp::Form::Login;

    use Moo;
    use Data::MuForm::Meta;

    extends 'Data::MuForm';

    has_field 'username' => (
      type => 'Text',
      required => 1 );

    package MyApp::Form::Email;

    use Moo;
    use Data::MuForm::Meta;

    extends 'Data::MuForm';

    has_field 'username' => (
      type => 'Text',
      required => 1 );

Create a 'registry' object that will load a prepare all the forms:

    my $registry = Data::MuFormX::Registry->new(form_namespace=>'MyApp::Form');
    my $login = $registry->create('Login'); # $login ISA MyApp::Form::Login

You may also subclass for hardcoded defaults

    package MyApp::MyRegistry;

    use Moo;
    extends 'Data::MuFormX::Registry';

    1;

    # 'form_namespace defaults to 'MyApp::Form'
    my $registry = MyApp::MyRegistry->new;

=head1 DESCRIPTION

B<NOTE> Early access; the docs do not describe all existing features (read
the source :) ) and I reserve the right to break stuff if that's the only way
to fix deep problems.  On the other hand there's not a ton of stuff here so
its probably ok...

This is a wrapper on top of L<Module::Pluggable::Object> to make it easier
to load up and create a namespace of L<Data::MuForm> based form validation
classes.  At its heart it makes it so you don't have to say 'use Form;' for
every form you need in a package.  It also adds a way to centralize some
form initialization work.  This may or may not recommend itself to you.  I
think it makes it easier to reuse forms in different packages (for example in
different L<Mojolicous> controllers).  On the other hand it injects a proxy
layer such that '$registry->create("Login")' is not 100% transparent in that
you are getting an instance of 'MyApp::Form::Login'.  You may consider this
a type of action at a distance that makes your code harder to maintain.

If you have a lot of L<Data::MuForm> based form validation classes you may find
it more useful.  I also believe it helps you follow the 'code against an interface
not an class' best practice.  As you wish ;)

=head1 METHOD

This class exposes the follow methods for intended public use.

=head2 new

Create a new registry object.  You can set the following initial arguments:

=over 4

=item form_namespace

Either a scalar or array ref of the base namespaces used to find forms.

=item config

configuration values used when creating form objects.

=back

=head2 create

Create a new form.  Requires a form name.  May accept a hash of additional initialization
values (which are merged with any global configuration.  Examples:

    my $transaction = $registry->create('Transaction');
    my $login = $registry->create('Login', user_rs=>$users);

If you do not need to pass any extra arguments we  reuse a pre-initialized copy of
the form rather than build a new one as a performance enhancement.

=head2 form_names

Returns an array of the form names, which can be used in L</create>.  Do not
rely on return order!

=head2 config

Global configuration information for all forms.

Intended to be overridden in a subclass to provide form defaults.  For example:

    package MyRegistry;

    use Moo;
    extends 'Data::MuFormX::Registry';

    sub config {
      'Login' => + {
        min_username_length => 11,
      },
      'NewNodes' => sub {
        my ($self) = @_;