mongoid-slug 6.0.0 → 6.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cf9ad642da6118dcc879edd3c4b6f43adf2b110e422d691926984ffb743f0dcf
-  data.tar.gz: 800d4c721c01fb89267218aaeff2c5a8d91a906f8587c87aa3680d774011180b
+  metadata.gz: 54274387f9a202810aefa5b3b19c90990636d6076cbc6591cf46129986b4b5e4
+  data.tar.gz: 557ba29c3dfaa615f7e926ba223bb3390e930a52ed559baf33b0517cf224aaa8
 SHA512:
-  metadata.gz: 8bb6300dd08988c87f922e5cfc308de3ea428a8730a75d9b2c261814cb1a8568ad266b94e8358d710602af131166dbf063ad1e163eca2a2d31108be7d147456d
-  data.tar.gz: 36dd52ca7e37b0e57cd4241ab616a20892688dfb4e79af8e02ada7f7802c30b158bb28b5594337eded30c47de948e20e1e40da69bc84ef2398e463d738c63188
+  metadata.gz: 11a15aec160529e61f5e6fe9636d9fded847d12ec08fe50e6c67997aca86fed844f42264962c65999e862b7a73ba3d41c337c7fae492e8c91999efbd889ea502
+  data.tar.gz: ff604c15c46fa831bb648906b802cc8e93d13363207fc3a121b7b1c3e4ef3ccb46305f630507ded0e24ad07d70069e4e70ae3185d022267e5ba4c42b53381b44

data/LICENSE

@@ -1,20 +1,20 @@
-Copyright (c) 2010-2017 Hakan Ensari & Contributors
-
-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.
+Copyright (c) 2010-2017 Hakan Ensari & Contributors
+
+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/README.md

