mil_friendly_id 4.0.9.8

data/lib/friendly_id/scoped.rb

@@ -0,0 +1,149 @@
+require "friendly_id/slugged"
+
+module FriendlyId
+
+=begin
+
+== Unique Slugs by Scope
+
+The {FriendlyId::Scoped} 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.
+
+=== 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_generator_class.send :include, SlugGenerator
+      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 columns.
+      #
+      # 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_columns
+        [@scope].flatten.map { |s| (reflection_foreign_key(s) or s).to_s }
+      end
+
+      private
+
+      if ActiveRecord::VERSION::STRING < "3.1"
+        def reflection_foreign_key(scope)
+          model_class.reflections[scope].try(:primary_key_name)
+        end
+      else
+        def reflection_foreign_key(scope)
+          model_class.reflections[scope].try(:foreign_key)
+        end
+      end
+    end
+
+    # This module overrides {FriendlyId::SlugGenerator#conflict} to consider
+    # scope, to avoid adding sequences to slugs under different scopes.
+    module SlugGenerator
+
+      private
+
+      def conflict
+        columns = friendly_id_config.scope_columns
+        matched = columns.inject(conflicts) do |memo, column|
+           memo.with_deleted.where(column => sluggable.send(column))
+        end
+
+        matched.first
+      end
+    end
+  end
+end

data/lib/friendly_id/simple_i18n.rb

@@ -0,0 +1,95 @@
+require "i18n"
+
+module FriendlyId
+
+=begin
+
+== Translating Slugs Using Simple I18n
+
+The {FriendlyId::SimpleI18n SimpleI18n} module adds very basic i18n support to
+FriendlyId.
+
+In order to use this module, your model must have a slug column for each locale.
+By default FriendlyId looks for columns named, for example, "slug_en",
+"slug_es", etc. The first part of the name can be configured by passing the
++:slug_column+ option if you choose. Note that the column for the default locale
+must also include the locale in its name.
+
+This module is most suitable to applications that need to support few locales.
+If you need to support two or more locales, you may wish to use the
+{FriendlyId::Globalize Globalize} module instead.
+
+=== Example migration
+
+  def self.up
+    create_table :posts do |t|
+      t.string :title
+      t.string :slug_en
+      t.string :slug_es
+      t.text   :body
+    end
+    add_index :posts, :slug_en
+    add_index :posts, :slug_es
+  end
+
+=== Finds
+
+Finds will take into consideration the current locale:
+
+  I18n.locale = :es
+  Post.find("la-guerra-de-las-galaxas")
+  I18n.locale = :en
+  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(:es) do
+    Post.find("la-guerra-de-las-galaxas")
+  end
+
+=== 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::SimpleI18n::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("La guerra de las galaxas", :es)
+
+If you don't pass in a locale argument, FriendlyId::SimpleI18n will just use the
+current locale:
+
+  I18n.with_locale(:es) do
+    post.set_friendly_id("La guerra de las galaxas")
+  end
+=end
+  module SimpleI18n
+
+    def self.included(model_class)
+      model_class.instance_eval do
+        friendly_id_config.use :slugged
+        friendly_id_config.class.send :include, Configuration
+        include Model
+      end
+    end
+
+    module Model
+      def set_friendly_id(text, locale = nil)
+        I18n.with_locale(locale || I18n.locale) do
+          set_slug(normalize_friendly_id(text))
+        end
+      end
+    end
+
+    module Configuration
+      def slug_column
+        "#{super}_#{I18n.locale}"
+      end
+    end
+  end
+end

data/lib/friendly_id/slug.rb

@@ -0,0 +1,14 @@
+module FriendlyId
+  # A FriendlyId slug stored in an external table.
+  #
+  # @see FriendlyId::History
+  class Slug < ActiveRecord::Base
+    acts_as_paranoid column_type: 'boolean'
+    belongs_to :sluggable, :polymorphic => true
+
+    def to_param
+      slug
+    end
+
+  end
+end

data/lib/friendly_id/slug_generator.rb

