ActsAsSlug
==========

Simple plugin to manage slugs in models.

You must install Novelys_Hack plugin in order for this plugin to work : https://github.com/yannski/novelys_hacks/tree

Usage
=====

You can use acts_as_slug in two different ways. The first one is if you want to name your models instances like "xxxxxx-id" (with the id at the end).
The second way is if you don't want an id. If you don't want a the object id to be part of the slug, you have to add a varchar/string slug column in your model
table. 

acts_as_slug(slug_array, slug_options)

options is a hash that may contains optional :separator and :append_id keys. 

Add :
acts_as_slug [:title]

To handle a slug using the title column.

slug_array parameter is an Array.

options can be :

:separator is a String that will be used to join the elements in order to create the slug.

:append_id : if set, acts_as_slug will not use a slug column to save the slug, but will generate dynamicaly a slug based on the slug_array and append the object id.

If you want to use different separators like '-by-', you should deactivate separator by specifying :separator => false.

Use a symbol to reference a column of the model, use a string to reference an association (ie.: "address.locality.name"), use a string beginning and ending by "/" for a static string (ie.: "/-by-/").

Note : when using find_with_slug!, if append_id option is set it uses the final id to find the object, otherwise it uses the slug column to find the object.

if the object cannot be retrieved :
- if append_id is set, it raise AR::RecordNotFound if the given id is not found. If the id is good but the slug is bad, it raises a SlugError exception. The good thing is that you
can catch the exception in ApplicationController and redirect to the good URL thanks to the retrieved_element attribute of the exception that contains the current element.
- if append_id is not set, it uses the slug column to find the element. If the element is not found, it raises AR::RecordNotFound.

Using SlugError
===============

The great thing about this plugin is that if you use append_id, you can easily catch modification in the slug and redirect your users to the new model URL.
This is great for Search Engines Optimization (SEO) !
For example, a model Recipe has :

acts_as_slug [:title], :append_id => true

A model instance has a title "My good cake", and its slug is : "my-good-cake-8". If the title changes, the slug changes as well. For example, the new slug is now : "my-great-cake-8".
You want your users to be redirected from /recipes/my-good-cake-8 to /recipes/my-great-cake-8, it is easy, just add this in your ApplicationController :

def rescue_action(e)
  case e
  when SlugError
    redirect_to polymorphic_url(e.retrieved_element), :status => :moved_permanently
  else
    super
  end
end

Features
========

* Auto-sanitization of parameters for clean URLs (you must have unicode gem installed UNLESS you use Rails >= 2.2).
* Auto-incrementation of the slug if you use a slug column. ActsAsSlug will add '-2' and so on if a record with the same slug exists.
* Will not fail or raise exception if a given parameter is nil or invalid when generating the slug, it will simply ignore the paramater.

Examples
========

acts_as_slug [:title, '/-by-/', "author.login"], :separator => false

will create a slug like "loki-by-alexandre"

acts_as_slug [:title, "author.login"], :separator => '_'

will create a slug like "loki_alexandre"

acts_as_slug [:title], :append_id => true

will create a slug like "loki-9"


Copyright (c) 2008-2009 Novelys Team, released under the MIT license