Slugged

About

Slugged is a simple slug library for ActiveRecord 3.0+.

It's main features are:

A very simple and tested codebase
Support for slug history (e.g. if a users slug changes, it will record the old slug)
Simple defaulting for slugs to UUID's (to avoid showing ID's.)
Built on ActiveRecord 3.0
If stringex is installed, uses stringex's transliteration stuff

Slugged used to be called Pseudocephalopod - a name inspired by the Jason Wander series of books which I just happened to be reading when I had the need for this that focuses on a war with slug-like creatures.

Why?

I love the idea of friendly_id, and most of the implementation but it felt bloated to me and my experiences on getting it to work correctly with Rails 3 left a base taste in my mouth / was altogether hacky.

Slugged is very much inspired by friendly id but with a much simpler codebase and built to work on Rails 3 from the start.

Usage

Using Slugged is simple. In Rails, simply drop this in your Gemfile:

gem 'slugged'

Optionally restricting the version.

Next, if you wish to use slug history run:

$ rails generate slugged:slugs

Otherwise, when calling is_sluggable make sure to include :history => false

Next, you need to add a cached slug column to your model and add an index. In your migration, you'd usually want something like:

add_column :users, :cached_slug, :string
add_index :users,  :cached_slug

Or, using our build in generator:

$ rails generate slugged:slug_migration Model

Lastly, in your model, call is_sluggable:

class User
  is_sluggable :name
end

is_sluggable accepts the source method name as a symbol, and an optional has of options including:

:sync - when source column changes, save the result. Defaults to true.
:convertor - a symbol (for a method) or block for how to generate the base slug. Defaults to :to_url if available, parameterize otherwise.
:history - use slug history (e.g. if the name changes, it records the previous version in a slugs table). Defaults to true
:uuid - If the slug is blank, uses a generated uuid instead. Defaults to true
:slug_column - the column in which to store the slug. Defaults to :cached_slug
:to_param - if true (by default), overrides to_param to use the slug
:use_cache - uses Slugged.cache if available to cache any lookups e.g. in memcache.
:editable - if true (false is the default), allow the users to edit cached_slug column.

Once installed, it provides the following methods:

User.find_using_slug "some-slug"

Finds a user from a slug (which can be the record's id, it's cached slug or, if enabled, slug history)

User.other_than(record)

Returns a relationship which returns records other than the given.

User.with_cached_slug(record)

Returns a relationship which returns records with the given cached slug.

User#generate_slug

Forces the generation of a current slug

User#generate_slug!

Forces the generation of a current slug and saves it

User#autogenerate_slug

Generates a slug if not already present.

User#has_better_slug?

When found via Model.find_using_slug, it will return try if there is a better slug available. Intended for use in redirects etc.

Working on Slugged

To run tests, simply do the following:

bundle install
rake

And it's ready!

Contributors

Thanks to the following who contributed functionality / bug fixes:

Matt Pruitt

Note on Patches/Pull Requests

Fork the project.
Make your feature addition or bug fix.
Add tests for it. This is important so I don't break it in a future version unintentionally.
Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
Send me a pull request. Bonus points for topic branches.

silab/slugged