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 external 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

Catalogs listing

We extend ActiveRecord::ConnectionAdapters::AbstractAdapter (and thus all of the derived adapters) by adding the methods method - You can query your connection as to which catalogs are defined, and it will give you back everything that looks like a canonical catalog (that is, every table that has two columns, called ‘id’ and ‘name’).

  catalog_list = MyTable.connection.catalogs

This function is analog to the tables function, provided by Rails.

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.

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 rubyforge.org/projects/actsascatalog/

The Git tree can be cloned anonymously:

    git clone git://rubyforge.org/actsascatalog.git

You can also browse the Git repository via the web interface, and even generate tarballs for specific points in time at:

    http://actsascatalog.rubyforge.org/git?p=actsascatalog.git;a=tree

README