mongoid_listable 0.0.3 → 0.0.4

data/README.md

@@ -1,39 +1,85 @@
 # Mongoid Listable
 
 Mongoid Listable will eventually be a full replacement library for Mongoid List or Mongoid Orderable. Both 
-libraries fail to accomplish the simple task this library handles: lists that need to be specific for a given `has_many`
-relation.
+libraries fail to accomplish the simple task this library handles: separate position scopes for each
+defined `has_many` / `belongs_to` relation.
 
-## Usage
+## Basic Usage
 
     class User
       include Mongoid::Document
       include Mongoid:Lists
     
       has_many :photos
-      
       lists :photos
-    
+      ...
     end
     
     class Photo
       include Mongoid::Document
       
       belongs_to :user
-    
+      ...
     end
     
-Now, photos that are assigned to a user via by the method `user.photo_ids=[ids]` will maintain position based on the index
+In this example photos that are assigned to a user via by the method `user.photo_ids=[ids]` will maintain position based on the index
 of the id in the array argument.
 
-In this example, each photo object that belongs to the user will obtain a field called `user_position`. The 1-n relation of 
-a user to their photos will automatically be ordered by `user_position` unless otherwise specified. 
+Each photo that belongs to the user will automatically obtain a field called `user_position`. The position field
+is derived from the foreign key of the relation, replacing "_id" with "_position". 
 
-You can also override the name of the position column:
+The 1-n relation of a user to their photos will automatically be ordered by `user_position` unless otherwise specified
+via the standard `order` option to the `has_many` macro. 
+    
+## Complex Relations
+
+    # Handles multiple has_many relations on same model!
+    
+    class User
+      include Mongoid::Document
+      include Mongoid:Lists
+    
+      has_many :featured_photos, 
+      class_name: 'Photo', 
+      inverse_of: :featured_by_user, 
+      foreign_key: :featured_by_user_id
+      
+      has_many :kodak_moments, 
+      class_name: 'Photo', 
+      inverse_of: :kodaked_by_user, 
+      foreign_key: :kodaked_by_user_id
+      
+      lists :featured_photos
+      lists :kodak_moments
+      ...
+    end
+    
+    class Photo
+      include Mongoid::Document
+      
+      belongs_to :featured_by_user, 
+      class_name: 'User', 
+      inverse_of: featured_photos, 
+      foreign_key: :featured_by_user_id
+      
+      belongs_to :kodaked_by_user, 
+      class_name: 'User', 
+      inverse_of: kodak_moments, 
+      foreign_key: :kodaked_by_user_id
+      ...
+    end
+    
+    
+In this example, there are two `has_many` relations defined between a user and photos. Each photo belonging to a user will 
+obtain two position fields: `featured_by_user_position` and `kodaked_by_user_position`.
+
+You can optionally override the name of the position column:
 
     lists :photos, column: :users_photos_order
 
-There's a lot more to add to the library. At this point, it will conveniently handle rails based multiselect form fields.  
+## Todo
+
+There's a lot more to add to the library! At this point, it conveniently handles standard rails-based multiselect form fields.
 
 ## Installation
 

data/lib/mongoid/lists.rb

@@ -11,19 +11,22 @@ module Mongoid
       # Macro to set relation on which to make a list
       #
       # @param [ Symbol ] relation The name of the has_many relation
-      # @param [ Hash ] options The options hash
+      # @param [ Hash ]   options The options hash
       #
       # @return [ Mongoid:Relations:Metadata ] Instance of metadata for the relation
       #
       # @since 0.0.1
-      def lists relation, options={}
-        meta       = reflect_on_association relation
+      def lists name, options={}
+        meta       = reflect_on_association name
         field_name = options[:column] || 
           (meta.foreign_key.to_s.gsub(/_?id$/, '_position')).to_sym
         
 
-        # Override model#{name}_ids=        
-        before_method self, "#{relation.to_s.singularize}_ids=" do |ids|
+        # Override the default ids setter, first setting the correct position
+        # on each relation based on the index of its id in the given array.
+        #
+        # @override model#{name}_ids= 
+        before_method self, "#{name.to_s.singularize}_ids=" do |ids|
           ids.each_with_index do |id, index|
             meta.klass.find(id).update_attribute field_name, index + 1
           end
@@ -33,11 +36,20 @@ module Mongoid
           end
         end
 
-        meta[:order] = "#{field_name} asc"
+        meta[:order] ||= "#{field_name} asc"
       end
 
       private
 
+      # Redefines a method on owner to first execute &block, then
+      # continue executing original method. 
+      #
+      # @param [ Object ] owner  The owner of the method
+      # @param [ String ] method The name of the method to override
+      # @param [ Proc ]   &block The block to execute before original method
+      #
+      # @private
+      # @since 0.0.3
       def before_method owner, method, &block
         original_method = instance_method method
         owner.re_define_method method do |*args|

data/mongoid_listable.gemspec

@@ -4,7 +4,7 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 
 Gem::Specification.new do |spec|
   spec.name          = 'mongoid_listable'
-  spec.version       = '0.0.3'
+  spec.version       = '0.0.4'
   spec.authors       = [ 'richardcalahan' ]
   spec.email         = [ 'richard@calahan.me' ]
   spec.description   = ''

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mongoid_listable
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
   prerelease: 
 platform: ruby
 authors: