X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FDBIx%2FClass%2FOrdered.pm;h=737477df15402c146d9d01883679579256cb3852;hb=79a77af646d55bab4840d883527d4f73c9426427;hp=b6ad5dc49622fc2b2b5f4c5be0d1005fa7fecbd3;hpb=fa6b598f79a96c8ff0a75c1bb8460f27790b4fc3;p=dbsrgits%2FDBIx-Class.git

diff --git a/lib/DBIx/Class/Ordered.pm b/lib/DBIx/Class/Ordered.pm
index b6ad5dc..737477d 100644
--- a/lib/DBIx/Class/Ordered.pm
+++ b/lib/DBIx/Class/Ordered.pm
@@ -17,9 +17,28 @@ Create a table for your ordered data.
     name TEXT NOT NULL,
     position INTEGER NOT NULL
   );
-  # Optional: group_id INTEGER NOT NULL
 
-In your Schema or DB class add Ordered to the top 
+Optionally, add one or more columns to specify groupings, allowing you 
+to maintain independent ordered lists within one table:
+
+  CREATE TABLE items (
+    item_id INTEGER PRIMARY KEY AUTOINCREMENT,
+    name TEXT NOT NULL,
+    position INTEGER NOT NULL,
+    group_id INTEGER NOT NULL
+  );
+
+Or even
+
+  CREATE TABLE items (
+    item_id INTEGER PRIMARY KEY AUTOINCREMENT,
+    name TEXT NOT NULL,
+    position INTEGER NOT NULL,
+    group_id INTEGER NOT NULL,
+    other_group_id INTEGER NOT NULL
+  );
+
+In your Schema or DB class add "Ordered" to the top 
 of the component list.
 
   __PACKAGE__->load_components(qw( Ordered ... ));
@@ -29,9 +48,16 @@ each row.
 
   package My::Item;
   __PACKAGE__->position_column('position');
-  __PACKAGE__->grouping_column('group_id'); # optional
 
-Thats it, now you can change the position of your objects.
+If you are using one grouping column, specify it as follows:
+
+  __PACKAGE__->grouping_column('group_id');
+
+Or if you have multiple grouping columns:
+
+  __PACKAGE__->grouping_column(['group_id', 'other_group_id']);
+
+That's it, now you can change the position of your objects.
 
   #!/use/bin/perl
   use My::Item;
@@ -54,6 +80,10 @@ Thats it, now you can change the position of your objects.
   $item->move_first();
   $item->move_last();
   $item->move_to( $position );
