DataMapper::Is::List::InstanceMethods

@api semipublic

detaches a list item from the list, essentially setting the position as nil

@param scope <Hash> Optional (Default is list_scope)

@return <DataMapper::Collection> the list items within the given scope

@example [Usage]

@api public

# File lib/dm-is-list/is/list.rb, line 426
def detach(scope = list_scope)
  list(scope).all(:position.gt => position).adjust!({ :position => -1 },true)
  self.position = nil
end

finds the previous higher item in the list (lower in number position)

@return <Model> the previous list item

@example [Usage]

Todo.get(2).left_sibling  => Todo.get(1)
Todo.get(2).higher_item  => Todo.get(1)
Todo.get(2).previous_item  => Todo.get(1)

@api public

# File lib/dm-is-list/is/list.rb, line 463
def left_sibling
  list.reverse.first(:position.lt => position)
end

returns the list the current item belongs to

@param scope <Hash> Optional (Default is list_query)

@return <DataMapper::Collection> the list items within the given scope

@example [Usage]

Todo.get(2).list  => [ list of Todo items within the same scope as item]
Todo.get(2).list(:user_id => 2 )  => [ list of Todo items with user_id => 2]

@api public

# File lib/dm-is-list/is/list.rb, line 389
def list(scope = list_query)
  model.all(scope)
end

returns the query conditions

@return <Hash> ...?

@example [Usage]

Todo.get(2).list_query => { :user_id => 1, :order => [:position] }

@api semipublic

# File lib/dm-is-list/is/list.rb, line 373
def list_query
  list_scope.merge(:order => [ :position ])
end

returns the scope of the current list item

@return <Hash> ...?

@example [Usage]

Todo.get(2).list_scope => { :user_id => 1 }

@api semipublic

# File lib/dm-is-list/is/list.rb, line 342
def list_scope
  Hash[ model.list_options[:scope].map { |p| [ p, attribute_get(p) ] } ]
end

move item to a position in the list. position should only be changed through this

@example [Usage]

* node.move :higher                 # moves node higher unless it is at the top of list
* node.move :lower                  # moves node lower unless it is at the bottom of list
* node.move :below => other_node    # moves this node below the other resource in the list
* node.move :above => Node.get(2)   # moves this node above the other resource in the list
* node.move :to => 2                # moves this node to the position given in the list
* node.move(2)                      # moves this node to the position given in the list

@param vector <Symbol, Hash, Integer> An integer, a symbol, or a key-value pair that describes the requested movement

@option :higher<Symbol> move item higher @option :lower<Symbol> move item lower @option :up<Symbol> move item higher @option :down<Symbol> move item lower @option :highest<Symbol> move item to the top of the list @option :lowest<Symbol> move item to the bottom of the list @option :top<Symbol> move item to the top of the list @option :bottom<Symbol> move item to the bottom of the list @option :above<Resource> move item above other item. must be in same scope @option :below<Resource> move item below other item. must be in same scope @option :to<Hash{Symbol => Integer/String}> move item to a specific position in the list @option <Integer> move item to a specific position in the list

@return <TrueClass, FalseClass> returns false if it cannot move to the position, otherwise true @see move_without_saving

@api public

# File lib/dm-is-list/is/list.rb, line 517
def move(vector)
  move_without_saving(vector) && save
end

moves an item from one list to another

@param scope <Integer> must be the id value of the scope @param pos <Integer> Optional sets the entry position for the item in the new list

@example [Usage]

Todo.get(2).move_to_list(2)
Todo.get(2).move_to_list(2, 10)

@return <Boolean> True/False based upon result

@api public

# File lib/dm-is-list/is/list.rb, line 444
def move_to_list(scope, pos = nil)
  detach   # remove from current list
  attribute_set(model.list_options[:scope][0], scope.to_i) # set new scope
  save     # save progress. Needed to get the positions correct.
  reload   # get a fresh new start
  move(pos) unless pos.nil?
end

returns the original scope of the current list item

@return <Hash> ...?

@example [Usage]

item = Todo.get(2) # with user_id 1
item.user_id = 2
item.original_list_scope  => { :user_id => 1 }

@api semipublic

# File lib/dm-is-list/is/list.rb, line 357
def original_list_scope
  pairs = model.list_options[:scope].map do |p|
    [ p, (property = properties[p]) && original_attributes.key?(property) ? original_attributes[property] : attribute_get(p) ]
  end
  Hash[ pairs ]
end

reorder the list this item belongs to

@param order <Array> ...?

@return <Boolean> True/False based upon result

@example [Usage]

Todo.get(2).reorder_list([:title.asc])

@api public

# File lib/dm-is-list/is/list.rb, line 412
def reorder_list(order)
  model.repair_list(list_scope.merge(:order => order))
end

repair the list this item belongs to

@api public

# File lib/dm-is-list/is/list.rb, line 397
def repair_list
  model.repair_list(list_scope)
end

finds the next lower item in the list (higher in number position)

@return <Model> the next list item

@example [Usage]

Todo.get(2).right_sibling  => Todo.get(3)
Todo.get(2).lower_item  => Todo.get(3)
Todo.get(2).next_item  => Todo.get(3)

@api public

# File lib/dm-is-list/is/list.rb, line 480
def right_sibling
  list.first(:position.gt => position)
end