positioning 0.1.6 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2fa6907a0507b7978c58578596c4e6ca16b7e334eb98b3fa42cba47a0d0b89b5
-  data.tar.gz: ed8f3126f69cb0f8780244a05d48e46abd0b64468ad47838f0d5827b4fa943ff
+  metadata.gz: 3287b3ffda224e17c32b5601cc2f14aba284bcac50d7627be46300f1c7473521
+  data.tar.gz: 9027f931d4dc6781241cd80faacf056d320307e94fb0a1ded2e8563bc7d86b59
 SHA512:
-  metadata.gz: 5d35b26bf717252dc30d828b2fff2b5b36c82ccd5b33d5480798cc57e38bacf9434120d2a478d448998c368286272a9dc2604cb8d3ebd071da0a55c8fa4ad5ba
-  data.tar.gz: 3b9c21bb1a3fe42c0799ffe6e991b29f7c17fd4efec8ff3b159afa41cd8a6b8b1e975e47c8e69e22dfd673352b105f2c55d85887a07d90e528b2cd0c54b3a318
+  metadata.gz: 8f0a3353940e24c88f89835fee413eef989a67e3ef1a984d8cba2611d377be6a68f0743568090cb5a58da2f6c8f2eb17d15cfa2f4880b4f0b209f4ad582b176f
+  data.tar.gz: 975fa2efc49eacb1dc5a96de826ccc9e6db72f8adb82a4d44f72dff57581cd551581c77458c40b06686c90232aebff127006503369cee3faed0ad704160e8c21

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 ## [Unreleased]
 
+## [0.1.7] - 2024-03-06
+
+- Seperated the Concern that is included into ActiveRecord::Base into its own submodule so that Mechanisms isn't also included.
+- Added the RelativePosition Struct and documentation to make it easier to supply relative positions via form helpers.
+
 ## [0.1.6] - 2024-03-05
 
 - Allow the position to be passed as a JSON object so that we can pass in complex positions from the browser more easily.

data/README.md

@@ -82,11 +82,13 @@ If you don't provide a position when creating a record, your record will be adde
 
 To assign a specific position when creating or updating a record you can simply declare a specific value for the database column tracking the position of records (by default this is `position`). The valid options for this column are:
 
-* A specific integer value. Values are automatically clamped to between `1` and the next available position at the end of the list (inclusive). You should use explicit position values as a last resort, instead you can use:
-* `:first` places the record at the start of the list.
-* `:last` places the record at the end of the list.
-* `nil` also places the record at the end of the list.
-* `before:` and `after:` allow you to define the position relative to other records in the list. You can define the relative record by its primary key (usually `id`) or by providing the record itself. You can also provide `nil` in which case the item will be placed at the start or end of the list (see below).
+* A specific integer value as an `Integer` or a `String`. Values are automatically clamped to between `1` and the next available position at the end of the list (inclusive). You should use explicit position values as a last resort, instead you can use:
+* `:first` or `"first"` places the record at the start of the list.
+* `:last` or `"last"` places the record at the end of the list.
+* `nil` and `""` also places the record at the end of the list.
+* `before:` and `after:` allow you to define the position relative to other records in the list. You can define the relative record by its primary key (usually `id`) or by providing the record itself. You can also provide `nil` or `""` in which case the item will be placed at the start or end of the list (see below).
+
+**You can provide the position value as a JSON string and it will be decoded first. This could be useful if you have no other way to provide `before:` or `after:` as a hash (e.g. `"{\"after\":33}"`). See below for a technique to provide `before:` and `after:` using form helpers.**
 
 Position parameters can be strings or symbols, so you can provide them from the browser.
 
