mongoid-lookup 0.0.1

data/README.md

@@ -0,0 +1,276 @@
+
+Mongoid::Lookup
+===============
+
+Mongoid::Lookup is an extension for the Mongoid ODM providing
+support for cross-model document lookups. It has a broad range of applications
+including versatile app-wide search. Mongoid::Lookup leverages
+Mongoid's polymorphism support to provide intuitive filtering by model.
+
+Simple Lookup
+-------------
+
+An ideal use for Mongoid::Lookup is cross-model search, i.e. the 
+Facebook search box which returns Users, Groups, Pages, Topics, etc.
+
+To begin, define a collection to use as a root for your lookup:
+
+    require 'mongoid_lookup'
+  
+    class SearchListing
+      include Mongoid::Document
+      include Mongoid::Lookup
+    
+      lookup_collection
+    
+      field :label, type: String
+    end
+    
+Next, for each model you'd like to reference in the `SearchListing` collection,
+add a `has_lookup` relationship:
+
+    class User
+      include Mongoid::Document
+      include Mongoid::Lookup
+      
+      has_lookup :search, collection: SearchListing, map: { label: :full_name }
+      
+      field :full_name, type: String
+    end
+    
+`has_lookup` does more than just add a relation to `SearchListing`. It actually creates
+a new model extending `SearchListing`, which you can access by passing the name of the relation
+to the `lookup` method:
+
+    User.lookup(:search) #=> User::SearchReference
+    User::SearchReference.superclass #=> SearchListing
+    
+Mongoid::Lookup will now maintain a reference document through the `User#search_reference` relation.
+The `:map` option matches fields in `User::SearchReference` to fields in `User`.
+`User::SearchReference#label` will be `User#full_name`. Whenever the user changes its name, 
+its `#search_reference` will be updated:
+
+    user = User.create(full_name: 'John Doe')
+    user.search_reference #=> #<User::SearchReference label: "John Doe">
+    user.update_attributes(full_name: "Jack Doe")
+    user.search_reference.reload #=> #<User::SearchReference label: "Jack Doe">
+
+The lookup collection won't be particularly useful, though, until you add more models:
+
+    class Group
+      include Mongoid::Document
+      include Mongoid::Lookup
+      has_lookup :search, collection: SearchListing, map: { label: :name }
+      field :name, type: String
+    end
+    
+    class Page
+      include Mongoid::Document
+      include Mongoid::Lookup
+      has_lookup :search, collection: SearchListing, map: { label: :title }
+      field :title, type: String
+    end
+    
+References in the lookup collection relate back to the source document, `referenced`:
+
+    User.create(full_name: 'John Doe')
+    listing = SearchListing.all.first
+    listing.referenced #=> #<User _id: 4f418f237742b50df7000001, _type: "User", name: "John Doe">
+    
+Now, you can add whatever functionality desired to your lookup collection. In our example,
+we'd like to implement cross-model search:
+
+    class SearchListing
+      scope :label_like, ->(query) { where(label: Regexp.new(/#{query}/i)) }
+    end
+    
+    SearchListing.label_like("J")
+    #=> [ #<User::SearchReference label: "J User">, <Group::SearchReference label: "J Group">, <Page::SearchReference label: "J Page">  ]
+
+Advanced Lookup
+---------------
+
+Building on the simple search example, suppose you have a structured tagging system:
+
+    class Tag
+      include Mongoid::Document
+    end
+    class Person < Tag; end
+    class Topic < Tag; end
+    class Place < Tag; end
+    class City < Place; end
+    class Region < Place; end
+    class Country < Place; end
+    
+Sometimes you'll want results across all models (User, Group, Page, Tag)
+but at other times you may only be interested in Tags, or even just Places. 
+Mongoid makes type filtering easy, and Mongoid::Lookup leverages this feature.
+
+Begin by defining a lookup on your parent class:
+
+    class Tag
+      include Mongoid::Lookup
+      has_lookup :search, collection: SearchListing, map: { label: :name }
+      field :name, type: String
+    end
+
+Mongoid::Lookup allows you to directly query just for tags:
+
+    Tag.lookup(:search).label_like("B")
+    #=> [ #<Topic::SearchReference label: "Business">, <Person::SearchReference label: "Barack Obama">, <City::SearchReference label: "Boston">  ] 
+
+Alternatively, you can access the model by its constant, which has been named according to the
+key `"#{name.to_s.classify}Reference"`:
+
+    Tag::SearchReference.label_like(query)
+
+`has_lookup :screen_name` would generate a reference model `Tag::ScreenNameReference`:
+
+### Lookup Inheritance 
+
+What if you're only interested in Places?
+
+Your `Place` model can define its own lookup. 
+Use the `inherit: true` option in any child class
+to create a finer grained lookup:
+
+    class Place < Tag
+      has_lookup :search, inherit: true
+    end
+    
+The new lookup will inherit the configuration of Tag's `:search` lookup. Now you
+can query Place references only, as needed:
+
+    Place.lookup(:search).label_like("C")
+    #=> [ #<Country::SearchReference label: "Canada">, <Region::SearchReference label: "California">, <City::SearchReference label: "Carson City">  ] 
+    
+or 
+
+    Place::SearchReference.label_like("C")
+    
+This does not effect SearchListing or Tag::SearchReference. Mongoid knows
+hows to limit the query.
+      
+### Extending Lookup Reference Models
+
+If you would like your lookup references to maintain more data from your source model,
+add the desired fields to the lookup collection:
+
+    class SearchListing
+      field :alias, type: String
+    end
+    
+Now update your `:map` option in your lookup declarations:
+    
+    class User
+      has_lookup :search, collection: SearchListing, map: { label: :full_name, alias: :nickname }
+      field :full_name, type: String
+      field :nickname, type: String
+    end
+    
+The `#search_reference` will be updated whenever `#full_name` or `#nickname` are changed.
+
+If you would like to include fields that only pertain to certain models, pass a block to
+your `has_lookup` call. It will be evaluated in the context of the reference class. 
+The following:
+
+    class Place < Tag
+
+      has_lookup :search, inherit: true, map: { population: :population } do
+        # this block is evaluated 
+        # in Place::SearchReference
+        field :population, type: Integer
+      end
+      
+      field :population, type: Integer
+    end
+    
+...adds a `Place::SearchReference#population` field and maps it to `Place#population`.
+This additional field and mapping will only exist to `Place` and its child classes.
+
+Anytime that you define a lookup, the parent configurations (fields and mappings) will
+be inherited, and the new ones added:
+
+    class City < Place
+    
+      has_lookup :search, inherit: true, map: { code: :zipcode } do
+        # this block is evaluated 
+        # in City::SearchReference
+        field :code, type: Integer
+      end
+    
+      field :zipcode, type: Integer
+    end
+    
+`City::SearchReference` will maintain `#label`, `#population`, and `#code`, as per mappings
+given in `Tag`, `Place`, and `City`.
+
+The ability to subclass lookup references allows for some flexibility. For instance,
+if you'd like search references to provide a `#summary` method:
+
+    class SearchListing
+      lookup_collection
+    
+      def summary
+        referenced_type.name
+      end
+    end
+    
+    class Place < Tag
+      has_lookup :search, inherit: true, map: { population: :population } do
+        field :population, type: Integer
+        
+        def summary
+          super + " of population #{population}"
+        end
+      end
+    end
+
+    Topic.create(title: "Politics")
+    City.create(name: 'New York City', population: 8125497)
+    
+    SearchListing.all.each do |listing|
+      puts "#{listing.label} + (#{listing.summary})"
+    end
+    
+    #=> "Politics (Topic)"
+    #=> "New York City (City of population 8125497)"
+    
+Notes
+-----
+
+Presumably, write heavy fields aren't great candidates for lookup. Every time
+the field changes, the lookup reference will have to be updated.
+
+The update currently takes place in a `before_save` callback. If performance were a
+concern, the hook could instead create a delayed job to update the lookup (not currently supported).
+
+Authors
+-------
+
+* [Jeff Magee](http://github.com/jmagee) (jmagee.osrc at gmail dot com)
+
+
+License
+-------
+
+Copyright (c) 2012 Jeff Magee
+
+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/lib/mongoid_lookup/collection.rb

@@ -0,0 +1,27 @@
+
+module Mongoid #:nodoc:
+  module Lookup #:nodoc:
+    
+    module Collection
+      extend ActiveSupport::Concern
+      
+      module ClassMethods
+        
+        # configure the lookup collection
+        def build_lookup_collection
+          relate_lookup_collection
+        end
+        
+        # add polymorphic relation to referenced document
+        #
+        # @private
+        def relate_lookup_collection
+          belongs_to :referenced, :polymorphic => true
+        end
+        
+      end
+      
+    end
+    
+  end
+end

data/lib/mongoid_lookup/model.rb

@@ -0,0 +1,155 @@
+
+module Mongoid #:nodoc:
+  module Lookup #:nodoc:
+
+    class InheritError < StandardError; end
+    
+    module Model
+      extend ActiveSupport::Concern
+      
+      # create or update the lookup reference if 
+      # changes are present
+      #
+      # @param [Symbol] name name of lookup reference to update
+      def maintain_lookup_reference name
+        if has_lookup_changes?(name)
+          attrs = lookup_reference_attributes(name)
+          
+          if ref = send("#{name}_reference")
+            ref.update_attributes(attrs)
+          else
+            send("create_#{name}_reference", attrs)
+          end
+        end
+      end
+      
+      # checks for dirty fields on the given lookup 
+      #
+      # @param [Symbol] name name of lookup to check
+      # @return [Boolean]
+      def has_lookup_changes? name
+        lookup_fields = self.class.lookup_fields(name)
+        changed_fields = changes.keys
+        (changed_fields - lookup_fields).count < changed_fields.count
+      end
+      
+      # the attributes required for the given lookup reference
+      #
+      # @param [Symbol] name name of lookup to check
+      # @return [Hash]
+      def lookup_reference_attributes name
+        {}.tap do |attrs|
+          map = self.class.lookup(name).lookup_field_map.invert
+          map.keys.each do |source_field|
+            attrs[map[source_field]] = read_attribute(source_field)
+          end
+        end
+      end
+      
+      module ClassMethods
+        
+        # Create a lookup of the given name on the host model.
+        #
+        # @param [Symbol] name name of lookup
+        # @param [Hash] options
+        # @option options [Mongoid::Document] :collection
+        def build_lookup name, options, &block;
+          define_lookup_reference(name, options, &block)
+          relate_lookup_reference(name, options)
+          attach_lookup_reference_callback(name, options)
+        end
+        
+        # Create a class to serve as the model for the lookup
+        # reference. Const is set within the current model.
+        #
+        # @private
+        def define_lookup_reference name, options, &block;
+          const_set("#{name.to_s.classify}Reference", Class.new(lookup_reference_parent(name, options)))
+          lookup(name).send(:include, Reference) unless included_modules.include?(Reference)
+          lookup(name).configure_lookup_reference(options)
+          if block_given?
+            lookup(name).class_eval(&block)
+          end
+        end
+        
+        # lookup reference class for the given lookup name
+        # 
+        # @param [String, Symbol] name
+        # @return [Mongoid::Lookup::Reference]
+        def lookup name
+          const_get("#{name.to_s.classify}Reference")
+        end
+        
+        # the fields on the Model which map to fields on the
+        # lookup reference 
+        #
+        # @param [Symbol] name
+        # @return [Array<String>]
+        def lookup_fields(name)
+          lookup(name).lookup_field_map.values.collect{ |v| v.to_s }
+        end
+        
+        # whether or not the given lookup is defined
+        # 
+        # @param [String, Symbol] name
+        # @return [Boolean]
+        def has_lookup? name
+          const_defined?("#{name.to_s.classify}Reference")
+        end
+        
+        # returns the appropriate lookup reference parent for 
+        # the given options
+        # 
+        # @private
+        # @param [String, Symbol] name
+        # @param [Array] options
+        # @return [Mongoid::Lookup::Collection, Mongoid::Lookup::Reference]
+        # @raise KeyError if not inheriting and collection is not given
+        def lookup_reference_parent name, options
+          options[:inherit] ? nearest_lookup_reference(name) : options.fetch(:collection)
+        end
+        
+        # returns the lookup reference for the given name
+        # belonging to the nearest ancestor of the calling class.
+        # 
+        # @private
+        # @param [String, Symbol] name
+        # @return [Mongoid::Lookup::Reference]
+        def nearest_lookup_reference name
+          (ancestors - included_modules).each do |klass|
+            if klass.respond_to?(:has_lookup?)
+              if klass.has_lookup?(name)
+                return klass.lookup(name)
+              end
+            end
+          end
+          
+          raise InheritError, "no ancestor of #{self.name} has a lookup named '#{name}'"
+        end
+        
+        # relate the Model to the created lookup Reference
+        #
+        # @private
+        def relate_lookup_reference name, options
+          has_one "#{name}_reference".to_sym, :as => :referenced, :class_name => lookup(name).name, :dependent => :destroy
+        end
+        
+        # add a save hook for the given reference unless 
+        # already defined (inheriting)
+        #
+        # @private
+        def attach_lookup_reference_callback name, options
+          return if options[:inherit]
+          
+          set_callback :save, :before do
+            maintain_lookup_reference(name)
+            true
+          end
+        end
+        
+      end
+        
+    end
+    
+  end
+end

data/lib/mongoid_lookup/reference.rb

@@ -0,0 +1,34 @@
+
+module Mongoid #:nodoc:
+  module Lookup #:nodoc:
+    
+    module Reference
+      extend ActiveSupport::Concern
+      
+      module ClassMethods
+        
+        # @param [Array] options
+        # @option options [Hash] :map
+        def configure_lookup_reference options
+          resolve_lookup_field_map(options)
+        end
+        
+        # inherit field map and merge new fields
+        #
+        # @private
+        def resolve_lookup_field_map options
+          map = (superclass.instance_variable_get(:@field_map) or {}).dup.merge((options[:map] or {}))
+          instance_variable_set(:@field_map, map)
+        end
+        
+        # @return [Hash] map of source fields to reference fields
+        def lookup_field_map
+          instance_variable_get(:@field_map)
+        end
+        
+      end
+      
+    end
+    
+  end
+end

data/lib/mongoid_lookup.rb

@@ -0,0 +1,29 @@
+
+require 'mongoid_lookup/collection'
+require 'mongoid_lookup/model'
+require 'mongoid_lookup/reference'
+
+module Mongoid #:nodoc:
+  module Lookup #:nodoc:
+    extend ActiveSupport::Concern
+    
+    module ClassMethods
+      
+      # Configures calling model as a lookup collection
+      def lookup_collection
+        include Collection
+        build_lookup_collection
+      end
+      
+      # Configures lookup on calling model.
+      # accepts a block which will be evaluated
+      # in the class of the generated lookup reference model
+      def has_lookup name, options, █
+        include Model unless included_modules.include?(Model)
+        build_lookup(name, options, &block)
+      end
+      
+    end
+    
+  end
+end

metadata

@@ -0,0 +1,102 @@
+--- !ruby/object:Gem::Specification 
+name: mongoid-lookup
+version: !ruby/object:Gem::Version 
+  prerelease: 
+  version: 0.0.1
+platform: ruby
+authors: 
+- Jeff Magee
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2012-03-12 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: mongoid
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: "2.4"
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: "2.6"
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: redcarpet
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: "2.1"
+  type: :development
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: yard
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.7.5
+  type: :development
+  version_requirements: *id004
+description: Mongoid::Lookup is an extension for the Mongoid ODM providing support for cross-model document lookups.
+email: jmagee.osrc@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/mongoid_lookup/collection.rb
+- lib/mongoid_lookup/model.rb
+- lib/mongoid_lookup/reference.rb
+- lib/mongoid_lookup.rb
+- README.md
+homepage: https://github.com/jmagee/mongoid-lookup
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.8.17
+signing_key: 
+specification_version: 3
+summary: Cross-model lookup support for Mongoid
+test_files: []
+
+has_rdoc: