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/history.rb,
lib/friendly_id/slugged.rb,
lib/friendly_id/version.rb,
lib/friendly_id/reserved.rb,
lib/friendly_id/globalize.rb,
lib/friendly_id/simple_i18n.rb,
lib/friendly_id/object_utils.rb,
lib/friendly_id/configuration.rb,
lib/friendly_id/slug_generator.rb,
lib/friendly_id/finder_methods.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 engine.

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.find("joe")

Defined Under Namespace

Modules: Base, FinderMethods, Globalize, History, Model, ObjectUtils, Reserved, Scoped, SimpleI18n, Slugged Classes: Configuration, Slug, SlugGenerator

Constant Summary

VERSION = 
"4.0.10.1"

Class Method Summary (collapse)

Class Method Details

+ (Object) defaults(&block)

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


105
106
107
108
109
110
 
# File 'lib/friendly_id.rb', line 105

def self.defaults(&block)
  @mutex.synchronize do
    @defaults = block if block_given?
    @defaults ||= lambda {|config| config.use :reserved}
  end
end

+ (Object) extended(model_class)

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.



79
80
81
82
83
84
85
86
87
88
89
 
# File 'lib/friendly_id.rb', line 79

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

+ (Object) included(model_class)

Allow developers to `include` FriendlyId or `extend` it.



92
93
94
 
# File 'lib/friendly_id.rb', line 92

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

+ (Object) table_name_prefix

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.



116
117
118
 
# File 'lib/friendly_id.rb', line 116

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