| Path: | README |
| Last Update: | Fri Mar 10 16:08:00 EST 2006 |
This plugin provides an easy way to give your ActiveRecord models clean urlnames, for use anywhere you don’t want to use a plain old integer id.
To use it, first either copy over the migration in db/00x_add_urlnames_table.rb and migrate it to it, or import the SQL in db/urlnames_table.sql.
This plugin also requires at least Rails 1.1 (currently edge. See wiki.rubyonrails.com/rails/pages/EdgeRails) For updates see gabriel.gironda.org, and for licensing see LICENSE.
The usage that will work for 80% of cases is this:
class Article < ActiveRecord::Base
acts_as_urlnameable :title
end
This will format the value of the title attribute of the record to one suitable for use in a URL and save it. Further changes to title will not overwrite the url name. The value can then be accessed with +object.urlname+. If the url name already exists, an error will be added to the urlname attribute.
To allow overwrites of the url name, call acts_as_urlname with the following option:
class Article < ActiveRecord::Base
acts_as_urlnameable :title, :overwrite => true
end
The url name will now be overwritten if the value of title changes. To change the default validation message you can use the :message option:
class Article < ActiveRecord::Base
acts_as_urlnameable :title, :overwrite => true, :message => 'is unavailable.'
end
Records can be located via the find_by_urlname method, like so:
Article.find_by_urlname('some_urlname')
This section is for those of us who like to mess with ActiveRecord a little more than usual.
You can set objects to be known by any past url names they may have had, even if the current one is different. The usage in this case would be:
class Article < ActiveRecord::Base
acts_as_urlnameable :title, :mode => :multiple
end
The instance method past_urlnames will then return all url names other than the current one, while all_urlnames will return all url names the object has ever been known by, including the current url name. The :overwrite option has no effect on objects with multiple urlnames for obvious reasons.
You can also define your own urlnameify method if you would prefer not to use the default url name formatting.
class Article < ActiveRecord::Base
acts_as_urlnameable :title, :mode => :multiple
protected
def urlnameify(text)
text.to_s.downcase + '_permalink'
end
end
Acts as Urlnameable gives you five options for validation:
* Skip any kind of validation (usually undesirable)
* Validating against the base class (the default)
* Validating against the child class (for use with single table inheritance)
* Validating against the parent object (for associations)
* Define your own validate_urlname method
To skip validation, use the plugin like so:
class Article < ActiveRecord::Base
acts_as_urlnameable :title, :mode => :multiple, :validate => false
end
If you’re using single table inheritance in ActiveRecord, and your models look like this for example:
class Article < ActiveRecord::Base
acts_as_urlnameable :title
end
class SpecialArticle < Article
end
class Draft < Article
end
Then by default, a Draft can not have the same url name as a SpecialArticle. If you’d like to change this behaviour, then use the :sti_class option with :validate
class Article < ActiveRecord::Base
acts_as_urlnameable :title, :validate => :sti_class
end
Now Draft and SpecialArticle can have the same url name set. SpecialArticle.find_by_urlname will find only the SpecialArticle with the matching url name, and Draft.find_by_urlname will find only the Draft with the url name given.
Article.find_by_urlname will find the first Article with the given url name, whereas Article.find_all_by_urlname will find both the Draft and SpecialArticle objects.
Here’s an example model setup:
class Person < ActiveRecord::Base
has_many :articles
end
class Article < ActiveRecord::Base
acts_as_urlnameable :title
belongs_to :person
end
If you would like to validate the url name for an article against the parent object, pass the name of the belongs_to association as the option for :validate. Example:
class Article < ActiveRecord::Base
acts_as_urlnameable :title, :validate => :person
belongs_to :person
end
Now for the validation to work properly, you must instantiate the new article through the association. This is best explained like this:
# Find two different people
bob = Person.find_by_first_name('bob')
joe = Person.find_by_first_name('joe')
# Have Bob write a new article
bobs_article = bob.articles.build(:title => "My first article", :body => "This is my first article")
bobs_article.save # passes validation and saves ok
# Have Joe write a new article
joes_article = joe.articles.build(:title => "My first article", :body => "This is my first article")
joes_article.save # passes validation and saves ok
# Find Bob's first article
bob.articles.find_by_urlname('my_first_article')
# Find Joe's first article
joe.articles.find_by_urlname('my_first_article')
Both articles validate because the validation is scoped against the owner. Bob and Joe can both have articles known as ‘my_first_article’, and the finder method will find only their own articles. Article.find_all_by_urlname(‘my_first_article’) will find both articles.
You can also define your own validate_urlname method in the class for custom validation, like so:
class Person < ActiveRecord::Base
acts_as_urlnameable :first_name
protected
def validate_urlname
if Person.find_by_urlname(attr_to_urlname)
errors.add(:urlname, 'is not available.')
elsif attr_to_urlname == 'bob'
errors.add_to_base('You might be Bob, and I hate Bob.')
end
end
end