= acts_as_catalog

This plugin facilitates the handling of catalogs, probably the most
often used kind of table in Rails. It extends ActiveRecord::Base,
ActiveRecord::Migration and provides a base unit test.

= Installing the plugin

The easiest way is through Rails' own +scripts/plugins+ utility. The
first thing you should do is to tell Rails where the plugin's tree is
located. 

If you want to follow the latest changes, you will probably prefer
following the project's trunk, however, for production, I strongly
suggest you to stick to a stable release. Depending on what you
prefer, from your project's base directory, type:

  $ ./script/plugin source http://actsascatalog.rubyforge.org/svn/trunk/

Or, to follow a given release (say, 0.1 - Of course, check on the
latest stable release before doing this):

  $ ./script/plugin source http://actsascatalog.rubyforge.org/svn/tags/0.1/

Then, ask Rails to install the plugin:

  $ ./script/plugin install acts_as_catalog

If you use Subversion for tracking your project's development, you
will probably want to mark the plugin as an <i>external</i>
repository. To do so, add the -x switch:

  $ ./script/plugin install -x acts_as_catalog

= Using the plugin

== Models

A catalog is defined as a table with only a +name+ column of
+string+ type, and with a unique index on it (this means, does not
allow for duplicate values). This plugin allows you to specify your
model definition as:

  def Mytable < ActiveRecord::Base
    acts_as_catalog
    belongs_to :some_other_table
  end

Catalog entries often need to be translated. Translation frameworks,
such as GetText, advise you to qualify several strings to avoid name
clashes. So, if you want to include your catalogs' entries in a
translation, instead of using their plane +name,+ use its
+qualified_name+ attribute. This will give you a string in the
following fashion:

  entry = Mytable.new(:name => 'Table entry #1')
  entry.save
  puts entry.qualified_name    #  'Mytable|Table entry #1'

That is, +ClassName|item's name+.

A catalog is often accessed to populate i.e. drop-down selection or
radio boxes, passing what is called +collections+ in Rails-speak. You
will often want collections to be sorted by ID or by name, thus:

  collection = Mytable.collection_by_id

  another_col = Mytable.collection_by_name

If you want to get the items collection with their qualified names,
just prepend +qualified_+ to the method name:

  qualified_collection_1 = Mytable.qualified_collection_by_id
  qualified_collection_2 = Mytable.qualified_collection_by_name

== Migrations

You can specify all the catalogs you need to create for a specific
migration with a single instruction from inside your self.up method,
by giving a list of catalog table names to create_catalogs:

  def self.up
    create_catalogs :countries, :states
    ...
  end

Likewise, you can destroy the created catalogs in a single
command. The drop_catalogs method will usually be the last thing you
call in self.down:

  def self.up
    ...
    drop_catalogs :states, :countries
  end

== Tests

This plugin provides the base functionality to include in your unit
tests ensuring the catalog is properly declared. Just include
'catalog_test_helper' and include the CatalogTest mixin in your test
classes, declare the model name, and off you go. This is, a complete
unit test for you +Mytable+ catalog model could be:

  require File.dirname(__FILE__) + '../test_helper'
  require 'catalog_test_helper'

  class MytableTest < Test::Unit::TestCase
    include CatalogTestHelper
    def setup
      @model = Mytable
    end
  end

= Author, copyright and licensing.

This plugin was written by Gunnar Wolf <gwolf@gwolf.org>, Instituto de
Investigaciones Económicas, UNAM.

It is licensed under a MIT license. See the LICENSE file for further
information. 
= Author

This plugin is Copyright (c) 2008 Gunnar Wolf <gwolf@gwolf.org>

== Licensing information

This plugin is under a MIT license. For further information, please
check the LICENSE file.

= Getting the code

The plugin project's home page can be found at
http://rubyforge.org/projects/actsascatalog/ 

The development branch of the SVN tree can be pulled anonymously from
http://actsascatalog.rubyforge.org/svn/trunk/

Released versions can be found along the 'tags' directory of the SVN
tree, at http://actsascatalog.rubyforge.org/svn/tags/