friendly_id4 4.0.0.beta4 → 4.0.0.beta5

data/lib/friendly_id/migration.rb

@@ -1,4 +1,5 @@
 class CreateFriendlyIdSlugs < ActiveRecord::Migration
+
   def self.up
     create_table :friendly_id_slugs do |t|
       t.string   :slug,           :null => false

data/lib/friendly_id/object_utils.rb

@@ -1,7 +1,11 @@
 module FriendlyId
-  # Utility methods that are in Object because it's impossible to predict what
-  # kinds of objects get passed into FinderMethods#find_one and
-  # Model#normalize_friendly_id.
+  # Utility methods for determining whether any object is a friendly id.
+  #
+  # Monkey-patching Object is a somewhat extreme measure not to be taken lightly
+  # by libraries, but in this case I decided to do it because to me, it feels
+  # cleaner than adding a module method to {FriendlyId}. I've given the methods
+  # names that unambigously refer to the library of their origin, which should
+  # be sufficient to avoid conflicts with other libraries.
   module ObjectUtils
 
     # True is the id is definitely friendly, false if definitely unfriendly,
@@ -9,6 +13,14 @@ module FriendlyId
     #
     # An object is considired "definitely unfriendly" if its class is or
     # inherits from Numeric, Symbol or ActiveRecord::Base.
+    #
+    # An object is considered "definitely friendly" if it responds to +to_i+,
+    # and its value when cast to an integer and then back to a string is
+    # different from its value when merely cast to a string:
+    #
+    #   123.friendly_id?       #=> false
+    #   "123".friendly_id?     #=> nil
+    #   "abc123".friendly_id?  #=> true
     def friendly_id?
       if [Numeric, Symbol, ActiveRecord::Base].detect {|klass| self.class < klass}
         false
@@ -25,6 +37,4 @@ module FriendlyId
   end
 end
 
-class Object
-  include FriendlyId::ObjectUtils
-end
+Object.send :include, FriendlyId::ObjectUtils

data/lib/friendly_id/reserved.rb

@@ -0,0 +1,46 @@
+module FriendlyId
+
+=begin
+This module adds the ability to exlude a list of words from use as
+FriendlyId slugs.
+
+By default, FriendlyId reserves the words "new" and "edit" when this module
+is included. You can configure this globally by using {FriendlyId.defaults FriendlyId.defaults}:
+
+  FriendlyId.defaults do |config|
+    config.use :reserved
+    # Reserve words for English and Spanish URLs
+    config.reserved_words = %w(new edit nueva nuevo editar)
+  end
+=end
+  module Reserved
+
+    # When included, this module adds configuration options to the model class's
+    # friendly_id_config.
+    def self.included(model_class)
+      model_class.class_eval do
+        friendly_id_config.class.send :include, Reserved::Configuration
+        friendly_id_config.defaults[:reserved_words] ||= ["new", "edit"]
+      end
+    end
+
+    # This module adds the +:reserved_words+ configuration option to
+    # {FriendlyId::Configuration FriendlyId::Configuration}.
+    module Configuration
+      attr_writer :reserved_words
+
+      # Overrides {FriendlyId::Configuration#base} to add a validation to the
+      # model class.
+      def base=(base)
+        super
+        reserved_words = model_class.friendly_id_config.reserved_words
+        model_class.validates_exclusion_of base, :in => reserved_words
+      end
+
+      # An array of words forbidden as slugs.
+      def reserved_words
+        @reserved_words ||= @defaults[:reserved_words]
+      end
+    end
+  end
+end

data/lib/friendly_id/scoped.rb

@@ -2,21 +2,88 @@ require "friendly_id/slugged"
 
 module FriendlyId
 
-  # This module adds scopes to in-table slugs. It's not loaded by default,
-  # so in order to active this feature you must include the module in your
-  # class.
-  #
-  # You can scope by an explicit column, or by a `belongs_to` relation.
-  #
-  # @example
-  #   class Restaurant < ActiveRecord::Base
-  #     belongs_to :city
-  #     include FriendlyId::Scoped
-  #     friendly_id :name, :scope => :city
-  #   end
+=begin
+This module allows FriendlyId to generate unique slugs within a scope.
+
+This allows, for example, two restaurants in different cities to have the slug
++joes-diner+:
+
+    class Restaurant < ActiveRecord::Base
+      extend FriendlyId
+      belongs_to :city
+      friendly_id :name, :use => :scoped, :scope => :city
+    end
+
+    class City < ActiveRecord::Base
+      extend FriendlyId
+      has_many :restaurants
+      friendly_id :name, :use => :slugged
+    end
+
+    City.find("seattle").restaurants.find("joes-diner")
+    City.find("chicago").restaurants.find("joes-diner")
+
+Without :scoped in this case, one of the restaurants would have the slug
++joes-diner+ and the other would have +joes-diner--2+.
+
+The value for the +:scope+ option can be the name of a +belongs_to+ relation, or
+a column.
+
+== Tips For Working With Scoped Slugs
+
+=== Finding Records by Friendly ID
+
+If you are using scopes your friendly ids may not be unique, so a simple find
+like
+
+    Restaurant.find("joes-diner")
+
+may return the wrong record. In these cases it's best to query through the
+relation:
+
+    @city.restaurants.find("joes-diner")
+
+Alternatively, you could pass the scope value as a query parameter:
+
+    Restaurant.find("joes-diner").where(:city_id => @city.id)
+
+
+=== Finding All Records That Match a Scoped ID
+
+Query the slug column directly:
+
+    Restaurant.find_all_by_slug("joes-diner")
+
+=== Routes for Scoped Models
+
+Recall that FriendlyId is a database-centric library, and does not set up any
+routes for scoped models. You must do this yourself in your application. Here's
+an example of one way to set this up:
+
+    # in routes.rb
+    resources :cities do
+      resources :restaurants
+    end
+
+    # in views
+    <%= link_to 'Show', [@city, @restaurant] %>
+
+    # in controllers
+    @city = City.find(params[:city_id])
+    @restaurant = @city.restaurants.find(params[:id])
+
+    # URLs:
+    http://example.org/cities/seattle/restaurants/joes-diner
+    http://example.org/cities/chicago/restaurants/joes-diner
+
+=end
   module Scoped
-    def self.included(klass)
-      klass.instance_eval do
+
+
+    # Sets up behavior and configuration options for FriendlyId's scoped slugs
+    # feature.
+    def self.included(model_class)
+      model_class.instance_eval do
         raise "FriendlyId::Scoped is incompatibe with FriendlyId::History" if self < History
         include Slugged unless self < Slugged
         friendly_id_config.class.send :include, Configuration
@@ -24,22 +91,37 @@ module FriendlyId
       end
     end
 
+    # This module adds the +:scope+ configuration option to
+    # {FriendlyId::Configuration FriendlyId::Configuration}.
     module Configuration
+
+      # Gets the scope value.
+      #
+      # When setting this value, the argument should be a symbol referencing a
+      # +belongs_to+ relation, or a column.
+      #
+      # @return Symbol The scope value
       attr_accessor :scope
 
       # Gets the scope column.
       #
-      # Checks to see if the +:scope+ option passed to {#friendly_id}
-      # refers to a relation, and if so, returns the realtion's foreign key.
-      # Otherwise it assumes the option value was the name of column and returns
-      # it cast to a String.
+      # Checks to see if the +:scope+ option passed to
+      # {FriendlyId::Base#friendly_id} refers to a relation, and if so, returns
+      # the realtion's foreign key. Otherwise it assumes the option value was
+      # the name of column and returns it cast to a String.
+      #
       # @return String The scope column
       def scope_column
-        (klass.reflections[@scope].try(:association_foreign_key) || @scope).to_s
+        (model_class.reflections[@scope].try(:association_foreign_key) || @scope).to_s
       end
     end
 
+    # This module overrides {FriendlyId::SlugSequencer#conflict} to consider
+    # scope, to avoid adding sequences to slugs under different scopes.
     module SlugSequencer
+
+      private
+
       def conflict
         column = friendly_id_config.scope_column
         conflicts.where("#{column} = ?", sluggable.send(column)).first

data/lib/friendly_id/slug.rb

@@ -1,3 +1,6 @@
+# A FriendlyId slug stored in an external table.
+#
+# @see FriendlyId::History
 class FriendlyIdSlug < ActiveRecord::Base
   belongs_to :sluggable, :polymorphic => true
 end

data/lib/friendly_id/slug_sequencer.rb

