Module: Mongoid::ActsAsList::List

Extended by:
ActiveSupport::Concern
Defined in:
lib/mongoid/acts_as_list/list.rb,
lib/mongoid/acts_as_list/list/root.rb,
lib/mongoid/acts_as_list/list/embedded.rb

Defined Under Namespace

Modules: ClassMethods, Embedded, Root Classes: ScopeMissingError

Instance Method Summary collapse

Instance Method Details

#decrement_positionObject

Public: decrements the position number without affecting other items

for API compatibility with AR acts_as_list


291
292
293
# File 'lib/mongoid/acts_as_list/list.rb', line 291

def decrement_position
  inc(position_field, -1)
end

#default_positionObject

Public: returns the default position symbol as defined in the configuration

for API compatibility with AR acts_as_list


297
298
299
# File 'lib/mongoid/acts_as_list/list.rb', line 297

def default_position
  Mongoid::ActsAsList.configuration.default_position_field
end

#default_position?Boolean

Public: returns true if the model uses the default position field name as defined in the configuration

for API compatibility with AR acts_as_list

Returns:

  • (Boolean)


303
304
305
# File 'lib/mongoid/acts_as_list/list.rb', line 303

def default_position?
  position_field == default_position
end

#first?Boolean

Public: Indicates if an item is the first of the list

Returns true if the item is the first in the list or false if not

Returns:

  • (Boolean)


241
242
243
# File 'lib/mongoid/acts_as_list/list.rb', line 241

def first?
  self[position_field] == start_position_in_list
end

#in_list?Boolean

Public: Indicates if an item is in the list

Returns true if the item is in the list or false if not

Returns:

  • (Boolean)


227
228
229
# File 'lib/mongoid/acts_as_list/list.rb', line 227

def in_list?
  self[position_field].present?
end

#increment_positionObject

Public: increments the position number without affecting other items

for API compatibility with AR acts_as_list


285
286
287
# File 'lib/mongoid/acts_as_list/list.rb', line 285

def increment_position
  inc(position_field, 1)
end

#insert_at(new_position) ⇒ Object

Public: Insert at a given position in the list

for API compatibility with AR acts_as_list

new_position - an Integer indicating the position to insert the item at

Returns true if the element’s position was updated, false if not



278
279
280
281
# File 'lib/mongoid/acts_as_list/list.rb', line 278

def insert_at(new_position)
  insert_space_at(new_position)
  update_attribute(position_field, new_position)
end

#last?Boolean

Public: Indicates if an item is the last of the list

Returns true if the item is the last in the list or false if not

Returns:

  • (Boolean)


248
249
250
# File 'lib/mongoid/acts_as_list/list.rb', line 248

def last?
  self[position_field] == last_item_in_list[position_field]
end

#move(where = {}) ⇒ Object

Public: Moves the item to new position in the list

where - a Symbol in [:forward, :lower, :backward, :higher]

or Hash specifying where to move the item:
  :to                - an Integer representing a position number
                       or a Symbol from the list :start, :top, :end, :bottom
  :before, :above    - another object in the list
  :after: , :below   - another object in the list
  :forward, :lower   - an Integer specify by how much to move the item forward.
                       will stop moving the item when it reaches the end of the list
  :backward, :higher - an Integer specify by how much to move the item forward.
                       will stop moving the item when it reaches the end of the list

Examples

item.move to: 3
#=> moves item to the 3rd position

item.move to: :start
#=> moves item to the first position in the list

other_item.position #=> 3

item.move before: other_item
#=> moves item to position 3 and other_item to position 4

item.move after: other_item
#=> moves item to position 4

item.move backward: 3
#=> move item 3 positions closer to the start of the list

item.move :forward
#=> same as item.move(forward: 1)

Returns nothing



126
127
128
129
130
131
132
133
134
135
136
137
138
139
# File 'lib/mongoid/acts_as_list/list.rb', line 126

