ruby script/plugin install http://svn.randomba.org/friendly_id/trunk

== The Problem

Numeric id's for your database records are perfect most of the time, but present some problems when used in URL's:

- They're ugly and impersonal.
- They make URL's harder to remember.
- They can give a window into your database - people can fiddle with your urls by incrementing id's.
- They can give a hint about the number of records in your database.
- They are bad for search engine optimization.

However, text-based ids in URL's present some problems too:

- They can change, breaking your URL's.
- They can have invalid URL characters, breaking your links in some browsers.
- It can be tricky to ensure they're always unique.


FriendlyId lets you use textual id's for your active records while mostly avoiding these problems so that you can go from:

OLD AND BUSTED: http://www.example.com/members/12

to

NEW AND HOT: http://www.example.com/members/joe

== How it works

=== Scenario 1: You already have a unique string column in your model.

This is the usual case if you have a member/user model with a unique login/nickname/username column. In this case, all you need to do is add this to your model:

has_friendly_id :login

and you can then write code like this:

	@member = Member.find("joe")   # the old Member.find(1) still works, too.
	@member.to_param               # returns "joe"
	redirect_to @member            # The URL would be /members/joe

=== Scenario 2: You want id's based on a not-necessarily unique string column in your model.

This would be the typical case if you have a Posts/Articles model with titles, and you want the titles turned into slugs so you can have URL's like

http://www.example.com/posts/new-version-released

Here you would include this in your model:

has_friendly_id :posts, :use_slug => true

and you can then write code like this:

	@post = Post.find("new-version-released")  # Post.find(1) still works, too
	@post.to_param                             # returns "new-version-released"
	redirect_to @post                          # The URL would be /posts/new-version-released

==== What if I change the title?

One of the problems with using text-based id's in URL's is that if you change the id, your URL's using the old id all break. This could break people's bookmarks, and your search engine listings. Sometimes this doesn't matter, but often it does.

Friendly_id will record changes to slugs so that you can do a 301 redirect to the new URL:

	def find_record_using_friendly_id
	  @post = Post.find(params[:id])
	  redirect_to @post, :status => :moved_permanently if @post.has_better_id?
	end

==== What if the title isn't unique?

Friendly_id will append a number to the end of the id to keep it unique if necessary:

- /posts/new-version-released
- /posts/new-version-released-2
- /posts/new-version-released-3
- etc.

==== Why not just override to_param with the id followed by a dasherized string?

That works fine sometimes, but makes ugly urls:

- OLD AND BUSTED: http://www.example.org/profiles/12-joe
- NEW AND HOT: http://www.example.org/profiles/joe

Also, these URL's will all point to the same content:

- http://www.example.org/posts/12-i-love-joe
- http://www.example.org/posts/12-i-hate-joe
- http://www.example.org/posts/12-this-is-getting-kinda-ridiculous

Search engines, especially Google, will penalize you for having duplicate content if you have more than one URL pointing to the same content.

Also, any person can still simply increment the id part of the url, and gain a level of access to your data that you may not wish them to have.

== Setup:

script/generate friendly_id_migration
rake db:migrate

- now add some code to your models: e.g., has_friendly_id :title, :use_slug => true
- if you are using slugs, then do rake friendly_id:make_slugs MODEL=MyModelName

Then every so often, or perhaps every day via cron, you can do:

rake:friendly_id:remove_old_slugs

This will remove any old slugs for friendly ids that have changed. The default is to remove dead slugs older than 45 days, but you can change that by doing:

rake:friendly_id:remove_old_slugs DAYS=60

There is currently no advanced documentation for this plugin.