# Slugged #

## About ###

Slugged is a simple slug library for ActiveRecord 3.0+.

It's main features are:

1. A very simple and tested codebase
2. Support for slug history (e.g. if a users slug changes, it will record the old slug)
3. Simple defaulting for slugs to UUID's (to avoid showing ID's.)
4. Built on ActiveRecord 3.0
5. 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.

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](http://github.com/guitsaru)

## 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.

## Copyright ##

Copyright (c) 2010 Darcy Laycock. See LICENSE for details.