mongoid-slug 5.2.0 → 5.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2d38815d369307746d6c796167d08b99aae02f8d
-  data.tar.gz: e0f6c6ba7dc2431fe84de87a6b32dcc90ba1f2ba
+  metadata.gz: bda81e5e78c0e83e9785ff87f5b6e1f6b4ca637a
+  data.tar.gz: f89a8f074c6ac112b65a62b9a0e122cabaef1d54
 SHA512:
-  metadata.gz: c4a7f3f5d7fdf36cb4d64b0ae5bb9f1e35bc6c2dbad3a7d1bbd586ff46b0a0da957bd3762bbe88182595b1aeb9b4e59c6a88bd143bbcdc3f17498c1a60ff82be
-  data.tar.gz: c91cb32733b81ec8b1ace9528bfced0c019aa1fc96d88cc4b6e11d803af0509cee3a0098260de8abcfd7702207deda9cd1c813b3f73f3a12f14930880d08c94c
+  metadata.gz: b30566749607cda56d2b4ed929327978f8997adca09a08a2f66b2b375a5f5485a9967c2c178bf7aa6433d78345d75b814a729f3c98e85f4195e81d1fe9880be8
+  data.tar.gz: 37c91ae5d6984e3403123e7bab3e568cbce7540d002509d5d3bfa396fd2fc72f8d8096498c933dae180aceec8f5edc09fda6e4a5fe1b9c0bbb1a40ed935ce76f

data/README.md

