geothird_friendly_id 4.0.9.1

data/lib/friendly_id/base.rb

@@ -0,0 +1,291 @@
+module FriendlyId
+=begin
+
+== Setting Up FriendlyId in Your Model
+
+To use FriendlyId in your ActiveRecord models, you must first either extend or
+include the FriendlyId module (it makes no difference), then invoke the
+{FriendlyId::Base#friendly_id friendly_id} method to configure your desired
+options:
+
+    class Foo < ActiveRecord::Base
+      include FriendlyId
+      friendly_id :bar, :use => [:slugged, :simple_i18n]
+    end
+
+The most important option is `:use`, which you use to tell FriendlyId which
+addons it should use. See the documentation for this method for a list of all
+available addons, or skim through the rest of the docs to get a high-level
+overview.
+
+=== The Default Setup: Simple Models
+
+The simplest way to use FriendlyId is with a model that has a uniquely indexed
+column with no spaces or special characters, and that is seldom or never
+updated. The most common example of this is a user name:
+
+    class User < ActiveRecord::Base
+      extend FriendlyId
+      friendly_id :login
+      validates_format_of :login, :with => /\A[a-z0-9]+\z/i
+    end
+
+    @user = User.find "joe"   # the old User.find(1) still works, too
+    @user.to_param            # returns "joe"
+    redirect_to @user         # the URL will be /users/joe
+
+In this case, FriendlyId assumes you want to use the column as-is; it will never
+modify the value of the column, and your application should ensure that the
+value is unique and admissible in a URL:
+
+    class City < ActiveRecord::Base
+      extend FriendlyId
+      friendly_id :name
+    end
+
+    @city.find "Viña del Mar"
+    redirect_to @city # the URL will be /cities/Viña%20del%20Mar
+
+Writing the code to process an arbitrary string into a good identifier for use
+in a URL can be repetitive and surprisingly tricky, so for this reason it's
+often better and easier to use {FriendlyId::Slugged slugs}.
+
+=end
+  module Base
+
+    # Configure FriendlyId's behavior in a model.
+    #
+    #   class Post < ActiveRecord::Base
+    #     extend FriendlyId
+    #     friendly_id :title, :use => :slugged
+    #   end
+    #
+    # When given the optional block, this method will yield the class's instance
+    # of {FriendlyId::Configuration} to the block before evaluating other
+    # arguments, so configuration values set in the block may be overwritten by
+    # the arguments. This order was chosen to allow passing the same proc to
+    # multiple models, while being able to override the values it sets. Here is
+    # a contrived example:
+    #
+    #   $friendly_id_config_proc = Proc.new do |config|
+    #     config.base = :name
+    #     config.use :slugged
+    #   end
+    #
+    #   class Foo < ActiveRecord::Base
+    #     extend FriendlyId
+    #     friendly_id &$friendly_id_config_proc
+    #   end
+    #
+    #   class Bar < ActiveRecord::Base
+    #     extend FriendlyId
+    #     friendly_id :title, &$friendly_id_config_proc
+    #   end
+    #
+    # However, it's usually better to use {FriendlyId.defaults} for this:
+    #
+    #   FriendlyId.defaults do |config|
+    #     config.base = :name
+    #     config.use :slugged
+    #   end
+    #
+    #   class Foo < ActiveRecord::Base
+    #     extend FriendlyId
+    #   end
+    #
+    #   class Bar < ActiveRecord::Base
+    #     extend FriendlyId
+    #     friendly_id :title
+    #   end
+    #
+    # In general you should use the block syntax either because of your personal
+    # aesthetic preference, or because you need to share some functionality
+    # between multiple models that can't be well encapsulated by
+    # {FriendlyId.defaults}.
+    #
+    # === Order Method Calls in a Block vs Ordering Options
+    #
+    # When calling this method without a block, you may set the hash options in
+    # any order.
+    #
+    # However, when using block-style invocation, be sure to call
+    # FriendlyId::Configuration's {FriendlyId::Configuration#use use} method
+    # *prior* to the associated configuration options, because it will include
+    # modules into your class, and these modules in turn may add required
+    # configuration options to the +@friendly_id_configuraton+'s class:
+    #
+    #   class Person < ActiveRecord::Base
+    #     friendly_id do |config|
+    #       # This will work
+    #       config.use :slugged
+    #       config.sequence_separator = ":"
+    #     end
+    #   end
+    #
+    #   class Person < ActiveRecord::Base
+    #     friendly_id do |config|
+    #       # This will fail
+    #       config.sequence_separator = ":"
+    #       config.use :slugged
+    #     end
+    #   end
+    #
+    # === Including Your Own Modules
+    #
+    # Because :use can accept a name or a Module, {FriendlyId.defaults defaults}
+    # can be a convenient place to set up behavior common to all classes using
+    # FriendlyId. You can include any module, or more conveniently, define one
+    # on-the-fly. For example, let's say you want to make
+    # Babosa[http://github.com/norman/babosa] the default slugging library in
+    # place of Active Support, and transliterate all slugs from Russian Cyrillic
+    # to ASCII:
+    #
+    #   require "babosa"
+    #
+    #   FriendlyId.defaults do |config|
+    #     config.base = :name
+    #     config.use :slugged
+    #     config.use Module.new {
+    #       def normalize_friendly_id(text)
+    #         text.to_slug.normalize(:transliterations => [:russian, :latin])
+    #       end
+    #     }
+    #   end
+    #
+    #
+    # @option options [Symbol,Module] :use The addon or name of an addon to use.
+    #   By default, FriendlyId provides {FriendlyId::Slugged :slugged},
+    #   {FriendlyId::History :history}, {FriendlyId::Reserved :reserved}, and
+    #   {FriendlyId::Scoped :scoped}, {FriendlyId::SimpleI18n :simple_i18n},
+    #   and {FriendlyId::Globalize :globalize}.
+    #
+    # @option options [Array] :reserved_words Available when using +:reserved+,
+    #   which is loaded by default. Sets an array of words banned for use as
+    #   the basis of a friendly_id. By default this includes "edit" and "new".
+    #
+    # @option options [Symbol] :scope Available when using +:scoped+.
+    #   Sets the relation or column used to scope generated friendly ids. This
+    #   option has no default value.
+    #
+    # @option options [Symbol] :sequence_separator Available when using +:slugged+.
+    #   Configures the sequence of characters used to separate a slug from a
+    #   sequence. Defaults to +--+.
+    #
+    # @option options [Symbol] :slug_column Available when using +:slugged+.
+    #   Configures the name of the column where FriendlyId will store the slug.
+    #   Defaults to +:slug+.
+    #
+    # @option options [Symbol] :slug_generator_class Available when using +:slugged+.
+    #   Sets the class used to generate unique slugs. You should not specify this
+    #   unless you're doing some extensive hacking on FriendlyId. Defaults to
+    #   {FriendlyId::SlugGenerator}.
+    #
+    # @yield Provides access to the model class's friendly_id_config, which
+    #   allows an alternate configuration syntax, and conditional configuration
+    #   logic.
+    #
+    # @yieldparam config The model class's {FriendlyId::Configuration friendly_id_config}.
+    def friendly_id(base = nil, options = {}, &block)
+      yield friendly_id_config if block_given?
+      friendly_id_config.use options.delete :use
+      friendly_id_config.send :set, base ? options.merge(:base => base) : options
+      before_save {|rec| rec.instance_eval {@current_friendly_id = friendly_id}}
+      include Model
+    end
+
+    # Returns the model class's {FriendlyId::Configuration friendly_id_config}.
+    # @note In the case of Single Table Inheritance (STI), this method will
+    #   duplicate the parent class's FriendlyId::Configuration and relation class
+    #   on first access. If you're concerned about thread safety, then be sure
+    #   to invoke {#friendly_id} in your class for each model.
+    def friendly_id_config
+      @friendly_id_config ||= base_class.friendly_id_config.dup.tap do |config|
+        config.model_class = self
+        @relation_class = base_class.send(:relation_class)
+      end
+    end
+
+    private
+
+    # Gets an instance of an the relation class.
+    #
+    # With FriendlyId this will be a subclass of ActiveRecord::Relation, rather than
+    # Relation itself, in order to avoid tainting all Active Record models with
+    # FriendlyId.
+    #
+    # Note that this method is essentially copied and pasted from Rails 3.2.9.rc1,
+    # with the exception of changing the relation class. Obviously this is less than
+    # ideal, but I know of no better way to accomplish this.
+    # @see #relation_class
+    def relation #:nodoc:
+      relation = relation_class.new(self, arel_table)
+
+      if finder_needs_type_condition?
+        relation.where(type_condition).create_with(inheritance_column.to_sym => sti_name)
+      else
+        relation
+      end
+    end
+
+    # Gets (and if necessary, creates) a subclass of the model's relation class.
+    #
+    # Rather than including FriendlyId's overridden finder methods in
+    # ActiveRecord::Relation directly, FriendlyId adds them to a subclass
+    # specific to the AR model, and makes #relation return an instance of this
+    # class. By doing this, we ensure that only models that specifically extend
+    # FriendlyId have their finder methods overridden.
+    #
+    # Note that this method does not directly subclass ActiveRecord::Relation,
+    # but rather whatever class the @relation class instance variable is an
+    # instance of.  In practice, this will almost always end up being
+    # ActiveRecord::Relation, but in case another plugin is using this same
+    # pattern to extend a model's finder functionality, FriendlyId will not
+    # replace it, but rather override it.
+    #
+    # This pattern can be seen as a poor man's "refinement"
+    # (http://timelessrepo.com/refinements-in-ruby), and while I **think** it
+    # will work quite well, I realize that it could cause unexpected issues,
+    # since the authors of Rails are probably not intending this kind of usage
+    # against a private API. If this ends up being problematic I will probably
+    # revert back to the old behavior of simply extending
+    # ActiveRecord::Relation.
+    def relation_class
+      @relation_class or begin
+        @relation_class = Class.new(relation_without_friendly_id.class) do
+          alias_method :find_one_without_friendly_id, :find_one
+          alias_method :exists_without_friendly_id?, :exists?
+          include FriendlyId::FinderMethods
+        end
+        # Set a name so that model instances can be marshalled. Use a
+        # ridiculously long name that will not conflict with anything.
+        # TODO: just use the constant, no need for the @relation_class variable.
+        const_set('FriendlyIdActiveRecordRelation', @relation_class)
+      end
+    end
+  end
+
+  # 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
+      if diff = changes[friendly_id_config.query_field]
+        diff.first || diff.second
+      else
+        friendly_id.presence || super
+      end
+    end
+  end
+end

data/lib/friendly_id/configuration.rb

@@ -0,0 +1,80 @@
+module FriendlyId
+  # The configuration paramters passed to +friendly_id+ will be stored in
+  # this object.
+  class Configuration
+
+    # The base column or method used by FriendlyId as the basis of a friendly id
+    # or slug.
+    #
+    # For models that don't use FriendlyId::Slugged, the base is the column that
+    # is used as the FriendlyId directly. For models using FriendlyId::Slugged,
+    # the base is a column or method whose value is used as the basis of the
+    # slug.
+    #
+    # For example, if you have a model representing blog posts and that uses
+    # slugs, you likely will want to use the "title" attribute as the base, and
+    # FriendlyId will take care of transforming the human-readable title into
+    # something suitable for use in a URL.
+    #
+    # @param [Symbol] A symbol referencing a column or method in the model. This
+    #   value is usually set by passing it as the first argument to
+    #   {FriendlyId::Base#friendly_id friendly_id}:
+    #
+    # @example
+    #   class Book < ActiveRecord::Base
+    #     extend FriendlyId
+    #     friendly_id :name
+    #   end
+    attr_accessor :base
+
+    # The default configuration options.
+    attr_reader :defaults
+
+    # The model class that this configuration belongs to.
+    # @return ActiveRecord::Base
+    attr_accessor :model_class
+
+    def initialize(model_class, values = nil)
+      @model_class = model_class
+      @defaults    = {}
+      set values
+    end
+
+    # Lets you specify the modules to use with FriendlyId.
+    #
+    # This method is invoked by {FriendlyId::Base#friendly_id friendly_id} when
+    # passing the +:use+ option, or when using {FriendlyId::Base#friendly_id
+    # friendly_id} with a block.
+    #
+    # @example
+    #   class Book < ActiveRecord::Base
+    #     extend FriendlyId
+    #     friendly_id :name, :use => :slugged
+    #   end
+    # @param [#to_s,Module] *modules Arguments should be Modules, or symbols or
+    #   strings that correspond with the name of a module inside the FriendlyId
+    #   namespace. By default FriendlyId provides +:slugged+, +:history+,
+    #   +:simple_i18n+, +:globalize+, and +:scoped+.
+    def use(*modules)
+      modules.to_a.flatten.compact.map do |object|
+        mod = object.kind_of?(Module) ? object : FriendlyId.const_get(object.to_s.classify)
+        model_class.send(:include, mod)
+      end
+    end
+
+    # The column that FriendlyId will use to find the record when querying by
+    # friendly id.
+    #
+    # This method is generally only used internally by FriendlyId.
+    # @return String
+    def query_field
+      base.to_s
+    end
+
+    private
+
+    def set(values)
+      values and values.each {|name, value| self.send "#{name}=", value}
+    end
+  end
+end

data/lib/friendly_id/finder_methods.rb

@@ -0,0 +1,35 @@
+module FriendlyId
+  # These methods will be added to the model's {FriendlyId::Base#relation_class relation_class}.
+  module FinderMethods
+
+    protected
+
+    # FriendlyId overrides this method to make it possible to use friendly id's
+    # identically to numeric ids in finders.
+    #
+    # @example
+    #  person = Person.find(123)
+    #  person = Person.find("joe")
+    #
+    # @see FriendlyId::ObjectUtils
+    def find_one(id)
+      return super if id.unfriendly_id?
+      where(@klass.friendly_id_config.query_field => id).first or super
+    end
+
+    # FriendlyId overrides this method to make it possible to use friendly id's
+    # identically to numeric ids in finders.
+    #
+    # @example
+    #  person = Person.exists?(123)
+    #  person = Person.exists?("joe")
+    #  person = Person.exists?({:name => 'joe'})
+    #  person = Person.exists?(['name = ?', 'joe'])
+    #
+    # @see FriendlyId::ObjectUtils
+    def exists?(id = false)
+      return super if id.unfriendly_id?
+      super @klass.friendly_id_config.query_field => id
+    end
+  end
+end

data/lib/friendly_id/globalize.rb

@@ -0,0 +1,115 @@
+require 'i18n'
+
+module FriendlyId
+
+=begin
+
+== Translating Slugs Using Globalize
+
+The {FriendlyId::Globalize Globalize} module lets you use
+Globalize[https://github.com/svenfuchs/globalize3] to translate slugs. This
+module is most suitable for applications that need to be localized to many
+languages. If your application only needs to be localized to one or two
+languages, you may wish to consider the {FriendlyId::SimpleI18n SimpleI18n}
+module.
+
+In order to use this module, your model's table and translation table must both
+have a slug column, and your model must set the +slug+ field as translatable
+with Globalize:
+
+    class Post < ActiveRecord::Base
+      translates :title, :slug
+      extend FriendlyId
+      friendly_id :title, :use => :globalize
+    end
+
+=== Finds
+
+Finds will take the current locale into consideration:
+
+  I18n.locale = :it
+  Post.find("guerre-stellari")
+  I18n.locale = :en
+  Post.find("star-wars")
+
+Additionally, finds will fall back to the default locale:
+
+  I18n.locale = :it
+  Post.find("star-wars")
+
+To find a slug by an explicit locale, perform the find inside a block
+passed to I18n's +with_locale+ method:
+
+  I18n.with_locale(:it) { Post.find("guerre-stellari") }
+
+=== Creating Records
+
+When new records are created, the slug is generated for the current locale only.
+
+=== Translating Slugs
+
+To translate an existing record's friendly_id, use
+{FriendlyId::Globalize::Model#set_friendly_id}. This will ensure that the slug
+you add is properly escaped, transliterated and sequenced:
+
+  post = Post.create :name => "Star Wars"
+  post.set_friendly_id("Guerre stellari", :it)
+
+If you don't pass in a locale argument, FriendlyId::Globalize will just use the
+current locale:
+
+  I18n.with_locale(:it) { post.set_friendly_id("Guerre stellari") }
+
+=end
+  module Globalize
+
+    def self.included(model_class)
+      model_class.instance_eval do
+        friendly_id_config.use :slugged
+        relation_class.send :include, FinderMethods
+        include Model
+        # Check if slug field is enabled to be translated with Globalize
+        unless respond_to?('translated_attribute_names') || translated_attribute_names.exclude?(friendly_id_config.query_field.to_sym)
+          puts "\n[FriendlyId] You need to translate '#{friendly_id_config.query_field}' field with Globalize (add 'translates :#{friendly_id_config.query_field}' in your model '#{self.class.name}')\n\n"
+        end
+      end
+    end
+
+    module Model
+      def set_friendly_id(text, locale)
+        I18n.with_locale(locale || I18n.locale) do
+          set_slug(normalize_friendly_id(text))
+        end
+      end
+    end
+
+    module FinderMethods
+      # FriendlyId overrides this method to make it possible to use friendly id's
+      # identically to numeric ids in finders.
+      #
+      # @example
+      #  person = Person.find(123)
+      #  person = Person.find("joe")
+      #
+      # @see FriendlyId::ObjectUtils
+      def find_one(id)
+        return super if id.unfriendly_id?
+        found = where(@klass.friendly_id_config.query_field => id).first
+        found = includes(:translations).
+                where(translation_class.arel_table[:locale].in([I18n.locale, I18n.default_locale])).
+                where(translation_class.arel_table[@klass.friendly_id_config.query_field].eq(id)).first if found.nil?
+
+        if found
+          # Reload the translations for the found records.
+          found.tap { |f| f.translations.reload }
+        else
+          # if locale is not translated fallback to default locale
+          super
+        end
+      end
+
+      protected :find_one
+
+    end
+  end
+end

data/lib/friendly_id/history.rb

@@ -0,0 +1,134 @@
+module FriendlyId
+
+=begin
+
+== History: Avoiding 404's When Slugs Change
+
+FriendlyId's {FriendlyId::History History} 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
+        @post = Post.find params[:id]
+
+        # 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(model_class)
+      model_class.instance_eval do
+        raise "FriendlyId::History is incompatible with FriendlyId::Scoped" if self < Scoped
+        @friendly_id_config.use :slugged
+        has_many :slugs, :as => :sluggable, :dependent => :destroy,
+          :class_name => Slug.to_s, :order => "#{Slug.quoted_table_name}.id DESC"
+        after_save :create_slug
+        relation_class.send :include, FinderMethods
+        friendly_id_config.slug_generator_class.send :include, SlugGenerator
+      end
+    end
+
+    private
+
+    def create_slug
+      return unless friendly_id
+      return if slugs.first.try(:slug) == friendly_id
+      # Allow reversion back to a previously used slug
+      relation = slugs.where(:slug => friendly_id)
+      result = relation.select("id").lock(true).all
+      relation.delete_all unless result.empty?
+      slugs.create! do |record|
+        record.slug = friendly_id
+      end
+    end
+
+    # Adds a finder that explictly uses slugs from the slug table.
+    module FinderMethods
+
+      # Search for a record in the slugs table using the specified slug.
+      def find_one(id)
+        return super(id) if id.unfriendly_id?
+        where(@klass.friendly_id_config.query_field => id).first or
+        with_old_friendly_id(id) {|x| find_one_without_friendly_id(x)} or
+        find_one_without_friendly_id(id)
+      end
+
+      # Search for a record in the slugs table using the specified slug.
+      def exists?(id = false)
+        return super if id.unfriendly_id?
+        exists_without_friendly_id?(@klass.friendly_id_config.query_field => id) or
+        with_old_friendly_id(id) {|x| exists_without_friendly_id?(x)} or
+        exists_without_friendly_id?(id)
+      end
+
+      private
+
+      # Accepts a slug, and yields a corresponding sluggable_id into the block.
+      def with_old_friendly_id(slug, &block)
+        sql = "SELECT sluggable_id FROM #{Slug.quoted_table_name} WHERE sluggable_type = %s AND slug = %s"
+        sql = sql % [@klass.base_class.to_s, slug].map {|x| connection.quote(x)}
+        sluggable_id = connection.select_values(sql).first
+        yield sluggable_id if sluggable_id
+      end
+    end
+
+    # This module overrides {FriendlyId::SlugGenerator#conflicts} to consider
+    # all historic slugs for that model.
+    module SlugGenerator
+
+      private
+
+      def conflicts
+        sluggable_class = friendly_id_config.model_class.base_class
+        pkey            = sluggable_class.primary_key
+        value           = sluggable.send pkey
+
+        scope = Slug.where("slug = ? OR slug LIKE ?", normalized, wildcard)
+        scope = scope.where(:sluggable_type => sluggable_class.to_s)
+        scope = scope.where("sluggable_id <> ?", value) unless sluggable.new_record?
+        scope.order("LENGTH(slug) DESC, slug DESC")
+      end
+    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