mil_friendly_id 4.0.9.8

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c6e5e405a8f499b763823ebfd2f64d3328b04770
+  data.tar.gz: f1af5d445ae42d992a9bb329d477affa920eaedb
+SHA512:
+  metadata.gz: bafb0972a9545b7d49dd3b20577ef0568b969cf1b3acb886f61bc66e934729bf1e6dcb61bf902fd39903e581f7014dea0696607c822dbb82d738e1d752d8695b
+  data.tar.gz: fcc3ed19d1a22963c4175b814fa91dad9f5ababe94c7c4c0ffe9f9dcf5f13a92f8bce6e91522f3bf74ec4a36c929c814c1b2c250162bcbf293b6ed9acbf4dbf0

data/.gitignore

@@ -0,0 +1,12 @@
+Gemfile.lock
+doc
+docs
+pkg
+.DS_Store
+coverage
+.yardoc
+*.gem
+*.sqlite3
+*.rbc
+*.lock
+.rbx

data/.travis.yml

@@ -0,0 +1,20 @@
+rvm:
+  - 1.9.3
+  - 1.8.7
+#  - jruby
+#  - rbx
+
+branches:
+  only:
+    - master
+env:
+  - DB=postgres
+  - DB=mysql
+  - DB=sqlite3
+
+gemfile:
+  - gemfiles/Gemfile.rails-3.0.rb
+  - gemfiles/Gemfile.rails-3.1.rb
+  - gemfiles/Gemfile.rails-3.2.rb
+before_script: 'bundle exec rake db:create db:up > /dev/null'
+script: 'bundle exec rake test'

data/.yardopts

@@ -0,0 +1,4 @@
+--files=WhatsNew.md,Changelog.md,Guide.rdoc
+--private
+--protected
+--exclude lib/friendly_id/migration

data/Changelog.md

@@ -0,0 +1,86 @@
+# FriendlyId Changelog
+
+We would like to think our many {file:Contributors contributors} for
+suggestions, ideas and improvements to FriendlyId.
+
+* Table of Contents
+{:toc}
+
+## 4.0.9 (2012-10-31)
+
+* Fixed support for Rails 3.2.9.rc1
+
+## 4.0.8 (2012-08-01)
+
+* Name internal anonymous class to fix marshall dump/load error (Jess Brown, Philip Arndt and Norman Clarke).
+
+* Avoid using deprecated `update_attribute` (Philip Arndt).
+
+* Added set_friendly_id method to Globalize module (Norman Clarke).
+
+* autoload FriendlyId::Slug; previously this class was not accessible from
+  migrations unless required explicitly, which could cause some queries to
+  unexpectedly fail (Norman Clarke).
+
+* Fix Mocha load order (Mark Turner).
+
+* Minor doc updates (Rob Yurkowski).
+
+* Other miscellaneous refactorings and doc updates.
+
+## 4.0.7 (2012-06-06)
+
+* to_param just calls super when no friendly_id is present, to keep the model's
+  default behavior. (Andrew White)
+
+* FriendlyId can now properly sequence slugs that end in numbers even when a
+  single dash is used as the separator (Tomás Arribas).
+
+## 4.0.6 (2012-05-21)
+
+* Fix nil return value from to_param when save fails because of validation errors (Tomás Arribas)
+* Fix incorrect usage of i18n API (Vinicius Ferriani)
+* Improve error handling in reserved module (Adrián Mugnolo and Github user "nolamesa")
+
+## 4.0.5 (2012-04-28)
+
+* Favor `includes` over `joins` in globalize to avoid read-only results (Jakub Wojtysiak)
+* Fix globalize compatibility with results from dynamic finders (Chris Salzberg)
+
+
+## 4.0.4 (2012-03-26)
+
+* Fix globalize plugin to avoid issues with asset precompilation (Philip Arndt)
+
+
+## 4.0.3 (2012-03-14)
+
+* Fix escape for '%' and '_' on SQLite (Norman Clarke and Sergey Petrunin)
+* Allow FriendlyId to be extended or included (Norman Clarke)
+* Allow Configuration#use to accept a Module (Norman Clarke)
+* Fix bugs with History module + STI (Norman Clarke and Sergey Petrunin)
+
+## 4.0.2 (2012-03-12)
+
+* Improved conflict handling and performance in History module (Erik Ogan and Thomas Shafer)
+* Fixed bug that impeded using underscores as a sequence separator (Erik Ogan and Thomas Shafer)
+* Minor documentation improvements (Norman Clarke)
+
+## 4.0.1 (2012-02-29)
+
+* Added support for Globalize 3 (Enrico Pilotto and Philip Arndt)
+* Allow the scoped module to use multiple scopes (Ben Caldwell)
+* Fixes for conflicting slugs in history module (Erik Ogan, Thomas Shafer, Evan Arnold)
+* Fix for conflicting slugs when using STI (Danny van der Heiden, Diederick Lawson)
+* Maintainence improvements (Norman Clarke, Philip Arndt, Thomas Darde, Lee Hambley)
+
+## 4.0.0 (2011-12-27)
+
+This is a complete rewrite of FriendlyId, and introduces a smaller, faster and
+less ambitious codebase. The primary change is the relegation of external slugs
+to an optional addon, and the adoption of what were formerly "cached slugs"
+as the primary way of handling slugging.
+
+## Older releases
+
+Please see the 3.x branch.

