friendly_id 3.3.3.0 → 4.0.0.beta7

data/lib/friendly_id/slugged.rb

@@ -1,105 +1,220 @@
-module FriendlyId
-  module Slugged
+# encoding: utf-8
+require "friendly_id/slug_sequencer"
 
-    class Status < FriendlyId::Status
+module FriendlyId
+=begin
+This module adds in-table slugs to a 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
 
-      attr_accessor :sequence, :slug
+    # 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
 
-      # Did the find operation use the best possible id? True if +id+ is
-      # numeric, but the model has no slug, or +id+ is friendly and current
-      def best?
-        current? || (numeric? && !record.slug)
+        add_index :posts, :slug, :unique => true
       end
 
-      # Did the find operation use the current slug?
-      def current?
-        !! slug && slug.current?
+      def self.down
+        drop_table :posts
       end
+    end
 
-      # Did the find operation use a friendly id?
-      def friendly?
-        !! (name or slug)
-      end
+=== Slug Format
 
-      def friendly_id=(friendly_id)
-        @name, @sequence = friendly_id.parse_friendly_id(record.friendly_id_config.sequence_separator)
-      end
+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:
 
-      # Did the find operation use an outdated slug?
-      def outdated?
-        !current?
-      end
+  movie = Movie.create! :title => "Der Preis fürs Überleben"
+  movie.slug #=> "der-preis-furs-uberleben"
 
-      # The slug that was used to find the model.
-      def slug
-        @slug ||= record.find_slug(name, sequence)
-      end
+==== 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
 
-    module Model
-      attr_accessor :slug
+  bob = Person.create! :name => "Bob Smith", :location => "New York City"
+  bob.friendly_id #=> "bob-smith-from-new-york-city"
 
-      def find_slug
-        raise NotImplementedError
-      end
+==== Providing Your Own Slug Processing Method
 
