• Stars
    star
    493
  • Rank 89,306 (Top 2 %)
  • Language
    Ruby
  • License
    MIT License
  • Created over 14 years ago
  • Updated 7 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Generates a URL slug/permalink based on fields in a Mongoid-based model.

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, supporting non-Latin characters.

Build Status Gem Version Code Climate

Version Support

Mongoid Slug 7.x requires at least Mongoid 7.0.0 and Ruby 2.5.0. For earlier Mongoid and Ruby version support, please use an earlier version of Mongoid Slug.

Mongoid Slug is compatible with all MongoDB versions which Mongoid supports, however, please see "Slug Max Length" section below for MongoDB 4.0 and earlier.

Installation

Add to your Gemfile:

gem 'mongoid-slug'

Usage

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 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.
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 for all available options.

Updating Existing Records

To set slugs for existing records run following rake task:

rake mongoid_slug:set

You can pass model names as an option for which you want to set slugs:

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:

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

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.

You can define a slug builder globally and/or override it per model.

Scoping

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.

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:

class Employee
  include Mongoid::Document
  include Mongoid::Slug

  field :name
  field :company_id

  slug :name, scope: :company_id
end

Slug Max Length

MongoDB featureCompatibilityVersion "4.0" and earlier applies an Index Key Limit which limits the total size of an index entry to around 1KB 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 set to false.

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.

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.

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.

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

Reserved Slugs

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'

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.

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 field only. For example, if I18n.default_locale is :en, the index will be generated as follows:

slug :title, localize: true

# The following index 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.

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:

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

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.

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. You're encouraged to submit pull requests, propose features, ask questions and discuss issues. See CONTRIBUTING for details.

Copyright & License

Copyright (c) 2010-2017 Hakan Ensari & Contributors, see LICENSE for details.

More Repositories

1

mongoid-rspec

RSpec matchers and macros for Mongoid.
Ruby
498
star
2

mongoid-history

Multi-user non-linear history tracking, auditing, undo, redo for mongoid.
Ruby
392
star
3

mongoid_search

Simple full text search for Mongoid ORM
Ruby
319
star
4

moped

A MongoDB driver for Ruby
Ruby
202
star
5

mongoid_fulltext

An n-gram-based full-text search implementation for the Mongoid ODM.
Ruby
150
star
6

mongoid-site

Source code for mongoid.org
HTML
141
star
7

echo

The Mongoid Demo Application
Ruby
128
star
8

mongoid_orderable

Acts as list mongoid implementation
Ruby
103
star
9

kiqstand

Mongoid 3 Middleware for Sidekiq
Ruby
97
star
10

mongoid-grid_fs

A pure Mongoid/Moped implementation of the MongoDB GridFS specification.
Ruby
83
star
11

mongoid-locker

Document-level locking for MongoDB via Mongoid
Ruby
77
star
12

mongoid-cached-json

Effective caching for nested JSON models.
Ruby
74
star
13

origin

A Ruby DSL for building MongoDB queries
Ruby
62
star
14

mongoid-scroll

Mongoid extension that enables infinite scrolling with MongoDB.
Ruby
60
star
15

mongo_session_store

MongoSessionStore is a Rails-compatible session store for MongoDB using either Mongoid or the MongoDB Ruby Driver. It also allows for custom Mongo session store that works with any (or no!) Mongo ODM
Ruby
56
star
16

evolver

Database Schema Evolution for MongoDB
Ruby
44
star
17

mongoid-demo

Demo applications for Mongoid
Ruby
19
star
18

mongoid-observers

Mongoid observer (removed in Mongoid 4.0)
Ruby
19
star
19

mongoid.github.io

Mongoid community site.
HTML
15
star
20

scooter

An Asynchronous (Non-Blocking) MongoDB driver for the JVM
Scala
15
star
21

mongoid-shell

Derive shell commands from Mongoid sessions and configuration options.
Ruby
14
star
22

moped-turbo

Moped turbocharger. (C extensions for Moped)
Ruby
13
star
23

mongoid-tag-collectible

Easily maintain a collection of Tag instances with aggregate counts from your model's tags.
Ruby
9
star
24

delayed_job_shallow_mongoid

When the object or arg to a delayed_job is a Mongoid document, store only a small stub of the object instead of the full serialization.
Ruby
8
star
25

echo-goliath

Simple Sample of Using Moped and Goliath.
Ruby
7
star
26

mongoid-compatibility

Compatibility helpers for the many Mongoid versions.
Ruby
7
star
27

scourge

1
star