@@ -3,13 +3,12 @@ Mongoid Slug
 
 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](https://github.com/rsl/stringex), supporting non-Latin characters.
 
-[![Build Status](https://secure.travis-ci.org/digitalplaywright/mongoid-slug.svg)](http://travis-ci.org/digitalplaywright/mongoid-slug)
+[![Build Status](https://secure.travis-ci.org/mongoid/mongoid-slug.svg)](http://travis-ci.org/mongoid/mongoid-slug)
 [![Gem Version](https://badge.fury.io/rb/mongoid-slug.svg)](http://badge.fury.io/rb/mongoid-slug)
-[![Dependency Status](https://gemnasium.com/digitalplaywright/mongoid-slug.svg)](https://gemnasium.com/digitalplaywright/mongoid-slug)
-[![Code Climate](https://codeclimate.com/github/digitalplaywright/mongoid-slug.svg)](https://codeclimate.com/github/digitalplaywright/mongoid-slug)
+[![Dependency Status](https://gemnasium.com/mongoid/mongoid-slug.svg)](https://gemnasium.com/mongoid/mongoid-slug)
+[![Code Climate](https://codeclimate.com/github/mongoid/mongoid-slug.svg)](https://codeclimate.com/github/mongoid/mongoid-slug)
 
-Installation
-------------
+### Installation
 
 Add to your Gemfile:
 
@@ -17,10 +16,9 @@ Add to your Gemfile:
 gem 'mongoid-slug'
 ```
 
-Usage
------
+### Usage
 
-Set up a slug:
+### Set Up a Slug
 
 ```ruby
 class Book
@@ -32,7 +30,7 @@ class Book
 end
 ```
 
-Find a document by its slug:
+### Find a Document by its Slug
 
 ```ruby
 # GET /books/a-thousand-plateaus
@@ -41,11 +39,10 @@ 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.
 
-* Mongoid Slug will perform a find based on `slugs` only if all arguments passed to `find` are of the type `String`
+* Mongoid Slug will perform a find based on `slugs` only if all arguments passed to `find` are of the type `String`.
 * If your document uses `BSON::ObjectId` identifiers, and all arguments 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`.
-* If your document uses `String` identifiers and you want to be able find by slugs or ids, to get the correct behaviour, you should add a slug_id_strategy option to your _id field definition.  This option should return something that responds to `call` (a callable) and takes one string argument, e.g. a lambda.  This callable must return true if the string looks like one of your ids.
-
+* If your document uses `String` identifiers and you want to be able find by slugs or ids, to get the correct behaviour, you should add a `slug_id_strategy` option to your `_id` field definition. This option should return something that responds to `call` (a callable) and takes one string argument, e.g. a lambda.  This callable must return true if the string looks like one of your ids.
 
 ```ruby
 Book.fields['_id'].type
@@ -57,7 +54,7 @@ class Post
   include Mongoid::Document
   include Mongoid::Slug
 
-  field :_id, type: String, slug_id_strategy: lambda {|id| id.start_with?('....')}
+  field :_id, type: String, slug_id_strategy: lambda { |id| id.start_with?('...') }
 
   field :name
   slug  :name, history: true
@@ -72,38 +69,62 @@ post = Post.find '50b1386a0482939864000001' # Finds by bson ids
 ```
 [Examine slug.rb](lib/mongoid/slug.rb) for all available options.
 
+### Updating Existing Records
+
 To set slugs for existing records run following rake task:
 
 ```ruby
 rake mongoid_slug:set
 ```
+
 You can pass model names as an option for which you want to set slugs:
 
 ```ruby
 rake mongoid_slug:set[Model1,Model2]
 ```
-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:
+### Nil Slugs
+
+Empty slugs are possible and generate a `nil` value for the `_slugs` field. In the `Post` example above, a blank post `name` will cause the document record not to contain a `_slugs` field in the database. The default `_slugs` index is `sparse`, allowing that. If you wish to change this behavior add a custom `validates_presence_of :_slugs` validator to the document or change the database index to `sparse: false`.
+
+### Custom Slug Generation
+
+By default Mongoid Slug generates slugs with stringex. If this is not desired you can define your own slug generator.
+
+There are two ways to define slug generator.
+
+#### Globally
+
+Configure a block in `config/initializers/mongoid_slug.rb` as follows:
+
+```ruby
+Mongoid::Slug.configure do |c|
+  # create a block that takes the current object as an argument and return the slug
+  c.slug = proc { |cur_obj|
+    cur_object.slug_builder.to_url
+  }
+end
+```
+
+#### On Model
 
 ```ruby
 class Caption
   include Mongoid::Document
   include Mongoid::Slug
 
-  #create a block that takes the current object as an argument
-  #and returns the 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
 ```
-You can call stringex `to_url` method.
 
-Scoping
--------
+The `to_url` method comes from [stringex](https://github.com/rsl/stringex).
+
+You can define a slug builder globally and/or override it per model.
+
+### Scoping
 
 To scope a slug by a reference association, pass `:scope`:
 
@@ -121,19 +142,17 @@ class Employee
   field :name
   referenced_in :company
 
-  slug  :name, scope: :company
+  slug :name, scope: :company
 end
 ```
 
-In this example, if you create an employee without associating it with any
-company, the scope will fall back to the root employees collection.
+In this example, if you create an employee without associating it with any company, the scope will fall back to the root employees collection.
 
-Currently, if you have an irregular association name, you **must** specify the
-`:inverse_of` option on the other side of the assocation.
+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.
 
-The value of `:scope` can alternatively be a field within the model itself:
+Note that the unique index on the `Employee` collection in this example is derived from the `scope` value and is `{ _slugs: 1, company_id: 1}`. Therefore `:company` must be `referenced_in` above the definition of `slug` or it will not be able to resolve the association and mistakenly create a `{ _slugs: 1, company: 1}` index. An alternative is to scope to the field itself as follows:
 
 ```ruby
 class Employee
@@ -143,12 +162,11 @@ class Employee
   field :name
   field :company_id
 
-  slug  :name, scope: :company_id
+  slug :name, scope: :company_id
 end
 ```
 
-Limit Slug Length
------------------
+### Limit Slug Length
 
 MongoDB has a default limit around 1KB to the size of the index keys and will raise error 17280, `key too large to index` when trying to create a record that causes an index key to exceed that limit. By default slugs are of the form `text[-number]` and the text portion is limited in size to `Mongoid::Slug::MONGO_INDEX_KEY_LIMIT_BYTES - 32` bytes. You can change this limit with `max_length` or set it to `nil` if you're running MongoDB with [failIndexKeyTooLong](https://docs.mongodb.org/manual/reference/parameters/#param.failIndexKeyTooLong) set to `false`.
 
@@ -163,8 +181,7 @@ class Company
 end
 ```
 
-Optionally Find and Create Slugs per Model Type
------------------------------------------------
+### Optionally Find and Create Slugs per Model Type
 
 By default when using STI, the scope will be around the super-class.
 
@@ -208,11 +225,9 @@ comic_book = ComicBook.create(title: 'Anti Oedipus')
 comic_book.slugs.should eql(book.slugs)
 ```
 
-History
--------
+### History
 
-To specify that the history of a document should be kept track of, pass
-`:history` with a value of `true`.
+Enable slug history tracking by setting `history: true`.
 
 ```ruby
 class Page
@@ -235,8 +250,7 @@ page.update_attributes title: "Welcome"
 Page.find("welcome") == Page.find("home") # => true
 ```
 
-Reserved Slugs
---------------
+### Reserved Slugs
 
 Pass words you do not want to be slugged using the `reserve` option:
 
@@ -256,10 +270,9 @@ friend.slug # => 'admin-1'
 When reserved words are not specified, the words 'new' and 'edit' are considered reserved by default.
 Specifying an array of custom reserved words will overwrite these defaults.
 
-Localize Slug
---------------
+### Localize Slugs
 
-The slug can be localized:
+The slugs can be localized:
 
 ```ruby
 class PageSlugLocalize
@@ -271,18 +284,11 @@ class PageSlugLocalize
 end
 ```
 
-This feature is built upon Mongoid localized fields, so fallbacks and localization
-works as documented in the Mongoid manual.
+This feature is built upon Mongoid localized fields, so fallbacks and localization works as documented in the Mongoid manual.
 
-PS! A migration is needed to use Mongoid localized fields for documents that was created when this
-feature was off. Anything else will cause errors.
+### Custom Find Strategies
 
-Custom Find Strategies
-----------------------
-
-By default find will search for the document by the id field if the provided id
-looks like a BSON::ObjectId, and it will otherwise find by the _slugs field. However,
-custom strategies can ovveride the default behavior, like e.g:
+By default find will search for the document by the id field if the provided id looks like a `BSON::ObjectId`, and it will otherwise find by the _slugs field. However, custom strategies can ovveride the default behavior, like e.g:
 
 ```ruby
 module Mongoid::Slug::UuidIdStrategy
@@ -292,7 +298,7 @@ module Mongoid::Slug::UuidIdStrategy
 end
 ```
 
-Use a custom strategy by adding the slug_id_strategy annotation to the _id field:
+Use a custom strategy by adding the `slug_id_strategy` annotation to the `_id` field:
 
 ```ruby
 class Entity
@@ -306,9 +312,7 @@ class Entity
 end
 ```
 
-
-Adhoc checking whether a string is unique on a per Model basis
---------------------------------------------------------------
+### Adhoc Checking Whether a Slug is Unique
 
 Lets say you want to have a auto-suggest function on your GUI that could provide a preview of what the url or slug could be before the form to create the record was submitted.
 
@@ -321,17 +325,16 @@ unique = Mongoid::Slug::UniqueSlug.new(Book.new).find_unique(title)
 # return some representation of unique
 ```
 
-
-Mongoid::Paranoia Support
--------------------------
+### Mongoid::Paranoia Support
 
 The [Mongoid::Paranoia](http://github.com/simi/mongoid-paranoia) gem adds "soft-destroy" functionality to Mongoid documents.
+
 Mongoid::Slug contains special handling for Mongoid::Paranoia:
 
-- When destroying a paranoid document, the slug will be unset from the database.
-- When restoring a paranoid document, the slug will be rebuilt. Note that the new slug may not match the old one.
-- When resaving a destroyed paranoid document, the slug will remain unset in the database.
-- For indexing purposes, sparse unique indexes are used. The sparse condition will ignore any destroyed paranoid documents, since their slug is not set in database.
+* When destroying a paranoid document, the slug will be unset from the database.
+* When restoring a paranoid document, the slug will be rebuilt. Note that the new slug may not match the old one.
+* When resaving a destroyed paranoid document, the slug will remain unset in the database.
+* For indexing purposes, sparse unique indexes are used. The sparse condition will ignore any destroyed paranoid documents, since their slug is not set in database.
 
 ```ruby
 class Entity
@@ -343,17 +346,15 @@ end
 
 The following variants of Mongoid Paranoia are officially supported:
 
-* Mongoid 3 built-in Mongoid::Paranoia
+* Mongoid 3 built-in `Mongoid::Paranoia`
 * Mongoid 4 or 5 gem http://github.com/simi/mongoid_paranoia
 
-
 Contributing
 ------------
 
-Mongoid-slug is work of [many of contributors](https://github.com/digitalplaywright/mongoid-slug/graphs/contributors). You're encouraged to submit [pull requests](https://github.com/digitalplaywright/mongoid-slug/pulls), [propose features, ask questions and discuss issues](https://github.com/digitalplaywright/mongoid-slug/issues). See [CONTRIBUTING](CONTRIBUTING.md) for details.
+Mongoid-slug is work of [many of contributors](https://github.com/mongoid/mongoid-slug/graphs/contributors). You're encouraged to submit [pull requests](https://github.com/mongoid/mongoid-slug/pulls), [propose features, ask questions and discuss issues](https://github.com/mongoid/mongoid-slug/issues). See [CONTRIBUTING](CONTRIBUTING.md) for details.
 
 Copyright & License
 -------------------
 
 Copyright (c) 2010-2016 Hakan Ensari & Contributors, see [LICENSE](LICENSE) for details.
-

data/lib/mongoid/slug.rb

@@ -16,18 +16,29 @@ module Mongoid
     MONGO_INDEX_KEY_LIMIT_BYTES = 1024
 
     included do
-      cattr_accessor :reserved_words,
+      cattr_accessor :slug_reserved_words,
                      :slug_scope,
                      :slugged_attributes,
-                     :url_builder,
-                     :history,
-                     :by_model_type,
+                     :slug_url_builder,
+                     :slug_history,
+                     :slug_by_model_type,
                      :slug_max_length
 
       # field :_slugs, type: Array, default: [], localize: false
       # alias_attribute :slugs, :_slugs
     end
 
+    class << self
+      attr_accessor :default_slug
+      def configure(&block)
+        instance_eval(&block)
+      end
+
+      def slug(&block)
+        @default_slug = block if block_given?
+      end
+    end
+
     module ClassMethods
       # @overload slug(*fields)
       #   Sets one ore more fields as source of slug.
@@ -65,26 +76,21 @@ module Mongoid
         options = fields.extract_options!
 
         self.slug_scope            = options[:scope]
-        self.reserved_words        = options[:reserve] || Set.new(%w(new edit))
+        self.slug_reserved_words   = options[:reserve] || Set.new(%w(new edit))
         self.slugged_attributes    = fields.map(&:to_s)
-        self.history               = options[:history]
-        self.by_model_type         = options[:by_model_type]
+        self.slug_history          = options[:history]
+        self.slug_by_model_type    = options[:by_model_type]
         self.slug_max_length       = options.key?(:max_length) ? options[:max_length] : MONGO_INDEX_KEY_LIMIT_BYTES - 32
 
-        field :_slugs, type: Array, default: [], localize: options[:localize]
+        field :_slugs, type: Array, localize: options[:localize]
         alias_attribute :slugs, :_slugs
 
         # Set index
         unless embedded?
-          index(*Mongoid::Slug::Index.build_index(slug_scope_key, by_model_type))
+          index(*Mongoid::Slug::Index.build_index(slug_scope_key, slug_by_model_type))
         end
 
-        #-- Why is it necessary to customize the slug builder?
-        default_url_builder = lambda do |cur_object|
-          cur_object.slug_builder.to_url
-        end
-
-        self.url_builder = block_given? ? block : default_url_builder
+        self.slug_url_builder = block_given? ? block : default_slug_url_builder
 
         #-- always create slug on create
         #-- do not create new slug on update if the slug is permanent
@@ -100,7 +106,7 @@ module Mongoid
         # - recreate the slug on restore
         # - force reset the slug when saving a destroyed paranoid document, to ensure it stays unset in the database
         if is_paranoid_doc?
-          send(:include, Mongoid::Slug::Paranoia) unless self.respond_to?(:before_restore)
+          send(:include, Mongoid::Slug::Paranoia) unless respond_to?(:before_restore)
           set_callback :destroy, :after,  :unset_slug!
           set_callback :restore, :before, :set_slug!
           set_callback :save,    :before, :reset_slug!, if: :paranoid_deleted?
@@ -108,6 +114,10 @@ module Mongoid
         end
       end
 
+      def default_slug_url_builder
+        Mongoid::Slug.default_slug || ->(cur_object) { cur_object.slug_builder.to_url }
+      end
+
       def look_like_slugs?(*args)
         with_default_scope.look_like_slugs?(*args)
       end
@@ -158,11 +168,13 @@ module Mongoid
 
       private
 
-      if Mongoid::Compatibility::Version.mongoid5? && Threaded.method(:current_scope).arity == -1
+      if Mongoid::Compatibility::Version.mongoid5? ||
+         Mongoid::Compatibility::Version.mongoid6? &&
+         Threaded.method(:current_scope).arity == -1
         def current_scope
           Threaded.current_scope(self)
         end
-      elsif Mongoid::Compatibility::Version.mongoid5?
+      elsif Mongoid::Compatibility::Version.mongoid5? || Mongoid::Compatibility::Version.mongoid6?
         def current_scope
           Threaded.current_scope
         end
@@ -198,12 +210,12 @@ module Mongoid
 
       # skip slug generation and use Mongoid id
       # to find document instead
-      return true if new_slug.size == 0
+      return true if new_slug.size.zero?
 
       # avoid duplicate slugs
       _slugs.delete(new_slug) if _slugs
 
-      if !!history && _slugs.is_a?(Array)
+      if !!slug_history && _slugs.is_a?(Array)
         append_slug(new_slug)
       else
         self._slugs = [new_slug]
@@ -231,7 +243,7 @@ module Mongoid
 
     # Rolls back the slug value from the Mongoid changeset.
     def reset_slug!
-      self.reset__slugs!
+      reset__slugs!
     end
 
     # Sets the slug to its default value.
@@ -341,7 +353,7 @@ module Mongoid
     # have any localized attributes at all (extreme edge case).
     def all_locales
       locales = slugged_attributes
-                .map { |attr| send("#{attr}_translations").keys if self.respond_to?("#{attr}_translations") }
+                .map { |attr| send("#{attr}_translations").keys if respond_to?("#{attr}_translations") }
                 .flatten.compact.uniq
       locales = I18n.available_locales if locales.empty?
       locales

data/lib/mongoid/slug/criteria.rb

@@ -62,7 +62,7 @@ module Mongoid
       # otherwise default for all other id_types
       def build_slug_strategy(id_type)
         type_method = id_type.to_s.downcase.split('::').last + '_slug_strategy'
-        self.respond_to?(type_method, true) ? method(type_method) : ->(_id) { false }
+        respond_to?(type_method, true) ? method(type_method) : ->(_id) { false }
       end
 
       # a string will not look like a slug if it looks like a legal BSON::ObjectId
@@ -99,10 +99,8 @@ module Mongoid
 
       def check_for_missing_documents_for_slugs!(result, slugs)
         missing_slugs = slugs - result.map(&:slugs).flatten
-
-        if !missing_slugs.blank? && Mongoid.raise_not_found_error
-          fail Errors::DocumentNotFound.new(klass, slugs, missing_slugs)
-        end
+        return unless !missing_slugs.blank? && Mongoid.raise_not_found_error
+        raise Errors::DocumentNotFound.new(klass, slugs, missing_slugs)
       end
     end
   end