@@ -0,0 +1,80 @@
+module FriendlyId
+  # The default slug generator offers functionality to check slug strings for
+  # uniqueness and, if necessary, appends a sequence to guarantee it.
+  class SlugGenerator
+    attr_reader :sluggable, :normalized
+
+    # Create a new slug generator.
+    def initialize(sluggable, normalized)
+      @sluggable  = sluggable
+      @normalized = normalized
+    end
+
+    # Given a slug, get the next available slug in the sequence.
+    def next
+      "#{normalized}#{separator}#{next_in_sequence}"
+    end
+
+    # Generate a new sequenced slug.
+    def generate
+      conflict? ? self.next : normalized
+    end
+
+    private
+
+    def next_in_sequence
+      last_in_sequence == 0 ? 2 : last_in_sequence.next
+    end
+
+    def last_in_sequence
+      @_last_in_sequence ||= extract_sequence_from_slug(conflict.to_param)
+    end
+
+    def extract_sequence_from_slug(slug)
+      slug.split("#{normalized}#{separator}").last.to_i
+    end
+
+    def column
+      sluggable.connection.quote_column_name friendly_id_config.slug_column
+    end
+
+    def conflict?
+      !! conflict
+    end
+
+    def conflict
+      unless defined? @conflict
+        @conflict = conflicts.first
+      end
+      @conflict
+    end
+
+    def conflicts
+      sluggable_class = friendly_id_config.model_class.base_class
+
+      pkey  = sluggable_class.primary_key
+      value = sluggable.send pkey
+      base = "#{column} = ? OR #{column} LIKE ?"
+      # Awful hack for SQLite3, which does not pick up '\' as the escape character without this.
+      base << "ESCAPE '\\'" if sluggable.connection.adapter_name =~ /sqlite/i
+      scope = sluggable_class.unscoped.with_deleted.where(base, 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 separator
+      friendly_id_config.sequence_separator
+    end
+
+    def wildcard
+      # Underscores (matching a single character) and percent signs (matching
+      # any number of characters) need to be escaped
+      # (While this seems like an excessive number of backslashes, it is correct)
+      "#{normalized}#{separator}".gsub(/[_%]/, '\\\\\&') + '%'
+    end
+  end
+end

data/lib/friendly_id/slugged.rb

@@ -0,0 +1,329 @@
+# encoding: utf-8
+require "friendly_id/slug_generator"
+
+module FriendlyId
+=begin
+
+== Slugged Models
+
+FriendlyId can use a separate column to store slugs for models which require
+some text processing.
+
+For example, blog applications typically use a post title to provide the basis
+of a search engine friendly URL. Such identifiers typically lack uppercase
+characters, use ASCII to approximate UTF-8 character, and strip out other
+characters which may make them aesthetically unappealing or error-prone when
+used in a URL.
+
+    class Post < ActiveRecord::Base
+      extend FriendlyId
+      friendly_id :title, :use => :slugged
+    end
+
+    @post = Post.create(:title => "This is the first post!")
+    @post.friendly_id   # returns "this-is-the-first-post"
+    redirect_to @post   # the URL will be /posts/this-is-the-first-post
+
+In general, use slugs by default unless you know for sure you don't need them.
+To activate the slugging functionality, use the {FriendlyId::Slugged} module.
+
+FriendlyId will generate slugs from a method or column that you specify, and
+store 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 column, and in most cases, make it
+unique. 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
+
+=== Working With Slugs
+
+==== Formatting
+
+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"
+
+==== 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"
+
+==== Sequence Separator - The Two Dashes
+
+By default, FriendlyId uses two dashes to separate the slug from a sequence.
+
+You can change this with the {FriendlyId::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 {FriendlyId::Slugged#normalize_friendly_id} in your model for
+total control over the slug format.
+
+==== Deciding When to Generate New Slugs
+
+Overriding {FriendlyId::Slugged#should_generate_new_friendly_id?} lets you
+control whether new friendly ids are created when a model is updated. For
+example, if you only want to generate slugs once and then treat them as
+read-only:
+
+  class Post < ActiveRecord::Base
+    extend FriendlyId
+    friendly_id :title, :use => :slugged
+
+    def should_generate_new_friendly_id?
+      new_record?
+    end
+  end
+
+  post = Post.create!(:title => "Hello world!")
+  post.slug #=> "hello-world"
+  post.title = "Hello there, world!"
+  post.save!
+  post.slug #=> "hello-world"
+
+==== 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.
+
+==== Gotchas: Common Problems
+
+===== Slugs That Begin With Numbers
+
+Ruby's `to_i` function casts strings to integers in such a way that +23abc.to_i+
+returns 23. Because FriendlyId falls back to finding by numeric id, this means
+that if you attempt to find a record with a non-existant slug, and that slug
+begins with a number, your find will probably return the wrong record.
+
+There are two fairly simple ways to avoid this:
+
+* Use validations to ensure that slugs don't begin with numbers.
+* Use explicit finders like +find_by_id+ to always find by the numeric id, or
+  +find_by_slug+ to always find using the friendly id.
+
+===== Concurrency Issues
+
+FriendlyId uses a before_validation callback to generate and set the slug. This
+means that if you create two model instances before saving them, it's possible
+they will generate the same slug, and the second save will fail.
+
+This can happen in two fairly normal cases: the first, when a model using nested
+attributes creates more than one record for a model that uses friendly_id. The
+second, in concurrent code, either in threads or multiple processes.
+
+To solve the nested attributes issue, I recommend simply avoiding them when
+creating more than one nested record for a model that uses FriendlyId. See {this
+Github issue}[https://github.com/norman/friendly_id/issues/185] for discussion.
+
+To solve the concurrency issue, I recommend locking the model's table against
+inserts while when saving the record. See {this Github
+issue}[https://github.com/norman/friendly_id/issues/180] for discussion.
+
+=end
+  module Slugged
+
+    # Sets up behavior and configuration options for FriendlyId's slugging
+    # feature.
+    def self.included(model_class)
+      model_class.friendly_id_config.instance_eval do
+        self.class.send :include, Configuration
+        self.slug_generator_class     ||= Class.new(SlugGenerator)
+        defaults[:slug_column]        ||= 'slug'
+        defaults[:sequence_separator] ||= '--'
+      end
+      model_class.before_validation :set_slug
+    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 upper 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)
+      # Fix to number based slugs which get mistaken as id's
+      value = value.to_s.parameterize
+      is_number = true if Float(value) rescue false
+      if is_number
+        return "#{rand_slug}#{value}"
+      end
+      value
+    end
+
+    # Generate random 10 character string for use in number error situations
+    # Instead of rejecting id/number based slug
+    def rand_slug
+      (0...10).map{ ('a'..'z').to_a[rand(26)] }.join
+    end
+
+    # Whether to generate a new slug.
+    #
+    # You can override this method in your model if, for example, you only want
+    # slugs to be generated once, and then never updated.
+    def should_generate_new_friendly_id?
+      base       = send(friendly_id_config.base)
+      slug_value = send(friendly_id_config.slug_column)
+
+      # If the slug base is nil, and the slug field is nil, then we're going to
+      # leave the slug column NULL.
+      return false if base.nil? && slug_value.nil?
+      # Otherwise, if this is a new record, we're definitely going to try to
+      # create a new slug.
+      return true if new_record?
+      slug_base = normalize_friendly_id(base)
+      separator = Regexp.escape friendly_id_config.sequence_separator
+      # If the slug base (with and without sequence) is different from either the current
+      # friendly id or the slug value, then we'll generate a new friendly_id.
+      compare = (current_friendly_id || slug_value)
+      slug_base != compare && slug_base != compare.try(:sub, /#{separator}[\d]*\z/, '')
+    end
+
+    # Sets the slug.
+    # FIXME: This method sucks and the logic is pretty dubious.
+    def set_slug(normalized_slug = nil)
+      if normalized_slug || should_generate_new_friendly_id?
+        normalized_slug ||= normalize_friendly_id send(friendly_id_config.base)
+        generator = friendly_id_config.slug_generator_class.new self, normalized_slug
+        send "#{friendly_id_config.slug_column}=", generator.generate
+      end
+    end
+    private :set_slug
+
+    # This module adds the +:slug_column+, and +:sequence_separator+, and
+    # +:slug_generator_class+ configuration options to
+    # {FriendlyId::Configuration FriendlyId::Configuration}.
+    module Configuration
+      attr_writer :slug_column, :sequence_separator
+      attr_accessor :slug_generator_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
+    end
+  end
+end