IMPORTANT: If you are upgrading to Mongoid Slug 1.0.0 please migrate in accordance with the instructions in https://github.com/digitalplaywright/mongoid-slug/wiki/How-to-upgrade-to-1.0.0-or-newer. Mongoid Slug 1.0.0 stores the slugs in a single field _slugs of array type, and all previous slugs must be migrated.
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.
Add to your Gemfile:
gem 'mongoid_slug'
Set up a slug:
class Book
include Mongoid::Document
include Mongoid::Slug
field :title
slug :title
end
Find a document by its slug:
# 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 tofind
are of the typeString
- If your document uses
BSON::ObjectId
identifiers, and all arguments look like validBSON::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 tocall
(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.
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
=> ...
[Read here] 4 for all available options.
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
To scope a slug by a reference association, pass :scope
:
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.
The value of :scope
can alternatively be a field within the model itself:
class Employee
include Mongoid::Document
include Mongoid::Slug
field :name
field :company_id
slug :name, :scope => :company_id
end
To specify that the history of a document should be kept track of, pass
:history
with a value of true
.
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:
page = Page.new title: "Home"
page.save
page.update_attributes title: "Welcome"
Page.find("welcome") == Page.find("home") #=> true
Pass words you do not want to be slugged using the reserve
option:
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'
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:
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:
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
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.
title = params[:title]
unique = Mongoid::Slug::UniqueSlug.new(Book.new).find_unique(title)
...
# return some representation of unique