positioning Ruby Gem

To use the Positioning gem, your database table must include a column to store the position.

1. Column Name: By default, use a column named position of type integer. It should not allow NULL values.
2. Uniqueness: You must add a unique index to ensure the position value is unique within its scope (e.g., within a specific list).
3. Polymorphic Scopes: If using a polymorphic belongs_to relationship, include the type column in your unique index.

Note on values: The gem uses 0 and negative integers for internal rearrangement. Do not add database constraints that restrict the column to positive integers only. If you attempt to set a position to 0 or a negative integer, it will be converted to 1.

# Standard setup (assuming items belong to lists)
add_column :items, :position, :integer, null: false
add_index :items, [:list_id, :position], unique: true

# Polymorphic setup
add_index :items, [:listable_id, :listable_type, :position], unique: true

To allow users to select a position relative to another item (e.g., 'Add before Item X') in a web form, follow these steps:

1. Permit Parameters: Allow both the scalar position and the nested before key in your Strong Parameters.
2. Initialize Position: In your controller's new action, initialize the position with the parameter.
3. Form Helper: Use Positioning::RelativePosition.new within your form fields to handle the nested structure. This ensures the before or after value is preserved even if the position column is an integer.

Note: Adjust method names if your position column is not named position (e.g., use category_position_before_type_cast).

# 1. Controller Params
def item_params
  params.require(:item).permit(:name, :position, { position: :before })
end

# 2. Controller New Action
def new
  item.position = { before: params[:before] }
end

# 3. View (ERB)
<% if item.new_record? %>
  <%= form.fields :position, model: Positioning::RelativePosition.new(item.position_before_type_cast) do |fields|
    <%= fields.hidden_field :before %>
  <% end %>
<% end %>

You can assign positions during creation or updates using the position column.

Available Position Values:

• Integers/Strings: A specific position (e.g., 3). Values are automatically clamped between 1 and the end of the list.
• Keywords: :first or :last (or strings 'first', 'last').
• Nil/Empty: nil or "" places the record at the end of the list.
• Relative: Use {before: record_or_id} or {after: record_or_id}. You can pass nil to these to place at the start or end respectively.

Relative Accessors: The gem adds instance methods to find neighbors. These are named after the position column. For a column named position, use prior_position and subsequent_position. For category_position, use prior_category_position and subsequent_category_position.

# Creating
list.items.create(name: 'Item', position: 3)
list.items.create(name: 'Item', position: :first)
list.items.create(name: 'Item', position: { before: other_item })
list.items.create(name: 'Item', position: { after: 22 })

# Updating
item.update(position: :last)
item.update(position: { before: other_item })

# Accessing neighbors
item.prior_position
item.subsequent_position

Use the positioned method in your ActiveRecord model to enable positioning. You can define the scope (the grouping) and the database column used for the position.

• Global Scope: All records in the table belong to the same list.
• Relationship Scope: Use on: :relationship_name to scope records by a belongs_to association. The gem automatically uses the foreign key (e.g., list_id) as the scope.
• Custom Column: Use column: :column_name if you want to track multiple positions on one model.
• Arbitrary Column: The scope can be any database column (e.g., :type).
• Complex Scopes: Pass an array of columns or relationships to create a composite scope.
• Polymorphic: If the relationship is polymorphic, the gem automatically includes the _type column in the scope.

# Global scope
positioned

# Scoped to a belongs_to relationship
belongs_to :list
positioned on: :list

# Scoped to a relationship with a custom column name
belongs_to :category
positioned on: :category, column: :category_position

# Scoped to an arbitrary column
positioned on: :type

# Complex composite scope
belongs_to :list
belongs_to :category
positioned on: [:list, :category, :enabled]

# Polymorphic scope
belongs_to :listable, polymorphic: true
positioned on: :listable

The Positioning::Mechanisms class provides the core logic for managing ordered positions within a specific scope. It handles the mathematical adjustments required when records are created, updated, or destroyed to ensure the integrity of the ordered list.

Core Operations

• create_position: Initializes a new position for a record. It locks the scope, solidifies the position (resolving symbolic or relative values), and expands the existing list to accommodate the new entry.
• update_position: Adjusts the position of an existing record. It detects if the record has moved within its scope or if the scope itself has changed, then performs the necessary expand or contract operations to shift other records.
• destroy_position: Removes a record from the ordering. It moves the record out of the way and contracts the remaining records to close the gap left by the deleted item.

Position Resolution (Solidification)

When calling create_position, the library can resolve several types of position inputs into a concrete integer:

• Integer: The exact position requested.
• :first, {after: nil}, or {after: ""}: Resolves to the first position (1).
• :last, {before: nil}, {before: ""}, or nil: Resolves to the last available position in the scope.
• Relative Hash: Using :before or :after with a record or ID (e.g., {after: some_record}) allows positioning relative to another item in the same scope.

# Conceptual usage of the mechanism logic
mechanisms = Positioning::Mechanisms.new(my_record, :position)

# To create a new position
mechanisms.create_position

# To update an existing position
mechanisms.update_position

# To remove a record from the ordering
mechanisms.destroy_position