mongoid_slug 0.6.4 → 0.7.0

data/README.md

@@ -2,10 +2,9 @@ Mongoid Slug
 ============
 
 Mongoid Slug generates a URL slug or permalink based on one or more
-fields in a Mongoid model.
+fields in a Mongoid model. It sits idly on top of [stringex](https://github.com/rsl/stringex) and works with non-Latin characters.
 
-It sits idly on top of [stringex](https://github.com/rsl/stringex) and
-works with non-Latin characters.
+![lacan](http://upload.wikimedia.org/wikipedia/commons/thumb/5/5d/Nus_borromeu_1.jpg/360px-Nus_borromeu_1.jpg)
 
 Quick Start
 -----------
@@ -14,7 +13,7 @@ Add mongoid_slug to your Gemfile:
 
     gem 'mongoid_slug', :require => 'mongoid/slug'
 
-Set up slugs in models like this:
+Set up some slugs:
 
     class Book
       include Mongoid::Document
@@ -37,36 +36,20 @@ Set up slugs in models like this:
       slug :first, :last, :as => :name
     end
 
-Finder
-------
-
-In your controller, throw in some minimal magic:
+In your controller, use available finders:
 
     # GET /books/a-thousand-plateaus/authors/gilles-deleuze
     author = Book.find_by_slug(params[:book_id]).
                   authors.
                   find_by_name(params[:id])
 
-Permanence
-----------
-
-By default, slugs are not permanent:
-
-    >> book = Book.create(:title => "A Thousand Plateaus")
-    >> book.to_param
-    "a-thousand-plateaus"
-    >> book.title = "Anti Oedipus"
-    >> book.save
-    >> book.to_param
-    "anti-oedipus"
-
-If you require permanent slugs, pass the `:permanent` option when
-defining the slug.
+[Read here](https://github.com/papercavalier/mongoid-slug/blob/master/lib/mongoid/slug.rb)
+for all available options.
 
-Scope
------
+Scoping
+-------
 
-To scope an object by a reference association, pass `:scope`:
+To scope a slug by a reference association, pass `:scope`:
 
     class Company
       include Mongoid::Document
@@ -88,18 +71,3 @@ Currently, if you have an irregular association name, you **must**
 specify the `:inverse_of` option on the other side of the assocation.
 
 Embedded objects are automatically scoped by their parent.
-
-Indexes
--------
-
-You may optionally pass an `:index` option to define an index on top-level
-slugs.
-
-    class Book
-      field :title
-      slug  :title, :index => true
-    end
-
-Indexes on unscoped slugs will be unique.
-
-This option has no effect if the object is embedded.

data/lib/mongoid/slug.rb

@@ -2,52 +2,82 @@ require 'stringex'
 
 module Mongoid #:nodoc:
 
-  # Generates a URL slug or permalink based on one or more fields in a Mongoid
-  # model.
+  # The slug module helps you generate a URL slug or permalink based on one or
+  # more fields in a Mongoid model.
+  #
+  #    class Person
+  #      include Mongoid::Document
+  #      include Mongoid::Slug
+  #
+  #      field :name
+  #      slug :name
+  #    end
+  #
   module Slug
     extend ActiveSupport::Concern
 
     included do
-      cattr_accessor :slug_name, :slugged_fields, :slug_scope
+      cattr_accessor :slug_builder, :slugged_fields, :slug_name, :slug_scope
     end
 
     module ClassMethods
 
       # Sets one ore more fields as source of slug.
       #
-      # By default, the name of the field that stores the slug is "slug". Pass an
-      # alternative name with the :as option.
+      # Takes a list of one or more fields to slug and an optional options
+      # hash.
       #
-      # If you wish the slug to be permanent once created, set :permanent to true.
+      # The options hash respects the following members:
       #
-      # To index slug in a top-level object, set :index to true.
-      def slug(*fields)
+      # * `:as`, which specifies name of the field that stores the slug.
+      # Defaults to `slug`.
+      #
+      # * `:scope`, which specifies a reference association to scope the slug
+      # by. Embedded documents are by default scoped by their parent.
+      #
+      # * `:permanent`, which specifies whether the slug should be immutable
+      # once created. Defaults to `false`.
+      #
+      # * `:index`, which specifies whether an index should be defined for the
+      # slug. Defaults to `false` and has no effect if the document is em-
+      # bedded.
+      #
+      # Alternatively, this method can be given a block to build a custom slug
+      # out of the specified fields.
+      #
+      # The block takes a single argument, the document itself, and should
+      # return a string that will serve as the base of the slug.
+      #
+      # Here, for instance, we slug an array field.
+      #
+      #     class Person
+      #      include Mongoid::Document
+      #      include Mongoid::Slug
+      #
+      #      field :names, :type => Array
+      #      slug :names do |doc|
+      #        doc.names.join(' ')
+      #      end
+      #
+      def slug(*fields, &block)
         options = fields.extract_options!
-
-        self.slug_name      = options[:as] || :slug
-        self.slug_scope     = options[:scope] || nil
-
-        class_eval <<-CODE
-          def slug_any?
-            #{!!options[:any]}
-          end
-        CODE
-
+        self.slug_scope = options[:scope]
+        self.slug_name = options[:as] || :slug
         self.slugged_fields = fields
 
-        if options[:scoped]
-          ActiveSupport::Deprecation.warn <<-EOM
-
-            The :scoped => true option is deprecated and now default for embedded
-            child documents. Please use :scope => :association_name if you wish
-            to scope by a reference association.
-          EOM
-        end
+        self.slug_builder =
+          if block_given?
+            block
+          else
+            lambda do |doc|
+              slugged_fields.map { |f| doc.send(f) }.join(',')
+            end
+          end
 
         field slug_name
 
         if options[:index]
-          index slug_name, :unique => !slug_scope
+          index(slug_name, :unique => !slug_scope)
         end
 
         if options[:permanent]
@@ -56,9 +86,12 @@ module Mongoid #:nodoc:
           before_save :generate_slug
         end
 
+        # Build a finder based on the slug name.
+        #
+        # Defaults to `find_by_slug`.
         instance_eval <<-CODE
           def self.find_by_#{slug_name}(slug)
-            where(slug_name => slug).first rescue nil
+            where(slug_name => slug).first
           end
         CODE
       end
@@ -66,23 +99,21 @@ module Mongoid #:nodoc:
 
     # Regenerates slug.
     #
-    # This method should come in handy when generating slugs for an existing
-    # collection.
+    # Should come in handy when generating slugs for an existing collection.
     def slug!
-      self.send(:generate_slug!)
-      save if self.send("#{slug_name}_changed?")
+      generate_slug!
+      save
     end
 
+    # Returns the slug.
     def to_param
       self.send(slug_name)
     end
 
     private
 
-    attr_reader :slug_counter
-
     def build_slug
-      ("#{slug_base} #{slug_counter}").to_url
+      ("#{slug_builder.call(self)} #{@slug_counter}").to_url
     end
 
     def find_unique_slug
@@ -95,34 +126,22 @@ module Mongoid #:nodoc:
       end
     end
 
-    def generate_slug!
-      self.send("#{slug_name}=", find_unique_slug)
-    end
-
     def generate_slug
-      generate_slug! if new_record? || slugged_fields_changed?
+      if new_record? || slugged_fields_changed?
+        generate_slug!
+      end
     end
 
-    def increment_slug_counter
-      @slug_counter = (slug_counter.to_i + 1).to_s
+    def generate_slug!
+      self.send("#{slug_name}=", find_unique_slug)
     end
 
-    def slug_base
-      values = self.class.slugged_fields.map do |field|
-        self.send(field)
-      end
-
-      if slug_any?
-        values.detect { |value| value.present? }
-      else
-        values.join(' ')
-      end
+    def increment_slug_counter
+      @slug_counter = (@slug_counter.to_i + 1).to_s
     end
 
     def slugged_fields_changed?
-      self.class.slugged_fields.any? do |field|
-        self.send("#{field}_changed?")
-      end
+      slugged_fields.any? { |f| self.send("#{f}_changed?") }
     end
 
     def unique_slug?(slug)

data/lib/mongoid/slug/version.rb

@@ -1,5 +1,5 @@
 module Mongoid #:nodoc:
   module Slug
-    VERSION = '0.6.4'
+    VERSION = '0.7.0'
   end
 end

data/spec/models/article.rb

@@ -3,5 +3,7 @@ class Article
   include Mongoid::Slug
   field :brief
   field :title
-  slug  :title, :brief, :any => true
+  slug  :title, :brief do |doc|
+    [doc.title, doc.brief].reject(&:blank?).first
+  end
 end

data/spec/models/caption.rb

@@ -0,0 +1,10 @@
+class Caption
+  include Mongoid::Document
+  include Mongoid::Slug
+  field :identity
+  field :title
+  field :medium
+  slug :identity, :title do |doc|
+    [doc.identity.gsub(/\s*\([^)]+\)/, ''), doc.title].join(' ')
+  end
+end

data/spec/models/comic_book.rb

@@ -1,3 +1,2 @@
 class ComicBook < Book
-  
-end
+end

data/spec/mongoid/slug_spec.rb

@@ -160,25 +160,6 @@ module Mongoid
 
     end
 
-    context "when :any is passed as an argument" do
-      let!(:article) do
-        Article.create(
-          :brief => "This is the brief",
-          :title => "This is the title")
-      end
-
-      it "uses the first available field for the slug if any option is used" do
-        article.to_param.should eql 'this-is-the-title'
-        article.title = ""
-        article.save
-        article.to_param.should eql 'this-is-the-brief'
-
-        article.title = nil
-        article.save
-        article.to_param.should eql 'this-is-the-brief'
-      end
-    end
-
     context "when :as is passed as an argument" do
       let!(:person) do
         Person.create(:name => "John Doe")
@@ -247,6 +228,34 @@ module Mongoid
       end
     end
 
+    context "when :slug is given a block" do
+      let(:caption) do
+        Caption.create(:identity => 'Edward Hopper (American, 1882-1967)',
+                       :title    => 'Soir Bleu, 1914',
+                       :medium   => 'Oil on Canvas')
+      end
+
+      it "generates a slug" do
+        caption.to_param.should eql 'edward-hopper-soir-bleu-1914'
+      end
+
+      it "updates the slug" do
+        caption.title = 'Road in Maine, 1914'
+        caption.save
+        caption.to_param.should eql "edward-hopper-road-in-maine-1914"
+      end
+
+      it "does not change slug if slugged fields have changed but generated slug is identical" do
+        caption.identity = 'Edward Hopper'
+        caption.save
+        caption.to_param.should eql 'edward-hopper-soir-bleu-1914'
+      end
+
+      it "finds by slug" do
+        Caption.find_by_slug(caption.to_param).should eql caption
+      end
+    end
+
     it "works with non-Latin characters" do
       book.title = "Капитал"
       book.save
@@ -265,16 +274,6 @@ module Mongoid
       book.to_param.should eql 'paul-cezanne'
     end
 
-    it "deprecates the :scoped option" do
-      ActiveSupport::Deprecation.should_receive(:warn)
-      class Oldie
-        include Mongoid::Document
-        include Mongoid::Slug
-        field :name
-        slug  :name, :scoped => true
-      end
-    end
-
     context "when :index is passed as an argument" do
       before do
         Book.collection.drop_indexes
@@ -299,8 +298,6 @@ module Mongoid
           Book.index_information["slug_1"]["unique"].should be_true
         end
       end
-
-      it "has no effect in embedded objects"
     end
 
     context "when :index is not passed as an argument" do
@@ -343,5 +340,12 @@ module Mongoid
         foo.reload.slug.should eql 'john'
       end
     end
+
+    describe ".find_by_slug" do
+      it "returns nil if no document is found" do
+        Book.create(:title => "A Thousand Plateaus")
+        Book.find_by_slug(:title => "Anti Oedipus").should be_nil
+      end
+    end
   end
 end

metadata

@@ -2,7 +2,7 @@
 name: mongoid_slug
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.6.4
+  version: 0.7.0
 platform: ruby
 authors: 
 - Paper Cavalier
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-02-27 00:00:00 +00:00
+date: 2011-03-31 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -21,7 +21,7 @@ dependencies:
     requirements: 
     - - ~>
       - !ruby/object:Gem::Version 
-        version: 2.0.0.rc.7
+        version: 2.0.0
   type: :runtime
   version_requirements: *id001
 - !ruby/object:Gem::Dependency 
@@ -35,50 +35,6 @@ dependencies:
         version: 1.2.0
   type: :runtime
   version_requirements: *id002
-- !ruby/object:Gem::Dependency 
-  name: bson_ext
-  prerelease: false
-  requirement: &id003 !ruby/object:Gem::Requirement 
-    none: false
-    requirements: 
-    - - ~>
-      - !ruby/object:Gem::Version 
-        version: 1.2.0
-  type: :development
-  version_requirements: *id003
-- !ruby/object:Gem::Dependency 
-  name: database_cleaner
-  prerelease: false
-  requirement: &id004 !ruby/object:Gem::Requirement 
-    none: false
-    requirements: 
-    - - ~>
-      - !ruby/object:Gem::Version 
-        version: 0.6.0
-  type: :development
-  version_requirements: *id004
-- !ruby/object:Gem::Dependency 
-  name: rspec
-  prerelease: false
-  requirement: &id005 !ruby/object:Gem::Requirement 
-    none: false
-    requirements: 
-    - - ~>
-      - !ruby/object:Gem::Version 
-        version: 2.4.0
-  type: :development
-  version_requirements: *id005
-- !ruby/object:Gem::Dependency 
-  name: ruby-debug19
-  prerelease: false
-  requirement: &id006 !ruby/object:Gem::Requirement 
-    none: false
-    requirements: 
-    - - ~>
-      - !ruby/object:Gem::Version 
-        version: 0.11.0
-  type: :development
-  version_requirements: *id006
 description: Mongoid Slug generates a URL slug or permalink based on one or more fields in a Mongoid model.
 email: 
 - code@papercavalier.com
@@ -96,6 +52,7 @@ files:
 - spec/models/article.rb
 - spec/models/author.rb
 - spec/models/book.rb
+- spec/models/caption.rb
 - spec/models/comic_book.rb
 - spec/models/partner.rb
 - spec/models/person.rb
@@ -135,6 +92,7 @@ test_files:
 - spec/models/article.rb
 - spec/models/author.rb
 - spec/models/book.rb
+- spec/models/caption.rb
 - spec/models/comic_book.rb
 - spec/models/partner.rb
 - spec/models/person.rb