mongoid_slug 0.10.0 → 1.0.0.rc1

data/README.md

@@ -1,3 +1,6 @@
+*IMPORTANT:*  If you are upgrading to Mongoid Slug 0.20.0 please migrate in accordance with the instructions in https://github.com/digitalplaywright/mongoid-slug/wiki/How-to-upgrade-to-0.20.0.
+Mongoid Slug 0.20.0 stores the slugs in a single field _slugs of array type, and all previous slugs must be migrated.
+
 Mongoid Slug
 ============
 
@@ -5,7 +8,7 @@ Mongoid Slug generates a URL slug or permalink based on one or more fields in a
 Mongoid model. It sits idly on top of [stringex] [1], supporting non-Latin
 characters.
 
-[![travis] [2]] [3]
+[![Build Status](https://secure.travis-ci.org/digitalplaywright/mongoid-slug.png)](http://travis-ci.org/digitalplaywright/mongoid-slug)
 
 Installation
 ------------
@@ -31,14 +34,52 @@ class Book
 end
 ```
 
-Find a record by its slug:
+Find a document by its slug:
 
 ```ruby
 # GET /books/a-thousand-plateaus
-book = Book.find_by_slug params[:book_id]
+book = Book.find params[:book_id]
+```
+
+Mongoid Slug will attempt to determine whether you want to find using the `slugs` field or the `_id` field by inspecting the supplied parameters.
+
+* If your document uses `BSON::ObjectId` identifiers, and all arguments passed to `find` are `String` and look like valid `BSON::ObjectId`, then Mongoid Slug will perform a find based on `_id`.
+* If your document uses any other type of identifiers, and all arguments passed to `find` are of the same type, then Mongoid Slug will perform a find based on `_id`.
+* Otherwise, if all arguments passed to `find` are of the type `String`, then Mongoid Slug will perform a find based on `slugs`.
+
+To override this behaviour you may supply a hash of options as the final argument to `find` with the key `force_slugs` set to `true` or `false` as required. For example:
+
+```ruby
+Book.fields['_id'].type
+=> String
+book = Book.find 'a-thousand-plateaus' # Finds by _id
+=> ...
+book = Book.find 'a-thousand-plateaus', { force_slugs: true } # Finds by slugs
+=> ...
 ```
 
-[Read here] [3] for all available options.
+
+[Read here] [4] for all available options.
+
+Custom Slug Generation
+-------
+
+By default Mongoid Slug generates slugs with stringex. If this is not desired you can
+define your own slug generator like this:
+
+```
+class Caption
+  include Mongoid::Document
+  include Mongoid::Slug
+
+  #create a block that takes the current object as an argument
+  #and returns the slug.
+  slug do |cur_object|
+    cur_object.slug_builder.to_url
+  end
+end
+
+```
 
 Scoping
 -------
@@ -109,7 +150,7 @@ page = Page.new title: "Home"
 page.save
 page.update_attributes title: "Welcome"
 
-Page.find_by_slug("welcome") == Page.find_by_slug("home") #=> true
+Page.find("welcome") == Page.find("home") #=> true
 ```
 
 Reserved Slugs
@@ -126,7 +167,7 @@ class Friend
 end
 
 friend = Friend.create name: 'admin'
-Friend.find_by_slug('admin') # => nil
+Friend.find('admin') # => nil
 friend.slug # => 'admin-1'
 ```
 

data/lib/mongoid/slug.rb

@@ -1,41 +1,34 @@
-require 'mongoid'
-require 'stringex'
-
 module Mongoid
-  # The Slug module helps you generate a URL slug or permalink based on one or 
-  # more fields in a Mongoid model.
+  # Slugs your Mongoid model.
   module Slug
     extend ActiveSupport::Concern
 
     included do
-      cattr_accessor :slug_builder,
-                     :slug_name,
-                     :slug_history_name,
+      cattr_accessor :reserved_words,
                      :slug_scope,
-                     :reserved_words_in_slug,
-                     :slugged_attributes
+                     :slugged_attributes,
+                     :url_builder,
+                     :history
+
+      field :_slugs, type: Array, default: []
+      alias_attribute :slugs, :_slugs
     end
 
     module ClassMethods
+
+
       # @overload slug(*fields)
       #   Sets one ore more fields as source of slug.
       #   @param [Array] fields One or more fields the slug should be based on.
       #   @yield If given, the block is used to build a custom slug.
       #
-      # @overload slug(*fields, options) 
+      # @overload slug(*fields, options)
       #   Sets one ore more fields as source of slug.
       #   @param [Array] fields One or more fields the slug should be based on.
       #   @param [Hash] options
-      #   @param options [String] :as The name of the field that stores the
-      #   slug. Defaults to `slug`.
       #   @param options [Boolean] :history Whether a history of changes to
       #   the slug should be retained. When searched by slug, the document now
       #   matches both past and present slugs.
-      #   @param options [Boolean] :index Whether an index should be defined
-      #   on the slug field. Defaults to `false` and has no effect if the
-      #   document is embedded.
-      #   Make sure you have a unique index on the slugs of root documents to
-      #   avoid race conditions.
       #   @param options [Boolean] :permanent Whether the slug should be
       #   immutable. Defaults to `false`.
       #   @param options [Array] :reserve` A list of reserved slugs
@@ -57,176 +50,145 @@ module Mongoid
       #
       def slug(*fields, &block)
         options = fields.extract_options!
-        options[:history] = false if options[:permanent]
-
-        self.slug_scope             = options[:scope]
-        self.reserved_words_in_slug = options[:reserve] || []
-        self.slug_name              = options[:as] || :slug
-        self.slugged_attributes     = fields.map(&:to_s)
-        if options[:history] && !options[:permanent]
-          self.slug_history_name    = "#{self.slug_name}_history".to_sym
-        end
-
-        default_builder = lambda do |doc|
-          slugged_attributes.map { |f| doc.send f }.join ' '
-        end
-        self.slug_builder = block_given? ? block : default_builder
 
-        field slug_name
+        self.slug_scope         = options[:scope]
+        self.reserved_words     = options[:reserve] || Set.new([:new, :edit])
+        self.slugged_attributes = fields.map &:to_s
+        self.history            = options[:history]
 
-        if slug_history_name
-          field slug_history_name, :type => Array, :default => []
+        if slug_scope
+          index({slug_scope: 1, _slugs: 1}, {unique: true})
+        else
+          index({_slugs: 1}, {unique: true})
         end
 
-        if options[:index]
-          index slug_name, :unique => !slug_scope
-          index slug_history_name if slug_history_name
+        #-- Why is it necessary to customize the slug builder?
+        default_url_builder = lambda do |cur_object|
+          cur_object.slug_builder.to_url
         end
 
-        set_callback options[:permanent] ? :create : :save, :before do |doc|
-          doc.build_slug if doc.slug_should_be_rebuilt?
+        self.url_builder = block_given? ? block : default_url_builder
+
+        #-- always create slug on create
+        #-- do not create new slug on update if the slug is permanent
+        if options[:permanent]
+          set_callback :create, :before, :build_slug
+        else
+          set_callback :save, :before, :build_slug, :if => :slug_should_be_rebuilt?
         end
 
-        # Build a finder for slug.
-        #
-        # Defaults to `find_by_slug`.
-        instance_eval <<-CODE
-          def self.find_by_#{slug_name}(slug)
-            if slug_history_name
-              any_of({ slug_name => slug }, { slug_history_name => slug })
-            else
-              where(slug_name => slug)
-            end.first
-          end
 
-          def self.find_by_#{slug_name}!(slug)
-            self.find_by_#{slug_name}(slug) ||
-              raise(Mongoid::Errors::DocumentNotFound.new self, slug)
-          end
-        CODE
+      end
 
-        # Build a scope based on the slug name.
-        #
-        # Defaults to `by_slug`.
-        scope "by_#{slug_name}".to_sym, lambda { |slug|
-          if slug_history_name
-            any_of({ slug_name => slug }, { slug_history_name => slug })
-          else
-            where(slug_name => slug)
-          end
-        }
+      def look_like_slugs?(*args)
+        with_default_scope.look_like_slugs?(*args)
       end
-      
-      # Finds a unique slug, were specified string used to generate a slug.
+
+
+
+      # Find documents by slugs.
       #
-      # Returned slug will the same as the specified string when there are no
-      # duplicates.
+      # A document matches if any of its slugs match one of the supplied params.
       #
-      # @param [String] desired_slug
-      # @param [Hash] options
-      # @param options [Symbol] :scope The scope that should be used to
-      # generate the slug, if the class creates scoped slugs. Defaults to
-      # `nil`.
-      # @param options [Constant] :model The model that the slug should be 
-      # generated for. This option overrides `:scope`, as the scope can now 
-      # be extracted from the model. Defaults to `nil`.
-      # @return [String] A unique slug
-      def find_unique_slug_for(desired_slug, options = {})
-        if slug_scope && self.reflect_on_association(slug_scope).nil?
-          scope_object    = uniqueness_scope(options[:model])
-          scope_attribute = options[:scope] || options[:model].try(:read_attribute, slug_scope)
-        else
-          scope_object = options[:scope] || uniqueness_scope(options[:model])
-          scope_attribute = nil
-        end
-        
-        excluded_id = options[:model]._id if options[:model]
-        
-        slug = desired_slug.to_url
-        
-        # Regular expression that matches slug, slug-1, ... slug-n
-        # If slug_name field was indexed, MongoDB will utilize that
-        # index to match /^.../ pattern.
-        pattern = /^#{Regexp.escape(slug)}(?:-(\d+))?$/
-
-        if slug_scope &&
-           self.reflect_on_association(slug_scope).nil?
-          # scope is not an association, so it's scoped to a local field
-          # (e.g. an association id in a denormalized db design)
-
-          where_hash = {}
-          where_hash[slug_name]  = pattern
-          where_hash[:_id.ne]    = excluded_id if excluded_id
-          where_hash[slug_scope] = scope_attribute
-
-          existing_slugs =
-            deepest_document_superclass.
-            only(slug_name).
-            where(where_hash)
-        else
-          where_hash = {}
-          where_hash[slug_name] = pattern
-          where_hash[:_id.ne]   = excluded_id if excluded_id
-
-          existing_slugs =
-            scope_object.
-            only(slug_name).
-            where(where_hash)
-        end    
-
-        existing_slugs = existing_slugs.map do |doc|
-          doc.slug
-        end
+      # A document matching multiple supplied params will be returned only once.
+      #
+      # If any supplied param does not match a document a Mongoid::Errors::DocumentNotFound will be raised.
+      #
+      # @example Find by a slug.
+      #   Model.find_by_slug!('some-slug')
+      #
+      # @example Find by multiple slugs.
+      #   Model.find_by_slug!('some-slug', 'some-other-slug')
+      #
+      # @param [ Array<Object> ] args The slugs to search for.
+      #
+      # @return [ Array<Document>, Document ] The matching document(s).
+      def find_by_slug!(*args)
+        with_default_scope.find_by_slug!(*args)
+      end
 
-        if slug_history_name
-          if slug_scope &&
-             self.reflect_on_association(slug_scope).nil?
-            # scope is not an association, so it's scoped to a local field
-            # (e.g. an association id in a denormalized db design)
+      def queryable
+        scope_stack.last || Criteria.new(self) # Use Mongoid::Slug::Criteria for slugged documents.
+      end
 
-            where_hash = {}
-            where_hash[slug_history_name.all] = [pattern]
-            where_hash[:_id.ne]               = excluded_id if excluded_id
-            where_hash[slug_scope]            = scope_attribute
+    end
 
-            history_slugged_documents =
-              deepest_document_superclass.
-              where(where_hash)
-          else
-            where_hash = {}
-            where_hash[slug_history_name.all] = [pattern]
-            where_hash[:_id.ne]               = excluded_id if excluded_id
+    # Builds a new slug.
+    #
+    # @return [true]
+    def build_slug
+      _new_slug = find_unique_slug
+      self._slugs.delete(_new_slug)
+      if self.history == true
+        self._slugs << _new_slug
+      else
+        self._slugs = [_new_slug]
+      end
+      true
+    end
+
+
+    # Finds a unique slug, were specified string used to generate a slug.
+    #
+    # Returned slug will the same as the specified string when there are no
+    # duplicates.
+    #
+    # @param [String] Desired slug
+    # @return [String] A unique slug
+    def find_unique_slug
+
+      _slug = self.url_builder.call(self)
 
-            history_slugged_documents =
-              scope_object.
+      # Regular expression that matches slug, slug-1, ... slug-n
+      # If slug_name field was indexed, MongoDB will utilize that
+      # index to match /^.../ pattern.
+      pattern = /^#{Regexp.escape(_slug)}(?:-(\d+))?$/
+
+      where_hash = {}
+      where_hash[:_slugs.all] = [pattern]
+      where_hash[:_id.ne]               = self._id
+
+      if slug_scope && self.reflect_on_association(slug_scope).nil?
+        # scope is not an association, so it's scoped to a local field
+        # (e.g. an association id in a denormalized db design)
+        where_hash[slug_scope]            = self.try(:read_attribute, slug_scope)
+
+      end
+
+      history_slugged_documents =
+          uniqueness_scope.
               where(where_hash)
-          end
 
-          existing_history_slugs = []
-          history_slugged_documents.each do |doc|
-            history_slugs = doc.read_attribute(slug_history_name)
-            next if history_slugs.nil?
-            existing_history_slugs.push(*history_slugs.find_all { |slug| slug =~ pattern })
-          end
+      existing_slugs = []
+      existing_history_slugs = []
+      last_entered_slug = []
+      history_slugged_documents.each do |doc|
+        history_slugs = doc._slugs
+        next if history_slugs.nil?
+        existing_slugs.push(*history_slugs.find_all { |cur_slug| cur_slug =~ pattern })
+        last_entered_slug.push(*history_slugs.last) if history_slugs.last =~ pattern
+        existing_history_slugs.push(*history_slugs.first(history_slugs.length() -1).find_all { |cur_slug| cur_slug =~ pattern })
+      end
 
-          # If the only conflict is in the history of a document in the same scope,
-          # transfer the slug
-          if slug_scope && existing_slugs.count == 0 && existing_history_slugs.count > 0
-            history_slugged_documents.each do |doc|
-              doc_history_slugs = doc.read_attribute(slug_history_name)
-              next if doc_history_slugs.nil?
-              doc_history_slugs -= existing_history_slugs
-              doc.write_attribute(slug_history_name, doc_history_slugs)
-              doc.save
-            end
-            existing_history_slugs = []
-          end
+      #do not allow a slug that can be interpreted as the current document id
+      existing_slugs << _slug unless self.class.look_like_slugs?([_slug])
 
-          existing_slugs += existing_history_slugs
-        end   
+      #make sure that the slug is not equal to a reserved word
+      if reserved_words.any? { |word| word === _slug }
+        existing_slugs << _slug
+      end
 
-        if reserved_words_in_slug.any? { |word| word === slug }
-          existing_slugs << slug
+      #only look for a new unique slug if the existing slugs contains the current slug
+      # - e.g if the slug 'foo-2' is taken, but 'foo' is available, the user can use 'foo'.
+      if existing_slugs.include? _slug
+        # If the only conflict is in the history of a document in the same scope,
+        # transfer the slug
+        if slug_scope && last_entered_slug.count == 0 && existing_history_slugs.count > 0
+          history_slugged_documents.each do |doc|
+            doc._slugs -= existing_history_slugs
+            doc.save
+          end
+          existing_slugs = []
         end
 
         if existing_slugs.count > 0
@@ -235,119 +197,90 @@ module Mongoid
           # slug, slug-1, slug-2, ..., slug-n
           existing_slugs.sort! do |a, b|
             (pattern.match(a)[1] || -1).to_i <=>
-            (pattern.match(b)[1] || -1).to_i
+                (pattern.match(b)[1] || -1).to_i
           end
           max = existing_slugs.last.match(/-(\d+)$/).try(:[], 1).to_i
 
-          slug += "-#{max + 1}"
-        end
-
-        slug
-      end
-      
-      private
-      
-      def uniqueness_scope(model = nil)  
-        if model
-          if slug_scope && (metadata = self.reflect_on_association(slug_scope))
-            parent = model.send(metadata.name)
-
-            # Make sure doc is actually associated with something, and that
-            # some referenced docs have been persisted to the parent
-            #
-            # TODO: we need better reflection for reference associations,
-            # like association_name instead of forcing collection_name here
-            # -- maybe in the forthcoming Mongoid refactorings?
-            inverse = metadata.inverse_of || collection_name
-            return parent.respond_to?(inverse) ? parent.send(inverse) : self
-          end
-          if embedded?
-            parent_metadata = reflect_on_all_associations(:embedded_in)[0]
-            return model._parent.send(parent_metadata.inverse_of || model.metadata.name)
-          end
+          _slug += "-#{max + 1}"
         end
-        deepest_document_superclass
-      end
-      
-      def deepest_document_superclass
-        appropriate_class = self
-        while appropriate_class.superclass.include?(Mongoid::Document)
-          appropriate_class = appropriate_class.superclass
-        end
-        appropriate_class
-      end
-    end
 
-    # Builds a new slug.
-    #
-    # @return [true]
-    def build_slug
-      old = slug
-      write_attribute slug_name, find_unique_slug
-      
-      # @note I find it odd that we can't use `slug_was`, `slug_changed?`, or
-      # `read_attribute (slug_history_name)` here.
-
-      if slug_history_name && old && old != slug
-        self.send(slug_history_name).<<(old).uniq!
       end
 
-      true
+      _slug
     end
 
-    # Finds a unique slug, were specified string used to generate a slug.
-    #
-    # Returned slug will the same as the specified string when there are no
-    # duplicates.
-    #
-    # @param [String] Desired slug
-    # @return [String] A unique slug
-    def find_unique_slug_for(desired_slug)
-      self.class.find_unique_slug_for desired_slug, :model => self
-    end
 
     # @return [Boolean] Whether the slug requires to be rebuilt
     def slug_should_be_rebuilt?
-      new_record? or slug_changed? or slugged_attributes_changed?
-    end
-
-    unless self.respond_to? :slug
-      def slug
-        read_attribute slug_name
-      end
-
-      def slug_changed?
-        attribute_changed? slug_name
-      end
-
-      def slug_was
-        attribute_was slug_name
-      end
+      new_record? or _slugs_changed? or slugged_attributes_changed?
     end
 
     def slugged_attributes_changed?
-      slugged_attributes.any? { |f| attribute_changed? f }
+      slugged_attributes.any? { |f| attribute_changed? f.to_s }
     end
 
     # @return [String] A string which Action Pack uses for constructing an URL
     # to this record.
     def to_param
-      unless slug
+      unless _slugs.last
         build_slug
         save
       end
 
-      slug
+      _slugs.last
     end
-    
-    private
+    alias_method :slug, :to_param
 
-    def find_unique_slug
-      find_unique_slug_for user_defined_slug || slug_builder.call(self)
+    def slug_builder
+
+      _cur_slug = nil
+      if (new_record? and _slugs.present?) or (persisted? and _slugs_changed?)
+        #user defined slug
+        _cur_slug =  _slugs.last
+      end
+
+      #generate slug if the slug is not user defined or does not exist
+      unless _cur_slug
+        self.slugged_attributes.map { |f| self.send f }.join ' '
+      else
+        _cur_slug
+      end
     end
 
-    def user_defined_slug
-      slug if new_record? and slug.present? or slug_changed?
+    private
+
+    def uniqueness_scope
+
+      if slug_scope &&
+          metadata = self.reflect_on_association(slug_scope)
+
+        parent = self.send(metadata.name)
+
+        # Make sure doc is actually associated with something, and that
+        # some referenced docs have been persisted to the parent
+        #
+        # TODO: we need better reflection for reference associations,
+        # like association_name instead of forcing collection_name here
+        # -- maybe in the forthcoming Mongoid refactorings?
+        inverse = metadata.inverse_of || collection_name
+        return parent.respond_to?(inverse) ? parent.send(inverse) : self.class
+
+      end
+
+      if self.embedded?
+        parent_metadata = reflect_on_all_associations(:embedded_in)[0]
+        return self._parent.send(parent_metadata.inverse_of || self.metadata.name)
+      end
+
+      #unless embedded or slug scope, return the deepest document superclass
+      appropriate_class = self.class
+      while appropriate_class.superclass.include?(Mongoid::Document)
+        appropriate_class = appropriate_class.superclass
+      end
+      appropriate_class
+
     end
+
   end
 end
+