@@ -1,336 +1,361 @@
-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/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/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
-
-Add to your Gemfile:
-
-```ruby
-gem 'mongoid-slug'
-```
-
-### Usage
-
-### Set Up a Slug
-
-```ruby
-class Book
-  include Mongoid::Document
-  include Mongoid::Slug
-
-  field :title
-  slug :title
-end
-```
-
-### Find a Document by its Slug
-
-```ruby
-# GET /books/a-thousand-plateaus
-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`.
-* 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.
-
-```ruby
-Book.fields['_id'].type
-=> String
-book = Book.find 'a-thousand-plateaus' # Finds by slugs
-=> ...
-
-class Post
-  include Mongoid::Document
-  include Mongoid::Slug
-
-  field :_id, type: String, slug_id_strategy: lambda { |id| id.start_with?('...') }
-
-  field :name
-  slug  :name, history: true
-end
-
-Post.fields['_id'].type
-=> String
-post = Post.find 'a-thousand-plateaus' # Finds by slugs
-=> ...
-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]
-```
-
-### 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
-  slug do |cur_object|
-    cur_object.slug_builder.to_url
-  end
-end
-```
-
-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`:
-
-```ruby
-class Company
-  include Mongoid::Document
-
-  references_many :employees
-end
-
-class Employee
-  include Mongoid::Document
-  include Mongoid::Slug
-
-  field :name
-  referenced_in :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.
-
-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.
-
-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
-  include Mongoid::Document
-  include Mongoid::Slug
-
-  field :name
-  field :company_id
-
-  slug :name, scope: :company_id
-end
-```
-
-### 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`.
-
-```ruby
-class Company
-  include Mongoid::Document
-  include Mongoid::Slug
-
-  field :name
-
-  slug  :name, max_length: 24
-end
-```
-
-### Optionally Find and Create Slugs per Model Type
-
-By default when using STI, the scope will be around the super-class.
-
-```ruby
-class Book
-  include Mongoid::Document
-  include Mongoid::Slug
-  field :title
-
-  slug  :title, history: true
-  embeds_many :subjects
-  has_many :authors
-end
-
-class ComicBook < Book
-end
-
-book = Book.create(title: 'Anti Oedipus')
-comic_book = ComicBook.create(title: 'Anti Oedipus')
-comic_book.slugs.should_not eql(book.slugs)
-```
-
-If you want the scope to be around the subclass, then set the option `by_model_type: true`.
-
-```ruby
-class Book
-  include Mongoid::Document
-  include Mongoid::Slug
-  field :title
-
-  slug  :title, history: true, by_model_type: true
-  embeds_many :subjects
-  has_many :authors
-end
-
-class ComicBook < Book
-end
-
-book = Book.create(title: 'Anti Oedipus')
-comic_book = ComicBook.create(title: 'Anti Oedipus')
-comic_book.slugs.should eql(book.slugs)
-```
-
-### History
-
-Enable slug history tracking by setting `history: true`.
-
-```ruby
-class Page
-  include Mongoid::Document
-  include Mongoid::Slug
-
-  field :title
-
-  slug :title, history: true
-end
-```
-
-The document will then be returned for any of the saved slugs:
-
-```ruby
-page = Page.new title: "Home"
-page.save
-page.update_attributes title: "Welcome"
-
-Page.find("welcome") == Page.find("home") # => true
-```
-
-### Reserved Slugs
-
-Pass words you do not want to be slugged using the `reserve` option:
-
-```ruby
-class Friend
-  include Mongoid::Document
-
-  field :name
-  slug :name, reserve: ['admin', 'root']
-end
-
-friend = Friend.create name: 'admin'
-Friend.find('admin') # => nil
-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 Slugs
-
-The slugs can be localized:
-
-```ruby
-class PageSlugLocalize
-  include Mongoid::Document
-  include Mongoid::Slug
-
-  field :title, localize: true
-  slug  :title, localize: true
-end
-```
-
-This feature is built upon Mongoid localized fields, so fallbacks and localization works as documented in the Mongoid manual.
-
-### 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:
-
-```ruby
-module Mongoid::Slug::UuidIdStrategy
-  def self.call id
-    id =~ /\A([0-9a-fA-F]){8}-(([0-9a-fA-F]){4}-){3}([0-9a-fA-F]){12}\z/
-  end
-end
-```
-
-Use a custom strategy by adding the `slug_id_strategy` annotation to the `_id` field:
-
-```ruby
-class Entity
-  include Mongoid::Document
-  include Mongoid::Slug
-
-  field :_id, type: String, slug_id_strategy: UuidIdStrategy
-
-  field :user_edited_variation
-  slug  :user_edited_variation, history: true
-end
-```
-
-### 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.
-
-You can use the UniqueSlug class in your server side code to do this, e.g.
-
-```ruby
-title = params[:title]
-unique = Mongoid::Slug::UniqueSlug.new(Book.new).find_unique(title)
-...
-# return some representation of unique
-```
-
-Contributing
-------------
-
-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-2017 Hakan Ensari & Contributors, see [LICENSE](LICENSE) for details.
+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://github.com/mongoid/mongoid-slug/actions/workflows/test.yml/badge.svg?query=branch%3Amaster)](https://github.com/mongoid/mongoid-slug/actions/workflows/test.ym?query=branch%3Amaster)
+[![Gem Version](https://badge.fury.io/rb/mongoid-slug.svg)](http://badge.fury.io/rb/mongoid-slug)
+[![Code Climate](https://codeclimate.com/github/mongoid/mongoid-slug.svg)](https://codeclimate.com/github/mongoid/mongoid-slug)
+
+### Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'mongoid-slug'
+```
+
+### Usage
+
+### Set Up a Slug
+
+```ruby
+class Book
+  include Mongoid::Document
+  include Mongoid::Slug
+
+  field :title
+  slug :title
+end
+```
+
+### Find a Document by its Slug
+
+```ruby
+# GET /books/a-thousand-plateaus
+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`.
+* 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.
+
+```ruby
+Book.fields['_id'].type
+=> String
+
+book = Book.find 'a-thousand-plateaus' # Finds by slugs
+=> ...
+
+class Post
+  include Mongoid::Document
+  include Mongoid::Slug
+
+  field :_id, type: String, slug_id_strategy: lambda { |id| id.start_with?('...') }
+
+  field :name
+  slug  :name, history: true
+end
+
+Post.fields['_id'].type
+=> String
+
+post = Post.find 'a-thousand-plateaus' # Finds by slugs
+=> ...
+
+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]
+```
+
+### 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
+  slug do |cur_object|
+    cur_object.slug_builder.to_url
+  end
+end
+```
+
+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`:
+
+```ruby
+class Company
+  include Mongoid::Document
+
+  references_many :employees
+end
+
+class Employee
+  include Mongoid::Document
+  include Mongoid::Slug
+
+  field :name
+  referenced_in :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.
+
+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.
+
+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
+  include Mongoid::Document
+  include Mongoid::Slug
+
+  field :name
+  field :company_id
+
+  slug :name, scope: :company_id
+end
+```
+
+### 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`.
+
+```ruby
+class Company
+  include Mongoid::Document
+  include Mongoid::Slug
+
+  field :name
+
+  slug  :name, max_length: 24
+end
+```
+
+### Optionally Find and Create Slugs per Model Type
+
+By default when using STI, the scope will be around the super-class.
+
+```ruby
+class Book
+  include Mongoid::Document
+  include Mongoid::Slug
+  field :title
+
+  slug  :title, history: true
+  embeds_many :subjects
+  has_many :authors
+end
+
+class ComicBook < Book
+end
+
+book = Book.create(title: 'Anti Oedipus')
+comic_book = ComicBook.create(title: 'Anti Oedipus')
+comic_book.slugs.should_not eql(book.slugs)
+```
+
+If you want the scope to be around the subclass, then set the option `by_model_type: true`.
+
+```ruby
+class Book
+  include Mongoid::Document
+  include Mongoid::Slug
+  field :title
+
+  slug  :title, history: true, by_model_type: true
+  embeds_many :subjects
+  has_many :authors
+end
+
+class ComicBook < Book
+end
+
+book = Book.create(title: 'Anti Oedipus')
+comic_book = ComicBook.create(title: 'Anti Oedipus')
+comic_book.slugs.should eql(book.slugs)
+```
+
+### History
+
+Enable slug history tracking by setting `history: true`.
+
+```ruby
+class Page
+  include Mongoid::Document
+  include Mongoid::Slug
+
+  field :title
+
+  slug :title, history: true
+end
+```
+
+The document will then be returned for any of the saved slugs:
+
+```ruby
+page = Page.new title: "Home"
+page.save
+page.update_attributes title: "Welcome"
+
+Page.find("welcome") == Page.find("home") # => true
+```
+
+### Reserved Slugs
+
+Pass words you do not want to be slugged using the `reserve` option:
+
+```ruby
+class Friend
+  include Mongoid::Document
+
+  field :name
+  slug :name, reserve: ['admin', 'root']
+end
+
+friend = Friend.create name: 'admin'
+Friend.find('admin') # => nil
+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 Slugs
+
+The slugs can be localized. This feature is built upon Mongoid localized fields,
+so fallbacks and localization works as documented in the Mongoid manual.
+
+```ruby
+class PageSlugLocalize
+  include Mongoid::Document
+  include Mongoid::Slug
+
+  field :title, localize: true
+  slug  :title, localize: true
+end
+```
+
+By specifying `localize: true`, the slug index will be created on the
+[I18n.default_locale](http://guides.rubyonrails.org/i18n.html#the-public-i18n-api) field only.
+For example, if `I18n.default_locale` is `:en`, the index will be generated as follows:
+
+```ruby
+slug :title, localize: true
+
+# The following indexes is auto-generated:
+index({ '_slugs.en' => 1 }, { unique: true, sparse: true })
+```
+
+If you are supporting multiple locales, you may specify the list of locales on which
+to create indexes as an `Array`.
+
+```ruby
+slug :title, localize: [:fr, :es, :de]
+
+# The following indexes are auto-generated:
+index({ '_slugs.fr' => 1 }, { unique: true, sparse: true })
+index({ '_slugs.es' => 1 }, { unique: true, sparse: true })
+index({ '_slugs.de' => 1 }, { unique: true, sparse: true })
+```
+
+### 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:
+
+```ruby
+module Mongoid::Slug::UuidIdStrategy
+  def self.call id
+    id =~ /\A([0-9a-fA-F]){8}-(([0-9a-fA-F]){4}-){3}([0-9a-fA-F]){12}\z/
+  end
+end
+```
+
+Use a custom strategy by adding the `slug_id_strategy` annotation to the `_id` field:
+
+```ruby
+class Entity
+  include Mongoid::Document
+  include Mongoid::Slug
+
+  field :_id, type: String, slug_id_strategy: UuidIdStrategy
+
+  field :user_edited_variation
+  slug  :user_edited_variation, history: true
+end
+```
+
+### 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.
+
+You can use the UniqueSlug class in your server side code to do this, e.g.
+
+```ruby
+title = params[:title]
+unique = Mongoid::Slug::UniqueSlug.new(Book.new).find_unique(title)
+...
+# return some representation of unique
+```
+
+Contributing
+------------
+
+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-2017 Hakan Ensari & Contributors, see [LICENSE](LICENSE) for details.