friendly_id 3.3.3.0 → 4.0.0.beta7

data/lib/friendly_id/history.rb

@@ -0,0 +1,88 @@
+require "friendly_id/slug"
+
+module FriendlyId
+
+=begin
+This module adds the ability to store a log of a model's slugs, so that when its
+friendly id changes, it's still possible to perform finds by the old id.
+
+The primary use case for this is avoiding broken URLs.
+
+== Setup
+
+In order to use this module, you must add a table to your database schema to
+store the slug records. FriendlyId provides a generator for this purpose:
+
+  rails generate friendly_id
+  rake db:migrate
+
+This will add a table named +friendly_id_slugs+, used by the {FriendlyId::Slug}
+model.
+
+== Considerations
+
+This module is incompatible with the +:scoped+ module.
+
+Because recording slug history requires creating additional database records,
+this module has an impact on the performance of the associated model's +create+
+method.
+
+== Example
+
+    class Post < ActiveRecord::Base
+      extend FriendlyId
+      friendly_id :title, :use => :history
+    end
+
+    class PostsController < ApplicationController
+
+      before_filter :find_post
+
+      ...
+
+      def find_post
+        return unless params[:id]
+        @post = begin
+          Post.find params[:id]
+        rescue ActiveRecord::RecordNotFound
+          Post.find_by_friendly_id params[:id]
+        end
+        # If an old id or a numeric id was used to find the record, then
+        # the request path will not match the post_path, and we should do
+        # a 301 redirect that uses the current friendly id.
+        if request.path != post_path(@post)
+          return redirect_to @post, :status => :moved_permanently
+        end
+      end
+    end
+=end
+  module History
+
+    # Configures the model instance to use the History add-on.
+    def self.included(klass)
+      klass.instance_eval do
+        raise "FriendlyId::History is incompatibe with FriendlyId::Scoped" if self < Scoped
+        @friendly_id_config.use :slugged
+        has_many :slugs, :as => :sluggable, :dependent => :destroy, :class_name => "FriendlyId::Slug"
+        before_save :build_slug, :if => lambda {|r| r.slug_sequencer.slug_changed?}
+        scope :with_friendly_id, lambda {|id| includes(:slugs).where("friendly_id_slugs.slug = ?", id)}
+        extend Finder
+      end
+    end
+
+    private
+
+    def build_slug
+      slugs.build :slug => friendly_id
+    end
+  end
+
+  # Adds a finder that explictly uses slugs from the slug table.
+  module Finder
+
+    # Search for a record in the slugs table using the specified slug.
+    def find_by_friendly_id(*args)
+      with_friendly_id(args.shift).first(*args)
+    end
+  end
+end

data/lib/friendly_id/migration.rb

@@ -0,0 +1,18 @@
+class CreateFriendlyIdSlugs < ActiveRecord::Migration
+
+  def self.up
+    create_table :friendly_id_slugs do |t|
+      t.string   :slug,           :null => false
+      t.integer  :sluggable_id,   :null => false
+      t.string   :sluggable_type, :limit => 40
+      t.datetime :created_at
+    end
+    add_index :friendly_id_slugs, :sluggable_id
+    add_index :friendly_id_slugs, [:slug, :sluggable_type], :unique => true
+    add_index :friendly_id_slugs, :sluggable_type
+  end
+
+  def self.down
+    drop_table :friendly_id_slugs
+  end
+end

data/lib/friendly_id/model.rb

@@ -0,0 +1,22 @@
+module FriendlyId
+  # Instance methods that will be added to all classes using FriendlyId.
+  module Model
+
+    attr_reader :current_friendly_id
+
+    # Convenience method for accessing the class method of the same name.
+    def friendly_id_config
+      self.class.friendly_id_config
+    end
+
+    # Get the instance's friendly_id.
+    def friendly_id
+      send friendly_id_config.query_field
+    end
+
+    # Either the friendly_id, or the numeric id cast to a string.
+    def to_param
+      (friendly_id.present? ? friendly_id : id).to_s
+    end
+  end
+end

data/lib/friendly_id/object_utils.rb

@@ -0,0 +1,40 @@
+module FriendlyId
+  # 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,
+    # else nil.
+    #
+    # 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
+      elsif respond_to?(:to_i) && to_i.to_s != to_s
+        true
+      end
+    end
+
+    # True if the id is definitely unfriendly, false if definitely friendly,
+    # else nil.
+    def unfriendly_id?
+      val = friendly_id? ; !val unless val.nil?
+    end
+  end
+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

@@ -0,0 +1,131 @@
+require "friendly_id/slugged"
+
+module FriendlyId
+
+=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
+
+
+    # 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
+        friendly_id_config.slug_sequencer_class.send :include, SlugSequencer
+      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
+      # {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
+        (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
+      end
+    end
+  end
+end

data/lib/friendly_id/slug.rb

@@ -0,0 +1,9 @@
+module FriendlyId
+  # A FriendlyId slug stored in an external table.
+  #
+  # @see FriendlyId::History
+  class Slug < ActiveRecord::Base
+    self.table_name = "friendly_id_slugs"
+    belongs_to :sluggable, :polymorphic => true
+  end
+end

data/lib/friendly_id/slug_sequencer.rb

@@ -0,0 +1,82 @@
+module FriendlyId
+  # This class offers functionality to check slug strings for uniqueness and,
+  # if necessary, append a sequence to ensure it.
+  class SlugSequencer
+    attr_reader :sluggable
+
+    def initialize(sluggable)
+      @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
+      else
+        sluggable.friendly_id
+      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/, '')
+    end
+
+    private
+
+    def base
+      sluggable.send friendly_id_config.base
+    end
+
+    def column
+      sluggable.connection.quote_column_name friendly_id_config.query_field
+    end
+
+    def conflict?
+      !! conflict
+    end
+
+    def conflict
+      unless defined? @conflict
+        @conflict = conflicts.first
+      end
+      @conflict
+    end
+
+    def conflicts
+      pkey  = sluggable.class.primary_key
+      value = sluggable.send pkey
+      scope = sluggable.class.where("#{column} = ? OR #{column} LIKE ?", normalized, wildcard)
+      scope = scope.where("#{pkey} <> ?", value) unless sluggable.new_record?
+      scope = scope.order("LENGTH(#{column}) DESC, #{column} DESC")
+    end
+
+    def friendly_id_config
+      sluggable.friendly_id_config
+    end
+
+    def new_record?
+      sluggable.new_record?
+    end
+
+    def normalized
+      @normalized ||= sluggable.normalize_friendly_id(base)
+    end
+
+    def separator
+      friendly_id_config.sequence_separator
+    end
+
+    def wildcard
+      "#{normalized}#{separator}%"
+    end
+  end
+end