@@ -8,12 +8,14 @@ module FriendlyId
       @sluggable = sluggable
     end
 
+    # Given a slug, get the next available slug in the sequence.
     def next
       sequence = conflict.slug.split(separator)[1].to_i
       next_sequence = sequence == 0 ? 2 : sequence.next
       "#{normalized}#{separator}#{next_sequence}"
     end
 
+    # Generate a new sequenced slug.
     def generate
       if new_record? or slug_changed?
         conflict? ? self.next : normalized
@@ -22,6 +24,7 @@ module FriendlyId
       end
     end
 
+    # Whether or not the model instance's slug has changed.
     def slug_changed?
       separator = Regexp.escape friendly_id_config.sequence_separator
       base != sluggable.current_friendly_id.try(:sub, /#{separator}[\d]*\z/, '')

data/lib/friendly_id/slugged.rb

@@ -1,46 +1,218 @@
+# encoding: utf-8
 require "friendly_id/slug_sequencer"
 
 module FriendlyId
+=begin
+This module adds in-table slugs to a model.
 
-  # This module adds in-table slugs to an ActiveRecord model.
+Slugs are unique id strings that have been processed to remove or replace
+characters that a developer considers inconvenient for use in URLs. For example,
+blog applications typically use a post title to provide the basis of a search
+engine friendly URL:
+
+    "Gone With The Wind" -> "gone-with-the-wind"
+
+FriendlyId generates slugs from a method or column that you specify, and stores
+them in a field in your model. By default, this field must be named +:slug+,
+though you may change this using the
+{FriendlyId::Slugged::Configuration#slug_column slug_column} configuration
+option. You should add an index to this field. You may also wish to constrain it
+to NOT NULL, but this depends on your app's behavior and requirements.
+
+=== Example Setup
+
+    # your model
+    class Post < ActiveRecord::Base
+      extend FriendlyId
+      friendly_id :title, :use => :slugged
+      validates_presence_of :title, :slug, :body
+    end
+
+    # a migration
+    class CreatePosts < ActiveRecord::Migration
+      def self.up
+        create_table :posts do |t|
+          t.string :title, :null => false
+          t.string :slug, :null => false
+          t.text :body
+        end
+
+        add_index :posts, :slug, :unique => true
+      end
+
+      def self.down
+        drop_table :posts
+      end
+    end
+
+=== Slug Format
+
+By default, FriendlyId uses Active Support's
+paramaterize[http://api.rubyonrails.org/classes/ActiveSupport/Inflector.html#method-i-parameterize]
+method to create slugs. This method will intelligently replace spaces with
+dashes, and Unicode Latin characters with ASCII approximations:
+
+  movie = Movie.create! :title => "Der Preis fürs Überleben"
+  movie.slug #=> "der-preis-furs-uberleben"
+
+==== Slug Uniqueness
+
+When you try to insert a record that would generate a duplicate friendly id,
+FriendlyId will append a sequence to the generated slug to ensure uniqueness:
+
+  car = Car.create :title => "Peugot 206"
+  car2 = Car.create :title => "Peugot 206"
+
+  car.friendly_id #=> "peugot-206"
+  car2.friendly_id #=> "peugot-206--2"
+
+==== Changing the Slug Sequence Separator
+
+You can do this with the {Slugged::Configuration#sequence_separator
+sequence_separator} configuration option.
+
+==== Column or Method?
+
+FriendlyId always uses a method as the basis of the slug text - not a column. It
+first glance, this may sound confusing, but remember that Active Record provides
+methods for each column in a model's associated table, and that's what
+FriendlyId uses.
+
+Here's an example of a class that uses a custom method to generate the slug:
+
+  class Person < ActiveRecord::Base
+    friendly_id :name_and_location
+    def name_and_location
+      "#{name} from #{location}"
+    end
+  end
+
+  bob = Person.create! :name => "Bob Smith", :location => "New York City"
+  bob.friendly_id #=> "bob-smith-from-new-york-city"
+
+==== Providing Your Own Slug Processing Method
+
+You can override {Slugged#normalize_friendly_id} in your model for total
+control over the slug format.
+
+==== Locale-specific Transliterations
+
+Active Support's +parameterize+ uses
+transliterate[http://api.rubyonrails.org/classes/ActiveSupport/Inflector.html#method-i-transliterate],
+which in turn can use I18n's transliteration rules to consider the current
+locale when replacing Latin characters:
+
+  # config/locales/de.yml
+  de:
+    i18n:
+      transliterate:
+        rule:
+          ü: "ue"
+          ö: "oe"
+          etc...
+
+  movie = Movie.create! :title => "Der Preis fürs Überleben"
+  movie.slug #=> "der-preis-fuers-ueberleben"
+
+This functionality was in fact taken from earlier versions of FriendlyId.
+=end
   module Slugged
 
-    def self.included(klass)
-      klass.instance_eval do
+    # Sets up behavior and configuration options for FriendlyId's slugging
+    # feature.
+    def self.included(model_class)
+      model_class.instance_eval do
         friendly_id_config.class.send :include, Configuration
-        friendly_id_config.defaults[:slug_column]        = 'slug'
-        friendly_id_config.defaults[:sequence_separator] = '--'
-        friendly_id_config.slug_sequencer_class          = Class.new(SlugSequencer)
+        friendly_id_config.defaults[:slug_column]        ||= 'slug'
+        friendly_id_config.defaults[:sequence_separator] ||= '--'
+        friendly_id_config.slug_sequencer_class          ||= Class.new(SlugSequencer)
         before_validation :set_slug
       end
     end
 
+    # Process the given value to make it suitable for use as a slug.
+    #
+    # This method is not intended to be invoked directly; FriendlyId uses it
+    # internaly to process strings into slugs.
+    #
+    # However, if FriendlyId's default slug generation doesn't suite your needs,
+    # you can override this method in your model class to control exactly how
+    # slugs are generated.
+    #
+    # === Example
+    #
+    #   class Person < ActiveRecord::Base
+    #     friendly_id :name_and_location
+    #
+    #     def name_and_location
+    #       "#{name} from #{location}"
+    #     end
+    #
+    #     # Use default slug, but uupper case and with underscores
+    #     def normalize_friendly_id(string)
+    #       super.upcase.gsub("-", "_")
+    #     end
+    #   end
+    #
+    #   bob = Person.create! :name => "Bob Smith", :location => "New York City"
+    #   bob.friendly_id #=> "BOB_SMITH_FROM_NEW_YORK_CITY"
+    #
+    # === More Resources
+    #
+    # You might want to look into Babosa[https://github.com/norman/babosa],
+    # which is the slugging library used by FriendlyId prior to version 4, which
+    # offers some specialized functionality missing from Active Support.
+    #
+    # @param [#to_s] value The value used as the basis of the slug.
+    # @return The candidate slug text, without a sequence.
     def normalize_friendly_id(value)
       value.to_s.parameterize
     end
 
+    # Gets a new instance of the configured slug sequencing class.
+    #
+    # @see FriendlyId::SlugSequencer
     def slug_sequencer
       friendly_id_config.slug_sequencer_class.new(self)
     end
 
-    private
-
+    # Sets the slug.
     def set_slug
       send "#{friendly_id_config.slug_column}=", slug_sequencer.generate
     end
+    private :set_slug
 
+    # This module adds the +:slug_column+, and +:sequence_separator+, and
+    # +:slug_sequencer_class+ configuration options to
+    # {FriendlyId::Configuration FriendlyId::Configuration}.
     module Configuration
       attr_writer :slug_column, :sequence_separator
       attr_accessor :slug_sequencer_class
 
+      # Makes FriendlyId use the slug column for querying.
+      # @return String The slug column.
       def query_field
         slug_column
       end
 
+      # The string used to separate a slug base from a numeric sequence.
+      #
+      # By default, +--+ is used to separate the slug from the sequence.
+      # FriendlyId uses two dashes to distinguish sequences from slugs with
+      # numbers in their name.
+      #
+      # You can change the default separator by setting the
+      # {FriendlyId::Slugged::Configuration#sequence_separator
+      # sequence_separator} configuration option.
+      #
+      # For obvious reasons, you should avoid setting it to "+-+" unless you're
+      # sure you will never want to have a friendly id with a number in it.
+      # @return String The sequence separator string. Defaults to "+--+".
       def sequence_separator
         @sequence_separator or defaults[:sequence_separator]
       end
 
+      # The column that will be used to store the generated slug.
       def slug_column
         @slug_column or defaults[:slug_column]
       end