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/slugged.rb,
lib/friendly_id/history.rb,
lib/friendly_id/version.rb,
lib/friendly_id/finders.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

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, SimpleI18n, Slugged Classes: Candidates, Configuration, Slug, SlugGenerator

Constant Summary

UNFRIENDLY_CLASSES =

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

See Also:

  • ObjectUtils#friendly_id
[
  ActiveRecord::Base,
  Array,
  FalseClass,
  Hash,
  NilClass,
  Numeric,
  Symbol,
  TrueClass
]
VERSION = 
"5.1.0.beta.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


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

def self.defaults(&block)
  @defaults = block if block_given?
  @defaults ||= ->(config) {config.use :reserved}
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.



88
89
90
91
92
93
94
95
96
97
98
99
 
# File 'lib/friendly_id.rb', line 88

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.class_eval do
    extend Base
    @friendly_id_config = Class.new(Configuration).new(self)
    FriendlyId.defaults.call @friendly_id_config
    include Model
  end
end

+ (Object) included(model_class)

Allow developers to include FriendlyId or extend it.



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

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.



124
125
126
 
# File 'lib/friendly_id.rb', line 124

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