Module: FriendlyId

Defined in:
lib/friendly_id.rb,
lib/friendly_id/base.rb,
lib/friendly_id/slug.rb,
lib/friendly_id/scoped.rb,
lib/friendly_id/finders.rb,
lib/friendly_id/history.rb,
lib/friendly_id/slugged.rb,
lib/friendly_id/version.rb,
lib/friendly_id/reserved.rb,
lib/friendly_id/candidates.rb,
lib/friendly_id/simple_i18n.rb,
lib/friendly_id/object_utils.rb,
lib/friendly_id/configuration.rb,
lib/friendly_id/finder_methods.rb,
lib/friendly_id/slug_generator.rb,
lib/friendly_id/sequentially_slugged.rb,
lib/friendly_id/sequentially_slugged/calculator.rb

Overview

About FriendlyId

FriendlyId is an add-on to Ruby's Active Record that allows you to replace ids in your URLs with strings:

# without FriendlyId
http://example.com/states/4323454

# with FriendlyId
http://example.com/states/washington

It requires few changes to your application code and offers flexibility, performance and a well-documented codebase.

Core Concepts

Slugs

The concept of slugs is at the heart of FriendlyId.

A slug is the part of a URL which identifies a page using human-readable keywords, rather than an opaque identifier such as a numeric id. This can make your application more friendly both for users and search engines.

Finders: Slugs Act Like Numeric IDs

To the extent possible, FriendlyId lets you treat text-based identifiers like normal IDs. This means that you can perform finds with slugs just like you do with numeric ids:

Person.find(82542335)
Person.friendly.find("joe")

Defined Under Namespace

Modules: Base, FinderMethods, Finders, History, Model, ObjectUtils, Reserved, Scoped, SequentiallySlugged, SimpleI18n, Slugged, UnfriendlyUtils Classes: Candidates, Configuration, Slug, SlugGenerator

Constant Summary collapse

VERSION =
"5.5.1".freeze
UNFRIENDLY_CLASSES =

Instances of these classes will never be considered a friendly id.

See Also:

  • ObjectUtils#friendly_id
[
  Array,
  FalseClass,
  Hash,
  NilClass,
  Numeric,
  Symbol,
  TrueClass
]

Class Method Summary collapse

Class Method Details

.defaults(&block) ⇒ Object

Set global defaults for all models using FriendlyId.

The default defaults are to use the :reserved module and nothing else.

Examples:

FriendlyId.defaults do |config|
  config.base :name
  config.use :slugged
end


102
103
104
105
# File 'lib/friendly_id.rb', line 102

def self.defaults(&block)
  @defaults = block if block
  @defaults ||= ->(config) { config.use :reserved }
end

.extended(model_class) ⇒ Object

FriendlyId takes advantage of extended to do basic model setup, primarily extending Base to add friendly_id as a class method.

Previous versions of FriendlyId simply patched ActiveRecord::Base, but this version tries to be less invasive.

In addition to adding friendly_id, the class instance variable +@friendly_id_config+ is added. This variable is an instance of an anonymous subclass of Configuration. This allows subsequently loaded modules like Slugged and Scoped to add functionality to the configuration class only for the current class, rather than monkey patching Configuration directly. This isolates other models from large feature changes an addon to FriendlyId could potentially introduce.

The upshot of this is, you can have two Active Record models that both have a @friendly_id_config, but each config object can have different methods and behaviors depending on what modules have been loaded, without conflicts. Keep this in mind if you're hacking on FriendlyId.

For examples of this, see the source for FriendlyId::Scoped.included.



75
76
77
78
79
80
81
82
83
84
85
86
# File 'lib/friendly_id.rb', line 75

def self.extended(model_class)
  return if model_class.respond_to? :friendly_id
  class << model_class
    alias_method :relation_without_friendly_id, :relation
  end
  model_class.class_eval do
    extend Base
    @friendly_id_config = Class.new(Configuration).new(self)
    FriendlyId.defaults.call @friendly_id_config
    include Model
  end
end

.included(model_class) ⇒ Object

Allow developers to include FriendlyId or extend it.



89
90
91
# File 'lib/friendly_id.rb', line 89

def self.included(model_class)
  model_class.extend self
end

.mark_as_unfriendly(klass) ⇒ Object



62
63
64
# File 'lib/friendly_id/object_utils.rb', line 62

def self.mark_as_unfriendly(klass)
  klass.send(:include, FriendlyId::UnfriendlyUtils)
end

.table_name_prefixObject

Set the ActiveRecord table name prefix to friendly_id_

This makes 'slugs' into 'friendly_id_slugs' and also respects any 'global' table_name_prefix set on ActiveRecord::Base.



111
112
113
# File 'lib/friendly_id.rb', line 111

def self.table_name_prefix
  "#{ActiveRecord::Base.table_name_prefix}friendly_id_"
end