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.
[ Array, FalseClass, Hash, NilClass, Numeric, Symbol, TrueClass ]
Class Method Summary collapse
-
.defaults(&block) ⇒ Object
Set global defaults for all models using FriendlyId.
-
.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. -
.included(model_class) ⇒ Object
Allow developers to
include
FriendlyId orextend
it. - .mark_as_unfriendly(klass) ⇒ Object
-
.table_name_prefix ⇒ Object
Set the ActiveRecord table name prefix to friendly_id_.
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.
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_prefix ⇒ Object
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 |