X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FDBIx%2FClass%2FOrdered.pm;fp=lib%2FDBIx%2FClass%2FOrdered.pm;h=88e1110ea32896bec0e92ec93fc96f3df7d0df61;hb=90545b68b06c2d2d288d593462539fe45fff48a6;hp=d5a7a003f74ad2565c793fef247486d7727cebc7;hpb=5acaa54e9ec5cbbe3c523bdafed807c14134f635;p=dbsrgits%2FDBIx-Class.git diff --git a/lib/DBIx/Class/Ordered.pm b/lib/DBIx/Class/Ordered.pm index d5a7a00..88e1110 100644 --- a/lib/DBIx/Class/Ordered.pm +++ b/lib/DBIx/Class/Ordered.pm @@ -18,27 +18,7 @@ Create a table for your ordered data. position INTEGER NOT NULL ); -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 +In your Schema or DB class add "Ordered" to the top of the component list. __PACKAGE__->load_components(qw( Ordered ... )); @@ -49,15 +29,7 @@ each row. package My::Item; __PACKAGE__->position_column('position'); -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']); - -Thats it, now you can change the position of your objects. +That's it, now you can change the position of your objects. #!/use/bin/perl use My::Item; @@ -103,7 +75,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 @@ -113,7 +85,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. @@ -126,7 +98,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 @@ -150,7 +122,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 @@ -170,7 +142,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 @@ -191,8 +163,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 @@ -213,8 +185,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 @@ -236,9 +208,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 @@ -252,8 +224,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 @@ -269,8 +242,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 @@ -283,8 +256,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 @@ -298,9 +271,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 @@ -470,8 +443,8 @@ need to use them. =head2 _grouping_clause -This method returns one or more name=>value pairs for limiting a search -by the grouping column(s). If the grouping column is not +This method returns a name=>value pair for limiting a search +by the collection column. If the collection column is not defined then this will return an empty list. =cut @@ -539,7 +512,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.