-      def friendly_id_config
-        self.class.friendly_id_config
-      end
+You can override {Slugged#normalize_friendly_id} in your model for total
+control over the slug format.
 
-      # Get the {FriendlyId::Status} after the find has been performed.
-      def friendly_id_status
-        @friendly_id_status ||= Status.new(:record => self)
-      end
+==== Locale-specific Transliterations
 
-      # The friendly id.
-      # @param
-      def friendly_id(skip_cache = false)
-        if friendly_id_config.cache_column? && !skip_cache
-          friendly_id = send(friendly_id_config.cache_column)
-        end
-        friendly_id || (slug.to_friendly_id if slug?)
-      end
+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:
 
-      # Clean up the string before setting it as the friendly_id. You can override
-      # this method to add your own custom normalization routines.
-      # @param string An instance of {FriendlyId::SlugString}.
-      # @return [String]
-      def normalize_friendly_id(string)
-        string.normalize_for!(friendly_id_config).to_s
-      end
+  # config/locales/de.yml
+  de:
+    i18n:
+      transliterate:
+        rule:
+          ü: "ue"
+          ö: "oe"
+          etc...
 
-      # Does the instance have a slug?
-      def slug?
-        !! slug
+  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
+
+    # 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)
+        before_validation :set_slug
       end
+    end
 
-      private
+    # 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
 
-      # Get the processed string used as the basis of the friendly id.
-      def slug_text
-        text = send(friendly_id_config.method)
-        text = normalize_friendly_id(SlugString.new(text)) unless text.nil?
-        text = nil if text.blank?
-        unless text.nil? && friendly_id_config.allow_nil?
-          SlugString.new(text).validate_for!(friendly_id_config).to_s
-        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
+
+    # 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
 
-      # Has the slug text changed?
-      def slug_text_changed?
-        slug_text != slug.name
+      # 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
 
-      # Has the basis of our friendly id changed, requiring the generation of a
-      # new slug?
-      def new_slug_needed?
-        if friendly_id_config.allow_nil?
-          (!slug? && !slug_text.blank?) || (slug? && slug_text_changed?)
-        else
-          !slug? || slug_text_changed?
-        end
+      # The column that will be used to store the generated slug.
+      def slug_column
+        @slug_column or defaults[:slug_column]
       end
     end
   end

data/lib/friendly_id/version.rb

@@ -2,8 +2,8 @@ module FriendlyId
   module Version
     MAJOR = 3
     MINOR = 3
-    TINY  = 3
-    BUILD = 0
+    TINY  = 0
+    BUILD = 'rc2'
     STRING = [MAJOR, MINOR, TINY, BUILD].compact.join('.')
   end
 end

data/test/base_test.rb

@@ -0,0 +1,54 @@
+require File.expand_path("../helper.rb", __FILE__)
+
+class CoreTest < MiniTest::Unit::TestCase
+  include FriendlyId::Test
+
+  test "friendly_id should accept a base and a hash" do
+    klass = Class.new(ActiveRecord::Base) do
+      extend FriendlyId
+      friendly_id :foo, :use => :slugged, :slug_column => :bar
+    end
+    assert klass < FriendlyId::Slugged
+    assert_equal :foo, klass.friendly_id_config.base
+    assert_equal :bar, klass.friendly_id_config.slug_column
+  end
+
+
+  test "friendly_id should accept a block" do
+    klass = Class.new(ActiveRecord::Base) do
+      extend FriendlyId
+      friendly_id :foo do |config|
+        config.use :slugged
+        config.base = :foo
+        config.slug_column = :bar
+      end
+    end
+    assert klass < FriendlyId::Slugged
+    assert_equal :foo, klass.friendly_id_config.base
+    assert_equal :bar, klass.friendly_id_config.slug_column
+  end
+
+  test "the block passed to friendly_id should be evaluated before arguments" do
+    klass = Class.new(ActiveRecord::Base) do
+      extend FriendlyId
+      friendly_id :foo do |config|
+        config.base = :bar
+      end
+    end
+    assert_equal :foo, klass.friendly_id_config.base
+  end
+
+  test "should allow defaults to be set via a block" do
+    begin
+      FriendlyId.defaults do |config|
+        config.base = :foo
+      end
+      klass = Class.new(ActiveRecord::Base) do
+        extend FriendlyId
+      end
+      assert_equal :foo, klass.friendly_id_config.base
+    ensure
+      FriendlyId.instance_variable_set :@defaults, nil
+    end
+  end
+end

data/test/configuration_test.rb

@@ -0,0 +1,27 @@
+require File.expand_path("../helper", __FILE__)
+
+class ConfigurationTest < MiniTest::Unit::TestCase
+
+  include FriendlyId::Test
+
+  def setup
+    @model_class = Class.new(ActiveRecord::Base)
+  end
+
+  test "should set model class on initialization" do
+    config = FriendlyId::Configuration.new @model_class
+    assert_equal @model_class, config.model_class
+  end
+
+  test "should set options on initialization if present" do
+    config = FriendlyId::Configuration.new @model_class, :base => "hello"
+    assert_equal "hello", config.base
+  end
+
+  test "should raise error if passed unrecognized option" do
+    assert_raises NoMethodError do
+      FriendlyId::Configuration.new @model_class, :foo => "bar"
+    end
+  end
+
+end

data/test/core_test.rb

@@ -0,0 +1,30 @@
+require File.expand_path("../helper.rb", __FILE__)
+
+Author, Book = 2.times.map do
+  Class.new(ActiveRecord::Base) do
+    extend FriendlyId
+    friendly_id :name
+  end
+end
+
+class CoreTest < MiniTest::Unit::TestCase
+
+  include FriendlyId::Test
+  include FriendlyId::Test::Shared::Core
+
+  def model_class
+    Author
+  end
+
+  test "models don't use friendly_id by default" do
+    assert !Class.new(ActiveRecord::Base).respond_to?(:friendly_id)
+  end
+
+  test "model classes should have a friendly id config" do
+    assert model_class.friendly_id(:name).friendly_id_config
+  end
+
+  test "instances should have a friendly id" do
+    with_instance_of(model_class) {|record| assert record.friendly_id}
+  end
+end

data/test/databases.yml

@@ -0,0 +1,19 @@
+mysql:
+  adapter: mysql2
+  database: friendly_id_test
+  username: root
+  hostname: localhost
+  encoding: utf8
+
+postgres:
+  adapter: postgresql
+  host: localhost
+  port: 5432
+  username: postgres
+  database: friendly_id_test
+  encoding: utf8
+
+sqlite3:
+  adapter: sqlite3
+  database: ":memory:"
+  encoding: utf8

data/test/helper.rb

@@ -0,0 +1,88 @@
+$: << File.expand_path("../../lib", __FILE__)
+$: << File.expand_path("../", __FILE__)
+$:.uniq!
+
+require "rubygems"
+require "bundler/setup"
+require "mocha"
+require "minitest/unit"
+require "active_record"
+require 'active_support/core_ext/time/conversions'
+# require "active_support/core_ext/class"
+
+if ENV["COVERAGE"]
+  require 'simplecov'
+  SimpleCov.start do
+    add_filter "test/"
+    add_filter "friendly_id/migration"
+  end
+end
+
+require "friendly_id"
+
+# If you want to see the ActiveRecord log, invoke the tests using `rake test LOG=true`
+if ENV["LOG"]
+  require "logger"
+  ActiveRecord::Base.logger = Logger.new($stdout)
+end
+
+module FriendlyId
+  module Test
+
+    def self.included(base)
+      MiniTest::Unit.autorun
+    end
+
+    def transaction
+      ActiveRecord::Base.transaction { yield ; raise ActiveRecord::Rollback }
+    end
+
+    def with_instance_of(*args)
+      model_class = args.shift
+      args[0] ||= {:name => "a"}
+      transaction { yield model_class.create!(*args) }
+    end
+
+    module Database
+      extend self
+
+      def connect
+        ActiveRecord::Base.establish_connection config[driver]
+        version = ActiveRecord::VERSION::STRING
+        driver  = FriendlyId::Test::Database.driver
+        engine = RUBY_ENGINE rescue "ruby"
+        message = "Using #{engine} #{RUBY_VERSION} AR #{version} with #{driver}"
+        puts "-" * 72
+        if in_memory?
+          ActiveRecord::Migration.verbose = false
+          Schema.up
+          puts "#{message} (in-memory)"
+        else
+          puts message
+        end
+      end
+
+      def config
+        @config ||= YAML::load(File.open(File.expand_path("../databases.yml", __FILE__)))
+      end
+
+      def driver
+        (ENV["DB"] or "sqlite3").downcase
+      end
+
+      def in_memory?
+        config[driver]["database"] == ":memory:"
+      end
+    end
+  end
+end
+
+class Module
+  def test(name, &block)
+    define_method("test_#{name.gsub(/[^a-z0-9']/i, "_")}".to_sym, &block)
+  end
+end
+
+require "schema"
+require "shared"
+FriendlyId::Test::Database.connect