def move(where = {})
  if where.is_a? Hash
    options = [:to, :before, :above, :after, :below, :forward, :forwards, :lower, :backward, :backwards, :higher]

    prefix, destination = where.each.select { |k, _| options.include? k }.first
    raise ArgumentError, "#move requires one of the following options: #{options.join(', ')}" unless prefix

    send("move_#{prefix}", destination)
  else
    destination = where

    send("move_#{destination}")
  end
end

#move_after(other_item) ⇒ Object Also known as: move_below

Public: Moves the item after another one in the list

other_item - another item of the list



203
204
205
206
207
208
209
210
211
212
# File 'lib/mongoid/acts_as_list/list.rb', line 203

def move_after(other_item)
  destination = other_item[position_field]
  origin = self[position_field]

  if origin > destination
    insert_at destination + 1
  else
    insert_at destination
  end
end

#move_backwards(by_how_much = 1) ⇒ Object Also known as: move_higher, move_backward

Public: Moves the item closer to the start of the list

by_how_much - The number of position to move the item by (default: 1)



179
180
181
# File 'lib/mongoid/acts_as_list/list.rb', line 179

def move_backwards by_how_much = 1
  move_to(self[position_field] - by_how_much) unless first?
end

#move_before(other_item) ⇒ Object Also known as: move_above

Public: Moves the item before another one in the list

other_item - another item of the list



188
189
190
191
192
193
194
195
196
197
# File 'lib/mongoid/acts_as_list/list.rb', line 188

def move_before(other_item)
  destination = other_item[position_field]
  origin = self[position_field]

  if origin > destination
    insert_at destination
  else
    insert_at destination - 1
  end
end

#move_forwards(by_how_much = 1) ⇒ Object Also known as: move_lower, move_forward

Public: Moves the item closer to the end of the list

by_how_much - The number of position to move the item by (default: 1)



170
171
172
# File 'lib/mongoid/acts_as_list/list.rb', line 170

def move_forwards by_how_much = 1
  move_to(self[position_field] + by_how_much) unless last?
end

#move_to(destination) ⇒ Object

Public: Moves the item to another position

destination - a Symbol among :start, :end, :top, :bottom

or an Integer indicating the new position number to move the item to


145
146
147
148
149
150
151
152
# File 'lib/mongoid/acts_as_list/list.rb', line 145

def move_to(destination)
  if destination.is_a? Symbol
    send("move_to_#{destination}")
  else
    destination = position_within_list_boundaries(destination)
    insert_at destination
  end
end

#move_to_endObject Also known as: move_to_bottom

Public: Moves the item to the end of the list



155
156
157
158
# File 'lib/mongoid/acts_as_list/list.rb', line 155

def move_to_end
  new_position = in_list? ? last_position_in_list : next_available_position_in_list
  insert_at new_position
end

#move_to_startObject Also known as: move_to_top

Public: Moves the item to the start of the list



162
163
164
# File 'lib/mongoid/acts_as_list/list.rb', line 162

def move_to_start
  insert_at start_position_in_list
end

#next_itemObject Also known as: lower_item

Public: Gets the following item in the list

Returns the next item in the list

or nil if there isn't a next item


256
257
258
259
# File 'lib/mongoid/acts_as_list/list.rb', line 256

def next_item
  return unless in_list?
  items_in_list.where(position_field => self[position_field]+1).first
end

#not_in_list?Boolean

Public: Indicates if an item is not in the list

Returns true if the item is not in the list or false if it is

Returns:

  • (Boolean)


234
235
236
# File 'lib/mongoid/acts_as_list/list.rb', line 234

def not_in_list?
  !in_list?
end

#previous_itemObject Also known as: higher_item

Public: Gets the preceding item in the list

Returns the previous item in the list

or nil if there isn't a previous item


266
267
268
269
# File 'lib/mongoid/acts_as_list/list.rb', line 266

def previous_item
  return unless in_list?
  items_in_list.where(position_field => self[position_field]-1).first
end

#remove_from_listObject

Public: Removes the item from the list

Returns true if the item was removed, false if not



218
219
220
221
222
# File 'lib/mongoid/acts_as_list/list.rb', line 218

def remove_from_list
  return true unless in_list?
  shift_later_items_towards_start_of_list
  update_attributes(position_field => nil)
end