improve documentation and tests to demonstrate reflect_from on a row …

…object

the reflect_from() method can take a DBIx::Class row object instead of a
resultsource. This patch adds a touch of documentation to make that obvious.
It also adds some tests to the test suite to enforce it.

There is an optional dependency added on Test::Differences. If Test::Differences
is present, the output from comparing the HTML is a little easier to follow
if it fails.

TODO

@@ -1,5 +1,5 @@
 TODO:
-Add Reflecting from row objects in addition to ResultSet (default values?)
+Populate default values if reflecting from a Row object instead of a ResultSet
 provide for field omitting - via should_process_field_delegate
 add relationship following - on simple relationships
 docs

lib/Form/Sensible/Reflector/DBIC.pm

@@ -38,6 +38,24 @@ Form::Sensible::Reflector::DBIC - A reflector class based on Form::Sensible and
 	$form->set_values( { date => $dt } );
 	my $output = $renderer->render($form)->complete;
 
+=head1 DESCRIPTION
+
+Form::Sensible::DBIC::Reflector allows you to create Form::Sensible forms from
+DBIx::Class objects.
+
+=head1 METHODS
+
+=head2 reflect_from
+
+    my $generated_form = $reflector->reflect_from($data_source, $options);
+
+The $data_source parameter can be a DBIx::Class resultsource such as
+$schema->resultset('Table'), or a DBIx::Class::Row object such as
+$schema->resultset('Table')->find( 1 );
+
+Since the reflect_from method is actually provided by Form::Sensible itself,
+please see the Form::Sensible::Reflector documentation for more information
+on the reflect_from method.
 
 =head1 CONFIGURATION OF FIELDS
 

t/01test_reflector.t

@@ -16,6 +16,13 @@ $schema->deploy;
 use Form::Sensible;
 use Form::Sensible::Reflector::DBIC;
 use Data::Dumper;
+
+# Try to use Test::Differences if possible
+BEGIN {
+    if ( !eval q{ use Test::Differences; unified_diff; 1 } ) {
+        *eq_or_diff = \&is_deeply;
+    }
+}
 my $dt = DateTime->now;
 
 # reflector WITH a submit button;
@@ -85,7 +92,6 @@ my $form2 = Form::Sensible->create_form(
           required => 1,
         },
       },
-
       {
         field_class => 'Text',
         name        => 'password',
@@ -103,13 +109,14 @@ my $form2 = Form::Sensible->create_form(
 );
 
 my $good_values = {
-  username   => "dhoss",
-  date       => "2008-09-01 12:35:45",
-  big_text   => "asdflkjawofij24fj2i3f4j 2903 dfnqe2fw f",
-  number     => 123,
-  decimal    => 12.34,
-  big_number => 1243567,
-  password   => "mMMmm123",
+  username    => "dhoss",
+  file_upload => 'these are the contents of a file',
+  date        => "2008-09-01 12:35:45",
+  big_text    => "asdflkjawofij24fj2i3f4j 2903 dfnqe2fw f",
+  number      => 123,
+  decimal     => 12.34,
+  big_number  => 1243567,
+  password    => "mMMmm123",
 };
 
 my $bad_values = {
@@ -122,31 +129,44 @@ my $bad_values = {
   password   => "a",
 };
 
+my $row = $schema->resultset('Test')->create($good_values);
+isa_ok( $row, 'TestSchema::Result::Test' );
+
+my $form_from_row = $reflector->reflect_from( $row, { form => { name => 'test' }, with_trigger => 1 } );
+
 $form->set_values($good_values);
 $form2->set_values($good_values);
+$form_from_row->set_values($good_values);
 my $v1 = $form->validate;
 my $v2 = $form2->validate;
+my $v3 = $form_from_row->validate;
 TODO: {
-  local $TODO = "These need fixing";
-  ok( $v1->is_valid, "form 1 valid" );
-  ok( $v2->is_valid, "form 2 valid" );
-  $form->set_values($bad_values);
-  $form2->set_values($bad_values);
-  my $bv1 = $form->validate;
-  my $bv2 = $form2->validate;
+    local $TODO = "These need fixing";
+    ok( $v1->is_valid, "form 1 valid" );
+    ok( $v2->is_valid, "form 2 valid" );
+    ok( $v3->is_valid, "form from row is valid" );
+    $form->set_values($bad_values);
+    $form2->set_values($bad_values);
+    $form_from_row->set_values($bad_values);
+    my $bv1 = $form->validate;
+    my $bv2 = $form2->validate;
+    my $bv3 = $form_from_row->validate;
 
-  ok( !$bv1->is_valid, "form 1 invalid" );
-  ok( !$bv2->is_valid, "form 2 invalid" );
-  $form->set_values($good_values);
-  $form2->set_values($good_values);
+    ok( !$bv1->is_valid, "form 1 invalid" );
+    ok( !$bv2->is_valid, "form 2 invalid" );
+    ok( !$bv3->is_valid, "form from row invalid" );
+    $form->set_values($good_values);
+    $form2->set_values($good_values);
+    $form_from_row->set_values($good_values);
 }
 my $renderer2 = Form::Sensible->get_renderer('HTML');
 my $output    = $renderer->render($form)->complete;
 my $output_2  = $renderer2->render($form2)->complete;
-is_deeply( $form->flatten, $form2->flatten,
-  "form one hash matches form two hash" );
+my $output_3  = $renderer2->render($form_from_row)->complete;
+is_deeply( $form->flatten, $form2->flatten, "form one hash matches form two hash" );
+is_deeply( $form_from_row->flatten, $form->flatten, "flattened form from row matches flattened original form" );
 
-cmp_ok( $output, 'eq', $output_2, "Flat eq to pulled from DBIC" );
-cmp_ok( $output, 'eq', $output_2, "Flat eq to pulled from DBIC" );
+eq_or_diff( $output, $output_2, "Output from flat eq to pulled from DBIC" );
+eq_or_diff( $output_2, $output_3, "Output from flat eq to output from form from row" );
 
 done_testing;