.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "DBIx::Class::Ordered 3pm"
.TH DBIx::Class::Ordered 3pm "2018-04-19" "perl v5.26.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
DBIx::Class::Ordered \- Modify the position of objects in an ordered list.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Create a table for your ordered data.
.PP
.Vb 5
\&  CREATE TABLE items (
\&    item_id INTEGER PRIMARY KEY AUTOINCREMENT,
\&    name TEXT NOT NULL,
\&    position INTEGER NOT NULL
\&  );
.Ve
.PP
Optionally, add one or more columns to specify groupings, allowing you
to maintain independent ordered lists within one table:
.PP
.Vb 6
\&  CREATE TABLE items (
\&    item_id INTEGER PRIMARY KEY AUTOINCREMENT,
\&    name TEXT NOT NULL,
\&    position INTEGER NOT NULL,
\&    group_id INTEGER NOT NULL
\&  );
.Ve
.PP
Or even
.PP
.Vb 7
\&  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
\&  );
.Ve
.PP
In your Schema or \s-1DB\s0 class add \*(L"Ordered\*(R" to the top
of the component list.
.PP
.Vb 1
\&  _\|_PACKAGE_\|_\->load_components(qw( Ordered ... ));
.Ve
.PP
Specify the column that stores the position number for
each row.
.PP
.Vb 2
\&  package My::Item;
\&  _\|_PACKAGE_\|_\->position_column(\*(Aqposition\*(Aq);
.Ve
.PP
If you are using one grouping column, specify it as follows:
.PP
.Vb 1
\&  _\|_PACKAGE_\|_\->grouping_column(\*(Aqgroup_id\*(Aq);
.Ve
.PP
Or if you have multiple grouping columns:
.PP
.Vb 1
\&  _\|_PACKAGE_\|_\->grouping_column([\*(Aqgroup_id\*(Aq, \*(Aqother_group_id\*(Aq]);
.Ve
.PP
That's it, now you can change the position of your objects.
.PP
.Vb 2
\&  #!/use/bin/perl
\&  use My::Item;
\&
\&  my $item = My::Item\->create({ name=>\*(AqMatt S. Trout\*(Aq });
\&  # If using grouping_column:
\&  my $item = My::Item\->create({ name=>\*(AqMatt S. Trout\*(Aq, group_id=>1 });
\&
\&  my $rs = $item\->siblings();
\&  my @siblings = $item\->siblings();
\&
\&  my $sibling;
\&  $sibling = $item\->first_sibling();
\&  $sibling = $item\->last_sibling();
\&  $sibling = $item\->previous_sibling();
\&  $sibling = $item\->next_sibling();
\&
\&  $item\->move_previous();
\&  $item\->move_next();
\&  $item\->move_first();
\&  $item\->move_last();
\&  $item\->move_to( $position );
\&  $item\->move_to_group( \*(Aqgroupname\*(Aq );
\&  $item\->move_to_group( \*(Aqgroupname\*(Aq, $position );
\&  $item\->move_to_group( {group_id=>\*(Aqgroupname\*(Aq, \*(Aqother_group_id=>\*(Aqothergroupname\*(Aq} );
\&  $item\->move_to_group( {group_id=>\*(Aqgroupname\*(Aq, \*(Aqother_group_id=>\*(Aqothergroupname\*(Aq}, $position );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides a simple interface for modifying the ordered
position of DBIx::Class objects.
.SH "AUTO UPDATE"
.IX Header "AUTO UPDATE"
All of the move_* methods automatically update the rows involved in
the query.  This is not configurable and is due to the fact that if you
move a record it always causes other records in the list to be updated.
.SH "METHODS"
.IX Header "METHODS"
.SS "position_column"
.IX Subsection "position_column"
.Vb 1
\&  _\|_PACKAGE_\|_\->position_column(\*(Aqposition\*(Aq);
.Ve
.PP
Sets and retrieves the name of the column that stores the
positional value of each record.  Defaults to \*(L"position\*(R".
.SS "grouping_column"
.IX Subsection "grouping_column"
.Vb 1
\&  _\|_PACKAGE_\|_\->grouping_column(\*(Aqgroup_id\*(Aq);
.Ve
.PP
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.
.SS "null_position_value"
.IX Subsection "null_position_value"
.Vb 1
\&  _\|_PACKAGE_\|_\->null_position_value(undef);
.Ve
.PP
This method specifies a value of \*(L"position_column\*(R" which \fBwould
never be assigned to a row\fR during normal operation. When
a row is moved, its position is set to this value temporarily, so
that any unique constraints can not be violated. This value defaults
to 0, which should work for all cases except when your positions do
indeed start from 0.
.SS "siblings"
.IX Subsection "siblings"
.Vb 2
\&  my $rs = $item\->siblings();
\&  my @siblings = $item\->siblings();
.Ve
.PP
Returns an \fBordered\fR resultset of all other objects in the same
group excluding the one you called it on.
.PP
The ordering is a backwards-compatibility artifact \- if you need
a resultset with no ordering applied use \f(CW\*(C`_siblings\*(C'\fR
.SS "previous_siblings"
.IX Subsection "previous_siblings"
.Vb 2
\&  my $prev_rs = $item\->previous_siblings();
\&  my @prev_siblings = $item\->previous_siblings();
.Ve
.PP
Returns a resultset of all objects in the same group
positioned before the object on which this method was called.
.SS "next_siblings"
.IX Subsection "next_siblings"
.Vb 2
\&  my $next_rs = $item\->next_siblings();
\&  my @next_siblings = $item\->next_siblings();
.Ve
.PP
Returns a resultset of all objects in the same group
positioned after the object on which this method was called.
.SS "previous_sibling"
.IX Subsection "previous_sibling"
.Vb 1
\&  my $sibling = $item\->previous_sibling();
.Ve
.PP
Returns the sibling that resides one position back.  Returns 0
if the current object is the first one.
.SS "first_sibling"
.IX Subsection "first_sibling"
.Vb 1
\&  my $sibling = $item\->first_sibling();
.Ve
.PP
Returns the first sibling object, or 0 if the first sibling
is this sibling.
.SS "next_sibling"
.IX Subsection "next_sibling"
.Vb 1
\&  my $sibling = $item\->next_sibling();
.Ve
.PP
Returns the sibling that resides one position forward. Returns 0
if the current object is the last one.
.SS "last_sibling"
.IX Subsection "last_sibling"
.Vb 1
\&  my $sibling = $item\->last_sibling();
.Ve
.PP
Returns the last sibling, or 0 if the last sibling is this
sibling.
.SS "move_previous"
.IX Subsection "move_previous"
.Vb 1
\&  $item\->move_previous();
.Ve
.PP
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.
.SS "move_next"
.IX Subsection "move_next"
.Vb 1
\&  $item\->move_next();
.Ve
.PP
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.
.SS "move_first"
.IX Subsection "move_first"
.Vb 1
\&  $item\->move_first();
.Ve
.PP
Moves the object to the first position in the list.  Returns 1
on success, and 0 if the object is already the first.
.SS "move_last"
.IX Subsection "move_last"
.Vb 1
\&  $item\->move_last();
.Ve
.PP
Moves the object to the last position in the list.  Returns 1
on success, and 0 if the object is already the last one.
.SS "move_to"
.IX Subsection "move_to"
.Vb 1
\&  $item\->move_to( $position );
.Ve
.PP
Moves the object to the specified position.  Returns 1 on
success, and 0 if the object is already at the specified
position.
.SS "move_to_group"
.IX Subsection "move_to_group"
.Vb 1
\&  $item\->move_to_group( $group, $position );
.Ve
.PP
Moves the object to the specified position of the specified
group, or to the end of the group if \f(CW$position\fR is undef.
1 is returned on success, and 0 is returned if the object is
already at the specified position of the specified group.
.PP
\&\f(CW$group\fR 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.
.SS "insert"
.IX Subsection "insert"
Overrides the \s-1DBIC\s0 \fIinsert()\fR method by providing a default
position number.  The default will be the number of rows in
the table +1, thus positioning the new record at the last position.
.SS "update"
.IX Subsection "update"
Overrides the \s-1DBIC\s0 \fIupdate()\fR method by checking for a change
to the position and/or group columns.  Movement within a
group or to another group is handled by repositioning
the appropriate siblings.  Position defaults to the end
of a new group if it has been changed to undef.
.SS "delete"
.IX Subsection "delete"
Overrides the \s-1DBIC\s0 \fIdelete()\fR method by first moving the object
to the last position, then deleting it, thus ensuring the
integrity of the positions.
.SH "METHODS FOR EXTENDING ORDERED"
.IX Header "METHODS FOR EXTENDING ORDERED"
You would want to override the methods below if you use sparse
(non-linear) or non-numeric position values. This can be useful
if you are working with preexisting non-normalised position data,
or if you need to work with materialized path columns.
.SS "_position_from_value"
.IX Subsection "_position_from_value"
.Vb 1
\&  my $num_pos = $item\->_position_from_value ( $pos_value )
.Ve
.PP
Returns the \fBabsolute numeric position\fR of an object with a \fBposition
value\fR set to \f(CW$pos_value\fR. By default simply returns \f(CW$pos_value\fR.
.SS "_position_value"
.IX Subsection "_position_value"
.Vb 1
\&  my $pos_value = $item\->_position_value ( $pos )
.Ve
.PP
Returns the \fBvalue\fR of \*(L"position_column\*(R" of the object at numeric
position \f(CW$pos\fR. By default simply returns \f(CW$pos\fR.
.SS "_initial_position_value"
.IX Subsection "_initial_position_value"
.Vb 1
\&  _\|_PACKAGE_\|_\->_initial_position_value(0);
.Ve
.PP
This method specifies a \fBvalue\fR of \*(L"position_column\*(R" which is assigned
to the first inserted element of a group, if no value was supplied at
insertion time. All subsequent values are derived from this one by
\&\*(L"_next_position_value\*(R" below. Defaults to 1.
.SS "_next_position_value"
.IX Subsection "_next_position_value"
.Vb 1
\&  my $new_value = $item\->_next_position_value ( $position_value )
.Ve
.PP
Returns a position \fBvalue\fR that would be considered \f(CW\*(C`next\*(C'\fR with
regards to \f(CW$position_value\fR. Can be pretty much anything, given
that \f(CW\*(C`$position_value < $new_value\*(C'\fR where \f(CW\*(C`<\*(C'\fR is the
\&\s-1SQL\s0 comparison operator (usually works fine on strings). The
default method expects \f(CW$position_value\fR to be numeric, and
returns \f(CW\*(C`$position_value + 1\*(C'\fR
.SS "_shift_siblings"
.IX Subsection "_shift_siblings"
.Vb 1
\&  $item\->_shift_siblings ($direction, @between)
.Ve
.PP
Shifts all siblings with \fBpositions values\fR in the range \f(CW@between\fR
(inclusive) by one position as specified by \f(CW$direction\fR (left if < 0,
 right if > 0). By default simply increments/decrements each
\&\*(L"position_column\*(R" value by 1, doing so in a way as to not violate
any existing constraints.
.PP
Note that if you override this method and have unique constraints
including the \*(L"position_column\*(R" the shift is not a trivial task.
Refer to the implementation source of the default method for more
information.
.SH "CAVEATS"
.IX Header "CAVEATS"
.SS "Resultset Methods"
.IX Subsection "Resultset Methods"
Note that all Insert/Create/Delete overrides are happening on
DBIx::Class::Row methods only. If you use the
DBIx::Class::ResultSet versions of
update or
delete, all logic present in this
module will be bypassed entirely (possibly resulting in a broken
order-tree). Instead always use the
update_all and
delete_all methods, which will
invoke the corresponding row method on every
member of the given resultset.
.SS "Race Condition on Insert"
.IX Subsection "Race Condition on Insert"
If a position is not specified for an insert, a position
will be chosen based either on \*(L"_initial_position_value\*(R" or
\&\*(L"_next_position_value\*(R", depending if there are already some
items in the current group. The space of time between the
necessary selects and insert introduces a race condition.
Having unique constraints on your position/group columns,
and using transactions (see \*(L"txn_do\*(R" in DBIx::Class::Storage)
will prevent such race conditions going undetected.
.SS "Multiple Moves"
.IX Subsection "Multiple Moves"
If you have multiple same-group result objects already loaded from storage,
you need to be careful when executing \f(CW\*(C`move_*\*(C'\fR operations on them:
without a \*(L"position_column\*(R" reload the \*(L"_position_value\*(R" of the
\&\*(L"siblings\*(R" will be out of sync with the underlying storage.
.PP
Starting from version \f(CW0.082800\fR \s-1DBIC\s0 will implicitly perform such
reloads when the \f(CW\*(C`move_*\*(C'\fR happens as a part of a transaction
(a good example of such situation is \f(CW\*(C`$ordered_resultset\->delete_all\*(C'\fR).
.PP
If it is not possible for you to wrap the entire call-chain in a transaction,
you will need to call \*(L"discard_changes\*(R" in DBIx::Class::Row to get an object
up-to-date before proceeding, otherwise undefined behavior will result.
.SS "Default Values"
.IX Subsection "Default Values"
Using a database defined default_value on one of your group columns
could result in the position not being assigned correctly.
.SH "FURTHER QUESTIONS?"
.IX Header "FURTHER QUESTIONS?"
Check the list of additional \s-1DBIC\s0 resources.
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This module is free software copyright
by the DBIx::Class (\s-1DBIC\s0) authors. You can
redistribute it and/or modify it under the same terms as the
DBIx::Class library.