data/Gemfile

@@ -0,0 +1,15 @@
+source 'https://rubygems.org'
+
+gemspec
+
+# Database Configuration
+group :development, :test do
+  platforms :jruby do
+    gem 'activerecord-jdbcsqlite3-adapter'
+    gem 'jruby-openssl'
+  end
+
+  platforms :ruby do
+    gem 'sqlite3'
+  end
+end

data/Guide.rdoc

@@ -0,0 +1,553 @@
+#encoding: utf-8
+
+
+== About FriendlyId
+
+FriendlyId is an add-on to Ruby's Active Record that allows you to replace ids
+in your URLs with strings:
+
+    # without FriendlyId
+    http://example.com/states/4323454
+
+    # with FriendlyId
+    http://example.com/states/washington
+
+It requires few changes to your application code and offers flexibility,
+performance and a well-documented codebase.
+
+=== Core Concepts
+
+==== Slugs
+
+The concept of "slugs[http://en.wikipedia.org/wiki/Slug_(web_publishing)]" is at
+the heart of FriendlyId.
+
+A slug is the part of a URL which identifies a page using human-readable
+keywords, rather than an opaque identifier such as a numeric id. This can make
+your application more friendly both for users and search engine.
+
+==== Finders: Slugs Act Like Numeric IDs
+
+To the extent possible, FriendlyId lets you treat text-based identifiers like
+normal IDs. This means that you can perform finds with slugs just like you do
+with numeric ids:
+
+    Person.find(82542335)
+    Person.find("joe")
+
+
+== 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}.
+
+
+== 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. Do not make the column unique in case you wish to scope the slug
+(more on this later). 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.
+
+
+== 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
+
+
+== 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.
+
+Please do note that you must drop the uniqueness constraint on the slug's
+column in the database when you're scoping the slug.
+
+=== 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
+
+
+== 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
+
+
+== 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")
+
+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) do
+    Post.find("guerre-stellari")
+  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, simply change the locale and
+assign a value to the +slug+ field:
+
+  I18n.with_locale(:it) do
+    post.slug = "guerre-stellari"
+  end
+
+
+== Reserved Words
+
+The {FriendlyId::Reserved Reserved} 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
+
+Note that the error message will appear on the field +:friendly_id+. If you are
+using Rails's scaffolded form errors display, then it will have no field to
+highlight. If you'd like to change this so that scaffolding works as expected,
+one way to accomplish this is to move the error message to a different field.
+For example:
+
+  class Person < ActiveRecord::Base
+    extend FriendlyId
+    friendly_id :name, use: :slugged
+
+    after_validation :move_friendly_id_error_to_name
+
+    def move_friendly_id_error_to_name
+      errors.messages[:name] = errors.messages.delete(:friendly_id)
+    end
+  end