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

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

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

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 development branch of the SVN tree can be pulled anonymously from actsascatalog.rubyforge.org/svn/trunk/

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

Acts as catalog