PermalinkFu

This is a fork of goncalossilva/permalink_fu, a simple plugin for creating URL-friendly permalinks (slugs) from attributes.

It supports globalize model translations in the following branches:

• globalize branch: globalize 7.x / Rails 7.0-8.x (contains up-to-date usage instructions)
• globalize6 branch: globalize 6.x / Rails 5.2-7.1 (old, contains usage instructions)
• globalize5 branch: globalize 5.x / Rails 4.2-5.x (old, contains usage instructions)
• globalize4 branch: globalize 4.x / Rails 4 (old, contains usage instructions)
• globalize3 branch: globalize3 0.3.x / Rails 3 (old, without usage instructions)
• globalize2 branch: globalize2 for Rails 2 (old, without usage instructions)

Usage

class Article < ActiveRecord::Base
  has_permalink :title
end

This will escape the title in a before_validation callback, turning e.g. "Föö!! Bàr" into "foo-bar".

The permalink is by default stored in the permalink attribute.

has_permalink :title, :as => :slug

will store it in slug instead.

has_permalink [:category, :title]

will store a permalink form of "#{category}-#{title}".

Permalinks are guaranteed unique: "foo-bar-2", "foo-bar-3" etc are used if there are conflicts. You can set the scope of the uniqueness like

has_permalink :title, :scope => :blog_id

This means that two articles with the same blog_id can not have the same permalink, but two articles with different blog_ids can.

Two finders are provided:

Article.find_by_permalink(params[:id])
Article.find_by_permalink!(params[:id])

These methods keep their name no matter what attribute is used to store the permalink.

The find_by_permalink method returns nil if there is no match; the find_by_permalink! method will raise ActiveRecord::RecordNotFound.

You can override the model's to_param method with

has_permalink :title, :param => true

This means that the permalink will be used instead of the primary key (id) in generated URLs. Remember to change your controller code from e.g. find to find_by_permalink!.

You can add conditions to has_permalink like so:

class Article < ActiveRecord::Base
  has_permalink :title, :if => Proc.new { |article| article.needs_permalink? }
end

Use the :if or :unless options to specify a Proc, method, or string to be called or evaluated. The permalink will only be generated if the option evaluates to true.

You can use PermalinkFu.escape to escape a string manually.

Use with Globalize gem

class Article < ActiveRecord::Base   
  translates :title, :permalink
  
  has_permalink :title, :globalize => true
end

Just add the :globalize => true option when the permalink is based on translated attributes. You will also need to translate the permalink field itself.

Note:

• mixing translated and untranslated attributes for has_permalink is currently not supported
• when using the globalize option, it automatically adds a :locale scope when determining the permalink uniqueness

Development and Testing

If you change any gem dependencies, you need to re-generate the gemfiles via bundle exec appraisal update.

Run tests via:

• rake test for the current rails version with the current ruby version
• rake all for all rails versions with the current ruby version

Credits

Originally extracted from Mephisto by technoweenie.

Conditions added by Pat Nakajima.

Henrik Nyh replaced iconv with ActiveSupport::Multibyte.