adjust docs to reflect danger in using restricting object to provide restricted resul...

diff --git a/lib/DBIx/Class/Schema/RestrictWithObject.pm b/lib/DBIx/Class/Schema/RestrictWithObject.pm
index 05f3477..45575ca 100644 (file)
--- a/lib/DBIx/Class/Schema/RestrictWithObject.pm
+++ b/lib/DBIx/Class/Schema/RestrictWithObject.pm
@@ -20,21 +20,13 @@ In your L<DBIx::Class::Schema> class:
 
 In the L<DBIx::Class> table class for your users:
 
-    #let's pretend a user has_many notes, which are in ResultSet 'Notes'
+    # our Users "has_many" Notes
     sub restrict_Notes_resultset {
       my $self = shift; #the User object
       my $unrestricted_rs = shift;
 
-      #restrict the notes viewable to only those that belong to this user
-      #this will, in effect make the following 2 equivalent
-      # $user->notes $schema->resultset('Notes')
-      return $self->related_resultset('notes');
-    }
-
-     #it could also be written like this
-    sub restrict_Notes_resultset {
-      my $self = shift; #the User object
-      my $unrestricted_rs = shift;
+      # avoid the tempatation to return $self->related_resultset('Notes')
+      # it will only cause you trouble later
       return $unrestricted_rs->search_rs( { user_id => $self->id } );
     }
 
@@ -42,7 +34,10 @@ Wherever you connect to your database
 
     my $schema = MyApp::Schema->connect(...);
     my $user = $schema->resultset('User')->find( { id => $user_id } );
-    $resticted_schema = $schema->restrict_with_object( $user, $optional_prefix);
+    my $restricted_schema = $schema->restrict_with_object( $user, $optional_prefix);
+
+    # $notes will be pre-filtered by the restrict_Notes_resultset method
+    my $notes = $restricted_schema->resultset('Notes');
 
 In this example we used the User object as the restricting object, but please
 note that the restricting object need not be a DBIC class, it can be any kind of