@@ -149,6 +151,42 @@ other_item.id # => 11
 item.update position: {after: 11}
 ```
 
+##### Relative Positining in Forms
+
+It can be tricky to provide the hash forms of relative positining using Rails form helpers, but it is possible. We've declared a special `Struct` for you to use for this purpose.
+
+Firstly you need to allow nested Strong Parameters for the `position` column like so:
+
+```ruby
+def item_params
+  params.require(:item).permit :name, position: [:before]
+end
+```
+
+In the example above we're always declaring what item (by its `id`) we want to position our item **before**. You could change this to `:after` if you'd rather.
+
+Next, in your `new` method you may wish to intialise the `position` column with a value supplied by incoming parameters:
+
+```ruby
+def new
+  item.position = { before: params[:before] }
+end
+```
+
+You can now just pass the `before` parameter (the `id` of the item you want to add this record before) via the URL to the `new` action. For example: `items/new?before=22`.
+
+In the form itself, so that your intended position survives a failed `create` attempt and form redisplay you can declare the `position` value like so:
+
+```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 %>
+```
+
+The key part here is `Positioning::RelativePosition.new(item.position_before_type_cast)`. `Positioning::RelativePosition` is a `Struct` that can take `before` and `after` as parameters. You should only provide one or the other. Because `position` is an `Integer` column, the hash structure is obliterated when it is assigned but we can still access it with `position_before_type_cast`. Remember to adjust the method if your position column has a different name (e.g. `category_position_before_type_cast`). The `Struct` provides the correct methods for `fields` to display the nested value.
+
 #### Destroying
 
 When a record is destroyed, the positions of relative items in the scope will be shuffled to close the gap left by the destroyed record. If we detect that records are being destroyed via a scope dependency (e.g. `has_many :items, dependent: :destroy`) then we skip closing the gaps because all records in the scope will eventually be destroyed anyway.

data/lib/positioning/version.rb

@@ -1,3 +1,3 @@
 module Positioning
-  VERSION = "0.1.6"
+  VERSION = "0.1.7"
 end

data/lib/positioning.rb

@@ -7,46 +7,50 @@ require "active_support/lazy_load_hooks"
 module Positioning
   class Error < StandardError; end
 
-  extend ActiveSupport::Concern
+  RelativePosition = Struct.new(:before, :after, keyword_init: true)
 
-  class_methods do
-    def positioning_columns
-      @positioning_columns ||= {}
-    end
+  module Behaviour
+    extend ActiveSupport::Concern
 
-    def positioned(on: [], column: :position)
-      unless base_class?
-        raise Error.new "can't be called on an abstract class or STI subclass."
+    class_methods do
+      def positioning_columns
+        @positioning_columns ||= {}
       end
 
-      column = column.to_sym
+      def positioned(on: [], column: :position)
+        unless base_class?
+          raise Error.new "can't be called on an abstract class or STI subclass."
+        end
 
-      if positioning_columns.key? column
-        raise Error.new "The column `#{column}` has already been used by the scope `#{positioning_columns[column]}`."
-      else
-        positioning_columns[column] = Array.wrap(on).map do |scope_component|
-          scope_component = scope_component.to_s
-          reflection = reflections[scope_component]
+        column = column.to_sym
 
-          (reflection && reflection.belongs_to?) ? reflection.foreign_key : scope_component
-        end
+        if positioning_columns.key? column
+          raise Error.new "The column `#{column}` has already been used by the scope `#{positioning_columns[column]}`."
+        else
+          positioning_columns[column] = Array.wrap(on).map do |scope_component|
+            scope_component = scope_component.to_s
+            reflection = reflections[scope_component]
 
-        define_method(:"prior_#{column}") { Mechanisms.new(self, column).prior }
-        define_method(:"subsequent_#{column}") { Mechanisms.new(self, column).subsequent }
+            (reflection && reflection.belongs_to?) ? reflection.foreign_key : scope_component
+          end
 
-        redefine_method(:"#{column}=") do |position|
-          send :"#{column}_will_change!"
-          super(position)
-        end
+          define_method(:"prior_#{column}") { Mechanisms.new(self, column).prior }
+          define_method(:"subsequent_#{column}") { Mechanisms.new(self, column).subsequent }
+
+          redefine_method(:"#{column}=") do |position|
+            send :"#{column}_will_change!"
+            super(position)
+          end
 
-        before_create { Mechanisms.new(self, column).create_position }
-        before_update { Mechanisms.new(self, column).update_position }
-        after_destroy { Mechanisms.new(self, column).destroy_position }
+          before_create { Mechanisms.new(self, column).create_position }
+          before_update { Mechanisms.new(self, column).update_position }
+          after_destroy { Mechanisms.new(self, column).destroy_position }
+        end
       end
     end
   end
 end
 
 ActiveSupport.on_load :active_record do
-  ActiveRecord::Base.send :include, Positioning
+  ActiveRecord::Base.send :include, Positioning::Behaviour
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: positioning
 version: !ruby/object:Gem::Version
-  version: 0.1.6
+  version: 0.1.7
 platform: ruby
 authors:
 - Brendon Muir