+  $item->move_to_group( 'groupname' );
+  $item->move_to_group( 'groupname', $position );
+  $item->move_to_group( {group_id=>'groupname', 'other_group_id=>'othergroupname'} );
+  $item->move_to_group( {group_id=>'groupname', 'other_group_id=>'othergroupname'}, $position );
 
 =head1 DESCRIPTION
 
@@ -73,7 +103,7 @@ move a record it always causes other records in the list to be updated.
   __PACKAGE__->position_column('position');
 
 Sets and retrieves the name of the column that stores the 
-positional value of each record.  Default to "position".
+positional value of each record.  Defaults to "position".
 
 =cut
 
@@ -83,7 +113,7 @@ __PACKAGE__->mk_classdata( 'position_column' => 'position' );
 
   __PACKAGE__->grouping_column('group_id');
 
-This method specified a column to limit all queries in 
+This method specifies a column to limit all queries in 
 this module by.  This effectively allows you to have multiple 
 ordered lists within the same table.
 
@@ -96,7 +126,7 @@ __PACKAGE__->mk_classdata( 'grouping_column' );
   my $rs = $item->siblings();
   my @siblings = $item->siblings();
 
-Returns either a result set or an array of all other objects 
+Returns either a resultset or an array of all other objects 
 excluding the one you called it on.
 
 =cut
@@ -120,7 +150,7 @@ sub siblings {
   my $sibling = $item->first_sibling();
 
 Returns the first sibling object, or 0 if the first sibling 
-is this sibliing.
+is this sibling.
 
 =cut
 
@@ -140,7 +170,7 @@ sub first_sibling {
 
   my $sibling = $item->last_sibling();
 
-Return the last sibling, or 0 if the last sibling is this 
+Returns the last sibling, or 0 if the last sibling is this 
 sibling.
 
 =cut
@@ -161,8 +191,8 @@ sub last_sibling {
 
   my $sibling = $item->previous_sibling();
 
-Returns the sibling that resides one position back.  Undef 
-is returned if the current object is the first one.
+Returns the sibling that resides one position back.  Returns undef 
+if the current object is the first one.
 
 =cut
 
@@ -183,8 +213,8 @@ sub previous_sibling {
 
   my $sibling = $item->next_sibling();
 
-Returns the sibling that resides one position foward.  Undef 
-is returned if the current object is the last one.
+Returns the sibling that resides one position forward. Returns undef 
+if the current object is the last one.
 
 =cut
 
@@ -206,9 +236,9 @@ sub next_sibling {
 
   $item->move_previous();
 
-Swaps position with the sibling on position previous in the list.  
-1 is returned on success, and 0 is returned if the objects is already 
-the first one.
+Swaps position with the sibling in the position previous in
+the list.  Returns 1 on success, and 0 if the object is
+already the first one.
 
 =cut
 
@@ -222,8 +252,9 @@ sub move_previous {
 
   $item->move_next();
 
-Swaps position with the sibling in the next position.  1 is returned on 
-success, and 0 is returned if the object is already the last in the list.
+Swaps position with the sibling in the next position in the
+list.  Returns 1 on success, and 0 if the object is already
+the last in the list.
 
 =cut
 
@@ -239,8 +270,8 @@ sub move_next {
 
   $item->move_first();
 
-Moves the object to the first position.  1 is returned on 
-success, and 0 is returned if the object is already the first.
+Moves the object to the first position in the list.  Returns 1
+on success, and 0 if the object is already the first.
 
 =cut
 
@@ -253,8 +284,8 @@ sub move_first {
 
   $item->move_last();
 
-Moves the object to the very last position.  1 is returned on 
-success, and 0 is returned if the object is already the last one.
+Moves the object to the last position in the list.  Returns 1
+on success, and 0 if the object is already the last one.
 
 =cut
 
@@ -268,9 +299,9 @@ sub move_last {
 
   $item->move_to( $position );
 
-Moves the object to the specified position.  1 is returned on 
-success, and 0 is returned if the object is already at the 
-specified position.
+Moves the object to the specified position.  Returns 1 on
+success, and 0 if the object is already at the specified
+position.
 
 =cut
 
@@ -307,9 +338,9 @@ group, or to the end of the group if $position is undef.
 1 is returned on success, and 0 is returned if the object is
 already at the specified position of the specified group.
 
-$group should be supplied as a hashref of column => value pairs,
-e.g. if the grouping columns were 'user' and 'list',
-{ user => 'fred', list => 'work' }.
+$group may be specified as a single scalar if only one 
+grouping column is in use, or as a hashref of column => value pairs
+if multiple grouping columns are in use.
 
 =cut
 
@@ -396,9 +427,7 @@ sub update {
 
     my $pos_col = $self->position_column;
 
-    # is there a chance in hell of this working?
     # if any of our grouping columns have been changed
-$DB::single=1;
     if (grep {$_} map {exists $changes{$_}} $self->_grouping_columns ) {
 
         # create new_group by taking the current group and inserting changes
@@ -457,8 +486,8 @@ sub _grouping_clause {
 =head2 _get_grouping_columns
 
 Returns a list of the column names used for grouping, regardless of whether
-they were specified as an arrayref or a single string, and even returns ()
-if we're not grouping.
+they were specified as an arrayref or a single string, and returns ()
+if there is no grouping.
 
 =cut
 sub _grouping_columns {
@@ -493,8 +522,6 @@ sub _is_in_group {
 }
 
 
-
-
 1;
 __END__
 
@@ -513,7 +540,7 @@ ORDER BY on updates.
 
 If a position is not specified for an insert than a position 
 will be chosen based on COUNT(*)+1.  But, it first selects the 
-count then inserts the record.  The space of time between select 
+count, and then inserts the record.  The space of time between select 
 and insert introduces a race condition.  To fix this we need the 
 ability to lock tables in DBIC.  I've added an entry in the TODO 
 about this.