General documentation improvements

 - reorganized the POD to try to put it in a more readable order
 - added part about configuring fields from DBIC ResultSource objects
 - added a Contributors section

lib/Form/Sensible/Reflector/DBIC.pm

@@ -9,6 +9,88 @@ use Data::Dumper;
 
 # ABSTRACT: A Form::Sensible::Reflector subclass to reflect off of DBIC schema classes
 
+=head1 NAME 
+ 
+Form::Sensible::Reflector::DBIC - A reflector class based on Form::Sensible and Form::Sensible::Reflector
+
+=cut
+
+=head1 SYNOPSIS
+
+	my $schema = TestSchema->connect('dbi:SQLite::memory:');
+	$schema->deploy;
+	use Form::Sensible;
+	use Form::Sensible::Reflector::DBIC;
+	## name must reflect the table which we are reflecting
+
+	my $dt = DateTime->now;
+
+	my $reflector = Form::Sensible::Reflector::DBIC->new();
+	my $form      = $reflector->reflect_from(
+	    $schema->resultset("Test"),
+	    {
+	        form   => { name => 'test' },
+	         with_trigger => 1
+	    }
+	);
+	my $renderer = Form::Sensible->get_renderer('HTML');
+
+	$form->set_values( { date => $dt } );
+	my $output = $renderer->render($form)->complete;
+
+
+=head1 CONFIGURATION OF FIELDS
+
+Form::Sensible::Reflector::DBIC was designed with the intention that as much
+configuration as possible can be done in the definition of the
+DBIx::Class::ResultSource objects. While the ResultSource definition is used
+to programatically generate as much of the Form::Sensible::Field definitions
+as possible, it is possible to add to the Field generated. This is done with 
+several items that can be added to the columinfo hash in the call to add_columns():
+
+=over 4
+
+=item validation
+
+The validation hashref is used just as the validation hashref atribute in L<Form::Sensible::Field>.
+It is typically used by L<Form::Sensible::Validator> in order
+to create validation rules for form input values. As specified by
+Form::Sensible::Validator, it can contain keys C<required>, C<code>, and C<regex>.
+
+=item render_hints
+
+The render_hints hashref also gets passed to L<Form::Sensible::Field> as the
+render_hints attribute to the C<create_from_flattened> constructor.
+
+=item fs_definition
+
+The C<fs_definition> hashref can be used to completely override the intelligence
+ordinarily used to generate the Form::Sensible::Field definition. If this hashref
+is present, each key in it is used to completely overwrite the key in the
+Form::Sensible::Field definition. Any of the attributes accepted by
+Form::Sensible::Field are acceptable here. Note that one could alternatively
+specify C<validation> and C<render_hints> options here.
+
+=back
+
+For example:
+
+    __PACKAGE__->add_columns(
+        'id',
+        {
+            data_type         => 'integer',
+            is_auto_increment => 1,
+            is_nullable       => 0
+        },
+        'phone_number',
+        {
+            data_type  => 'varchar',
+            validation => { regex => qr/[-\d]+/ }, # passed to Form::Sensible::Field
+        }
+    );
+    __PACKAGE__->set_primary_key('id');  # Defaults to hidden in the form
+
+=head1 INTERNAL METHODS
 
 =head2 $self->field_type_map 
 
@@ -72,7 +154,6 @@ Default options for L<Form::Sensible> field classes.
 
 =cut
 
-
 ## this should also be in a role
 has 'field_class_options' => (
     is       => 'rw',
@@ -122,7 +203,6 @@ has 'field_class_options' => (
     }
 );
 
-
 =head2 $self->get_base_definition($name, $datatype)
 
 This gets field definitions for a given datatype and returns them in hashref form.
@@ -149,10 +229,10 @@ sub get_base_definition {
         }
     }
 
-    # this loops over the attribute map and brings over any attributes that can be directly
-    # applied.  This is useful for things like 'size' where the columninfo itself will tell you
-    # maximum length, etc.  It's also used to find any override parameters provided by the user in the validation
-    # or render_hints keys in the column info.
+# this loops over the attribute map and brings over any attributes that can be directly
+# applied.  This is useful for things like 'size' where the columninfo itself will tell you
+# maximum length, etc.  It's also used to find any override parameters provided by the user in the validation
+# or render_hints keys in the column info.
     my $attribute_map =
       $self->field_class_options->{ $definition->{'field_class'} } || {};
     if ( exists( $field_type_map->{'attribute_map'} ) ) {
@@ -197,7 +277,7 @@ sub get_base_definition {
     return $definition;
 }
 
-=head1 $self->get_fieldnames()
+=head2 $self->get_fieldnames()
 
 Get field names for the form, for example, the column names in the table.
 
@@ -208,18 +288,18 @@ sub get_fieldnames {
     return $self->result_source_for($handle)->columns;
 }
 
-=head1 $self->get_field_definition()
+=head2 $self->get_field_definition()
 
 Get a given field's definition.
 
 =cut
 
 sub get_field_definition {
     my ( $self, $form, $handle, $name ) = @_;
-    ## TODO: 
+    ## TODO:
     ## 1. Follow relationships
     ## 2. Options for primary key rendering other than "hidden"
-    
+
     ## check to see if it's a primary key
     my $result_source = $self->result_source_for($handle);
     my @pks           = $result_source->primary_columns;
@@ -309,34 +389,16 @@ sub result_source_for {
 __PACKAGE__->meta->make_immutable;
 1;
 
-=head1 NAME 
- 
-Form::Sensible::Reflector::DBIC - A reflector class based on Form::Sensible and Form::Sensible::Reflector
+=head1 CONTRIBUTORS
 
-=cut
+=over 4
 
-=head1 SYNOPSIS
+=item Devin Austin <devin.austin@gmail.com>
 
-	my $schema = TestSchema->connect('dbi:SQLite::memory:');
-	$schema->deploy;
-	use Form::Sensible;
-	use Form::Sensible::Reflector::DBIC;
-	## name must reflect the table which we are reflecting
+=item Jay Kuri <jayk@cpan.org>
 
-	my $dt = DateTime->now;
+=item Andrew Moore <amoore@cpan.org>
 
-	my $reflector = Form::Sensible::Reflector::DBIC->new();
-	my $form      = $reflector->reflect_from(
-	    $schema->resultset("Test"),
-	    {
-	        form   => { name => 'test' },
-	         with_trigger => 1
-	    }
-	);
-	my $renderer = Form::Sensible->get_renderer('HTML');
+=back
 
-	$form->set_values( { date => $dt } );
-	my $output = $renderer->render($form)->complete;
-
-=cut