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.
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.
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:
Finds a user from a slug (which can be the record's id, it's cached slug or, if enabled, slug history)
Returns a relationship which returns records other than the given.
Returns a relationship which returns records with the given cached slug.
Forces the generation of a current slug
Forces the generation of a current slug and saves it
Generates a slug if not already present.
When found via Model.find_using_slug, it will return try if there is a better slug available. Intended for use in redirects etc.
To run tests, simply do the following:
bundle install
rake
And it's ready!
Thanks to the following who contributed functionality / bug fixes:
- 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.
Copyright (c) 2010 Darcy Laycock. See LICENSE for details.