Skip to content
Browse files

Updated POD, documented writing Plugins, added instantiation hook for…

… Plugins
  • Loading branch information...
1 parent 4eb2934 commit ccf98d07c2bb7acb8472380cfe3ce6d86475a9a7 Al Newkirk committed Oct 30, 2011
Showing with 115 additions and 0 deletions.
  1. +4 −0 CHANGES
  2. +110 −0 lib/Validation/Class/Plugins.pod
  3. +1 −0 lib/Validation/Class/Validator.pm
View
4 CHANGES
@@ -1,5 +1,9 @@
This file documents the revision history for the Perl library Validation::Class.
+2.4.4 2011-10-28
+ - Updated POD, documented writing Plugins
+ - Added instatiation hook for plugins
+
2.4.3 2011-10-28
- Refactored the plugin system
View
110 lib/Validation/Class/Plugins.pod
@@ -0,0 +1,110 @@
+=head1 NAME
+
+Validation::Class::Plugins - Basic Instructions for Writing Plugins
+
+=head1 DESCRIPTION
+
+This documentation serves as a brief overview on writing plugins for
+Validation::Class. Here are the key points:
+
+L<Validation::Class> is written with L<Moose> and a plugin must be designed
+as a L<Moose::Role>. As a role the plugins attributes and methods are imported
+into the calling class and because of this it is important to name your
+attributes and methods cautiously as to not overwrite another plugins
+functionality.
+
+When creating B<official> Validation::Class plugins you should use the namespace
+Validation::Class::Plugin::YourPluginName. This will allow users of your plugin
+to simply pass YourPluginName to the load_plugins() method. The following is an
+example of including a plugin.
+
+ package MyApp::Validation;
+
+ use Validation::Class;
+
+ __PACKAGE__->load_plugins('YourPluginName');
+
+ # a validation rule
+ field 'login' => {
+ label => 'User Login',
+ error => 'Login invalid.',
+ required => 1,
+ validation => sub {
+ my ($self, $this_field, $all_params) = @_;
+ return $this_field->{value} eq 'admin' ? 1 : 0;
+ }
+ };
+
+ # a validation rule
+ field 'password' => {
+ label => 'User Password',
+ error => 'Password invalid.',
+ required => 1,
+ validation => sub {
+ my ($self, $this_field, $all_params) = @_;
+ return $this_field->{value} eq 'pass' ? 1 : 0;
+ }
+ };
+
+ 1;
+
+Once your plugin is loaded at runtime and can manipulate the L<Validation::Class>
+object by declaring a B<new> method. The following is an example of a ficticious
+plugin for formatting telephone numbers:
+
+ package Validation::Class::Plugin::TelephoneFormatting;
+
+ use Moose::Role;
+
+ # hook into the instantiation process
+ # of the calling class at runtime
+ sub new {
+ my ($class, $self) = @_;
+
+ # US Telephones
+ $self->filters->{telephone_usa} = sub {
+ my $phone = shift;
+ $phone =~ s/\D//g;
+
+ my ($area, $prefix, $xchng) = $phone =~ m/1?(\d{3})(\d{3})(\d{4});
+
+ return "+1 ($area) $prefix-$xchng";
+ };
+
+ }
+
+Once we create, test and deploy our plugin, we can use it in our code as follows:
+
+ package MyApp::Validation;
+
+ use Validation::Class;
+
+ __PACKAGE__->load_plugins('TelephoneFormatting');
+
+ # a validation rule
+ field 'phone' => {
+ label => 'Telephone Number',
+ error => 'Phone number invalid.',
+ required => 1,
+ filters => 'telephone_usa',
+ pattern => '+1 (###) ###-####'
+ };
+
+ package main ;
+
+ my $rules = MyApp::Validation;
+
+ # ...
+
+=head1 AUTHOR
+
+Al Newkirk <awncorp@cpan.org>
+
+=head1 COPYRIGHT AND LICENSE
+
+This software is copyright (c) 2011 by awncorp.
+
+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
View
1 lib/Validation/Class/Validator.pm
@@ -190,6 +190,7 @@ sub BUILD {
# attach plugins
foreach my $plugin (keys %{$self->plugins}) {
+ $plugin->new($self) if $plugin->meta->has_method('new'); # init hook
$plugin->meta->apply($self);
}

0 comments on commit ccf98d0

Please sign in to comment.
Something went wrong with that request. Please try again.