Kent Fredric

NAME

Spark::Form - A simple yet powerful forms validation system that promotes reuse.

VERSION

version 0.2102

SYNOPSIS

 use Spark::Form;
 use CGI; #Because it makes for a quick and oversimplistic example
 use Third::Party::Field;
 $form = Spark::Form->new(plugin_ns => 'MyApp::Field');
 # Add a couple of inbuilt modules
 $form->add('email','email',confirm_field => 'email-confirm')
      ->add('email','email-confirm')
      ->add('password','password',regex => qr/^\S{6,}$/),
      #This one will be autoloaded from MyApp::Field::Username
      ->add('username','username')
      # And this shows how you can use a third party field of any class name
      ->add(Third::Party::Field->new(name => 'blah'));
 #Pass in a HashRef of params to populate the virtual form with data
 $form->data(CGI->new->params);
 #And do the actual validation
 if ($form->validate) {
     print "You are now registered";
 } else {
     print join "\n", $form->errors;
 }

and over in MyApp/Field/Username.pm...

 package MyApp::Form::Field::Username;
 use base Spark::Form::Field;

 sub _validate {

   my ($self,$v) = @_;

   if (length $v < 6 or length $v > 12) {
     $self->error("Usernames must be 6-12 characters long");
   } elsif ($v =~ /[^a-zA-Z0-9_-]/) {
     $self->error("Usernames may contain only a-z,A-Z,0-9, _ and -");
   } else {
     $self->error(undef);
   }
   $self->valid(!!$self->error());
 }

INSTABILITY

Periodically the API may break. I'll try to make sure it's obvious so it doesn't silently malfunction.

By 0.5, we shouldn't have to do this.

DEPENDENCIES

Moose. I've dropped using Any::Moose. If you need the performance increase, perhaps it's time to start thinking about shifting off CGI.

METHODS

import (%options)

Allows you to set some options for the forms class.

class => String

Optional, gives the basename for searching for form plugins.

Given 'MyApp', it will try to load form plugins from MyApp::Form::Field::*

source => String

Optional, names a plugin to try and extract form data from.

If unspecified, you will need to call $form->data(\%data);

add ($thing,@rest)

If $thing is a string, attempts to instantiate a plugin of that type and add it to the form. Requires the second argument to be a string name for the field to identify it in the form. Rest will become %kwargs If it is an ArrayRef, it loops over the contents (Useful for custom fields, will probably result in bugs for string field names).@rest will be passed in each iteration. If it looks sufficiently like a field (implements Spark::Form::Field), then it will add it to the list of fields. @rest will just become %kwargs

Uses 'field name' to locate it from the data passed in.

This is a streaming interface, it returns the form itself.

validate

Validates the form. Sets valid and then also returns the value.

data

Allows you to pass in a HashRef of data to populate the fields with before validation. Useful if you don't use a plugin to automatically populate the data.

This is a streaming interface, it returns the form itself.

fields () => Fields

Returns a list of Fields in the form in their current order

BUILD

Moose constructor. Test::Pod::Coverage made me do it. Adds class to the search path for field modules.

get (Str)

Returns the form field of that name

get_at (Int)

Returns the form field at that index (counting from 0)

keys () :: Array

Returns the field names

field_couplet () :: Data::Couplet

Returns the Data::Couplet used to store the fields. Try not to use this too much.

remove (Array[Str]) :: Spark::Form

Removes the field(s) bearing the given name(s) from the form object. Silently no-ops any that do not exist.

remove_at (Array[Int]) :: Spark::Form

Removes the field at the given ID(s) from the form object. Silently no-ops any that do not exist.

WARNING: Things will get re-ordered when you do this. If you have a form with IDs 0..3 and you remove (1, 3), then (0, 2) will remain but they will now be (0, 1) as Data::Couplet will move them to keep a consistent array.

clone_all () :: Spark::Form

Returns a new copy of the form with freshly instantiated fields.

clone_except_names (Array[Str]) :: Spark::Form

Clones, removing the fields with the specified names.

clone_only_names (Array[Str]) :: Spark::Form

Clones, removing the fields without the specified names.

clone_except_ids (Array[Int]) :: Spark::Form

Clones, removing the fields with the specified IDs.

clone_only_ids (Array[Int]) :: Spark::Form

Clones, removing the fields without the specified IDs.

clone_if (SubRef[(Int, Str, Any) -> Bool]) :: Spark::Form

Clones, removing items for which the sub returns false. Sub is passed (Id, Key, Value).

clone_unless (SubRef[(Int, Str, Any) -> Bool]) :: Spark::Form

Clones, removing items for which the sub returns true. Sub is passed (Id, Key, Value).

compose (Spark::Form) :: Spark::Form

Clones the current form object and copies fields from the supplied other form to the end of that form. Where names clash, items on the current form take priority.

Docs?

http://sparkengine.org/docs/forms/

Source?

http://github.com/jjl/Spark-Form/

THANKS

Thanks to the Django Project, whose forms module gave some inspiration.

SEE ALSO

The FAQ: Spark::Form::FAQ Data::Couplet used to hold the fields (see field_couplet)

AUTHOR

  James Laver L<http://jameslaver.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2009 by James Laver <sprintf qw(%s@%s.%s cpan jameslaver com)>.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.




Hosting generously
sponsored by Bytemark