positionable 1.0.1

data/.gitignore

@@ -0,0 +1,8 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+coverage/
+spec/*.sqlite3
+doc/
+.DS_Store

data/.travis.yml

@@ -0,0 +1,7 @@
+rvm: 1.9.2
+script: "bundle exec rspec spec"
+branches:
+  only: 
+    - master
+notifications:
+  email: false

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in positionable.gemspec
+gemspec

data/LICENCE

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Philippe Guégan
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,117 @@
+= Positionable
+
+{<img src="https://secure.travis-ci.org/pguegan/positionable.png" />}[http://travis-ci.org/pguegan/positionable]
+
+<b>Positionable</b> is a library which provides contiguous positionning capabilities to your ActiveRecord models.
+
+For more functionalities, you could also have a look at acts_as_list[https://github.com/swanandp/acts_as_list].
+
+== Installation
+
+Edit your Gemfile, and simply add the following line:
+
+  gem 'positionable'
+
+== Getting Started
+
+Let's say you want to make the model +Item+ positionable.
+
+=== Create a migration
+
+First, create a migration to add the column +position+ to the table +items+:
+
+  rails generate migration add_position_to_items position:integer
+
+Then, run the migration:
+
+  rake db:migrate
+
+=== Setup your model
+
+Simply add the +is_positionable+ method in your ActiveRecord model:
+
+  class Item < ActiveRecord::Base
+    is_positionable
+  end
+
+==== Grouping records
+
+Maybe your items are grouped (typically with a +belongs_to+ association). In this case, you'll want to restrict the position in each group by declaring the +:scope+ option:
+
+  class Item < ActiveRecord::Base
+    belongs_to :folder
+    is_positionable :scope => :folder
+    attr_accessible :folder_id, :position
+  end
+
+Note that it is the model responsibility to give the white-list of attributes that can be updated <em>via</em> mass-assignement. In this case, <b>you must</b> add the +position+ attribute in the +attr_accessible+ clause.
+
+==== Start position
+
+By default, position starts by zero. But you may want to change this at the model level, for instance by starting at one (which seems more natural for some people):
+
+  class Item < ActiveRecord::Base
+    is_positionable :start => 1
+  end
+
+==== Ordering
+
+When a new record is created, it is inserted by default at the last (highest) position of its group. Thus, when record are listed, the newly created record will appear at the bottom.
+
+It is possible to change this behaviour by setting the +order+ option as follows:
+
+  class Item < ActiveRecord::Base
+    is_positionable :order => :desc
+  end
+
+This way, records are always listed by descending positions order. Record that have the highest position will appears at the top.
+
+<b>Caution!</b> The semantic of +next+ or +previous+ methods remains unchanged. More precisely, even if the highest position is the position of the <em>first</em> returned record, it is still considered as the <em>last</em> one (<em>i.e.:</em> +Item.first.last?+ returns +true+). I know, this is odd. The semantic of these methods will certainly change in a further version.
+
+==== Mixing options
+
+Obviously, these options are not exclusive. You are free to mix them like, for example:
+
+  class Item < ActiveRecord::Base
+    belongs_to :folder
+    is_positionable :scope => :folder, :order => :desc, :start => 1
+  end
+
+== Usage
+
+=== Querying
+
+To get the previous or next sibling items:
+
+  previous = item.previous
+  all_previous = item.all_previous
+  next = item.next
+  all_next = item.all_next
+
+Both first and last items can be caracterized:
+
+  item.first?   # True if item.previous is nil
+  item.last?    # True if item.next is nil
+
+Given a positionable item, its position is always included in a range which can be determined as follows:
+
+  item.range
+
+If this item is aimed at being moved to another different scope, then you can pass this new scope as a parameter:
+
+  item.range(folder)
+
+=== Moving
+
+Rather than directly assign position attribute, you can move your items with these provided methods:
+
+  item = Item.create(...)           # The newly created item is put at the last position (by default).
+  item.up!                          # Item's position is swaped with the previous item.
+  item.down!                        # Item's position is swaped with the next item.
+  item.move_to new_position         # Moves this record to the given position, and updates sibling items positions accordingly.
+
+Yet, it is possible to update the item's position <em>via</em> mass-assignement:
+
+  item.update_attributes { :position => new_position, ... }
+
+This will trigger some ActiveRecord callbacks in order to maintain positions contiguity across all other concerned items, even if the item is moved from a scope to another.

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/lib/positionable.rb

@@ -0,0 +1,314 @@
+require "positionable/version"
+require 'active_record'
+
+# <b>Positionable</b> is a library which provides contiguous positionning capabilities to your
+# ActiveRecord models. This module is designed to be an ActiveRecord extension.
+#
+# Calling the <tt>is_positionable</tt> method in your ActiveRecord model will inject
+# positionning capabilities. In particular, this will guarantee your records' positions
+# to be <em>contiguous</em>, ie.: there is no 'hole' between two adjacent positions.
+#
+# Positionable has a strong management of records that belong to a group (a.k.a. scope). When a
+# record is moved whithin its scope, or from a scope to another, other impacted records are 
+# also reordered accordingly.
+#
+# You can use the provided instance methods (<tt>up!</tt>, <tt>down!</tt> or <tt>move_to</tt>)
+# to move or reorder your records, whereas it is possible to update the position <em>via</em>
+# mass-assignement. In particular, <tt>update_attributes({:position => new_position})</tt> will
+# trigger some ActiveRecord callbacks in order to maintain positions' contiguity.
+#
+# Additional methods are available to query your model: check if this the <tt>last?</tt> or
+# <tt>first?</tt> of its own scope, retrieve the <tt>previous</tt> or the <tt>next</tt> records
+# according to their positions, etc.
+module Positionable
+
+  def self.included(base)
+    base.extend(PositionableMethods)
+  end
+
+  module PositionableMethods
+
+    # Makes this model positionable.
+    # 
+    #   class Item < ActiveRecord::Base
+    #     is_positionable
+    #   end
+    #
+    # Maybe your items are grouped (typically with a +belongs_to+ association). In this case, 
+    # you'll want to restrict the position in each group by declaring the +:scope+ option:
+    #
+    #   class Folder < ActiveRecord::Base
+    #     has_many :items
+    #   end
+    #
+    #   class Item < ActiveRecord::Base
+    #     belongs_to :folder
+    #     is_positionable :scope => :folder
+    #   end
+    #
+    # By default, position starts by zero. But you may want to change this at the model level,
+    # for instance by starting at one (which seems more natural for some people):
+    # 
+    #   class Item < ActiveRecord::Base
+    #     is_positionable :start => 1
+    #   end
+    #
+    # To make new records to appear at first position, the default ordering can be changed as
+    # follows:
+    #
+    #   class Item < ActiveRecord::Base
+    #     is_positionable :order => :desc
+    #   end
+    def is_positionable(options = {})
+      include InstanceMethods
+
+      scope_id_attr = "#{options[:scope].to_s}_id" if options[:scope]
+      start = options[:start] || 0
+      order = options[:order] || :asc
+
+      default_scope order("\"#{self.table_name}\".\"position\" #{order}")
+
+      before_create :add_to_bottom
+      before_update :update_position
+      after_destroy :decrement_all_next
+
+      if scope_id_attr
+        class_eval <<-RUBY
+
+          def scope_id
+            send(:"#{scope_id_attr}")
+          end
+
+          # Gives the range of available positions for this record, whithin the provided scope.
+          # If no scope is provided, then it takes the record's current scope by default.
+          # If this record is new and no scope can be retrieved, then a <tt>RangeWithoutScopeError</tt>
+          # is raised.
+          def range(scope = nil)
+            raise RangeWithoutScopeError if new_record? and scope.nil? and scope_id.nil?
+            # Does its best to retrieve the target scope...
+            target_scope_id = scope.nil? ? scope_id : scope.id
+            # Number of records whithin the target scope
+            count = self.class.where("#{scope_id_attr} = ?", target_scope_id).count
+            # An additional position is available if this record is new, or if it's moved to another scope
+            if new_record? or target_scope_id != scope_id
+              (start..(count + 1))
+            else
+              (start..count)
+            end
+          end
+
+        private
+
+          def scoped_condition
+            "#{scope_id_attr} = " + scope_id.to_s
+          end
+
+          def scoped_position
+            scoped_condition + " and position"
+          end
+
+          def scope_changed?
+            send(:"#{scope_id_attr}_changed?")
+          end
+
+          def scope_id_was
+            send(:"#{scope_id_attr}_was")
+          end
+
+          def scoped_condition_was
+            "#{scope_id_attr} = " + scope_id_was.to_s
+          end
+
+          def scoped_position_was
+            scoped_condition_was + " and position"
+          end
+
+        RUBY
+      else
+        class_eval <<-RUBY
+
+          # Gives the range of available positions for this record.
+          def range
+            if new_record?
+              (start..(bottom + 1))
+            else
+              (start..bottom)
+            end
+          end
+
+        private
+
+          def scope_changed?
+            false
+          end
+
+          def scoped_condition
+            ""
+          end
+
+          def scoped_position
+            "position"
+          end
+
+        RUBY
+      end
+
+      class_eval <<-RUBY
+        def start
+          #{start}
+        end
+      RUBY
+    end
+
+    module InstanceMethods
+
+      # Tells whether this record is the first one (of his scope, if any).
+      def first?
+        position == start
+      end
+
+      # Tells whether this record is the last one (of his scope, if any).
+      def last?
+        position == bottom
+      end
+
+      # Swaps this record position with his previous sibling, unless this record is the first one.
+      def up!
+        swap_with(previous) unless first?
+      end
+
+      # Swaps this record position with his next sibling, unless this record is the last one.
+      def down!
+        swap_with(self.next) unless last?
+      end
+
+      # Moves this record at the given position, and updates positions of the impacted sibling
+      # records accordingly. If the new position is out of range, then the record is not moved.
+      def move_to(new_position)
+        if range.include? new_position
+          reorder(position, new_position)
+          update_column(:position, new_position)
+        end
+      end
+
+      # The next sibling record, whose position is right after this record.
+      def next
+        at(position + 1)
+      end
+
+      # All the next records, whose positions are greater than this record. Records
+      # are ordered by their respective positions, depending on the <tt>order</tt> option
+      # provided to <tt>is_positionable</tt>.
+      def all_next
+        self.class.where("#{scoped_position} > ?", position)
+      end
+
+      # All the next records <em>of the old scope</em>, whose positions are greater 
+      # than this record before it was moved from its old record.
+      def all_next_was
+        self.class.where("#{scoped_position_was} > ?", position_was)
+      end
+
+      # Gives the next sibling record, whose position is right before this record.
+      def previous
+        at(position - 1)
+      end
+
+      # All the next records, whose positions are smaller than this record. Records
+      # are ordered by their respective positions, depending on the <tt>order</tt> option
+      # provided to <tt>is_positionable</tt> (ascending by default).
+      def all_previous
+        self.class.where("#{scoped_position} < ?", position)
+      end
+
+    private
+
+      # The position of the last record.
+      def bottom
+        scoped_all.size + start - 1
+      end
+
+      # Finds the record at the given position.
+      def at(position)
+        self.class.where("#{scoped_position} = ?", position).limit(1).first
+      end
+
+      # Swaps this record's position with the other provided record.
+      def swap_with(other)
+        self.class.transaction do
+          old_position = position
+          update_attribute(:position, other.position)
+          other.update_attribute(:position, old_position)
+        end
+      end
+
+      # All the records that belong to same scope (if any) of this record (including itself).
+      def scoped_all
+        self.class.where(scoped_condition)
+      end
+
+      # Reorders records between provided positions, unless the destination position is out of range.
+      def reorder(from, to)
+        if to > from
+          shift, siblings = -1, ((from + 1)..to).map { |p| at(p) }
+        elsif scope_changed?
+          # When scope changes, it actually inserts this record in the new scope
+          # All next siblings (from new position to bottom) have to be staggered
+          shift, siblings = 1, (to..bottom).map { |p| at(p) }
+        else
+          shift, siblings = 1, (to..(from - 1)).map { |p| at(p) }
+        end
+        self.class.transaction do
+          siblings.map do |sibling|
+            sibling.update_column(:position, sibling.position + shift)
+          end
+        end
+      end
+
+      # Reorders records between old and new position (and old and new scope).
+      def update_position
+        if scope_changed?
+          decrement(all_next_was)
+          if range.include?(position)
+            reorder(position_was, position)
+          else
+            add_to_bottom
+          end
+        else
+          if range.include?(position)
+            reorder(position_was, position)
+          else
+            self.position = position_was # Keep original position
+          end
+        end
+      end
+
+      # Adds this record to the bottom.
+      def add_to_bottom
+        self.position = bottom + 1
+      end
+
+      # Decrements the position of all the next sibling records of this record.
+      def decrement_all_next
+        decrement(all_next)
+      end
+
+      # Decrements the position of all the provided records.
+      def decrement(records)
+        self.class.transaction do
+          records.each do |record|
+            record.update_column(:position, record.position - 1)
+          end
+        end
+      end
+
+    end
+
+  end
+
+  class RangeWithoutScopeError < StandardError
+  end
+
+  ActiveRecord::Base.send(:include, Positionable)
+
+end