Plugin to facilitate rails apps connecting to topical_map application.
Ruby HTML JavaScript CSS
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



The Topical Map Builder was designed to centralize categories common to all THDL applications. Through the Topical Map Builder one integrates such categories into any rails app.


app> script/plugin install -x

This plugin relies on . Make sure you add it to your project too!

Integrate JavaScript, stylesheet, views and controller:

app> script/generate topical_map_categories

The active resource model will be called Category. The fields it includes are id, title, descriptions and parent_id, but the only one I used here is 'title'.

I patched the active resource classes for it to act more like a active records, so you can do belongs_to:

class FeatureObjectType < ActiveRecord::Base

belongs_to :object_type, :class_name => 'Category'

To integrate it into an edit action the ability to select a category from the tree, you get the parent category from the controller. In a “typical” rails app it would just look like this:

def new

  @parent_object_type = Category.find(20) # feature thesaurus id in topical map builder


Finally, in the new/edit view, you do this:

<%= f.label :object_type %> <%= category_selector(@parent_object_type, :feature_object_type, :object_type) %>

@parent_object_type is the main category, in this case feature type and the next two arguments are new name of the form variable and the name of the attribute.

By default the category selector inserts the required stylesheet and JavaScript file (where the call is made in the template). You can override this behavior and explicitly tell it not to include such tags by sending false to the fourth argument in case you are using multiple selectors (to avoid inserting several times the same stylesheet and JavaScript code) or if you want the include tags for the stylesheets and JavaScript in the header and not the body. You can use the tag helper category_selector_includes to generate the necessary JavaScript and stylesheet html tags. The code would look like this:

<%= category_selector_includes %> <p> <%= f.label :object_type %> <%= category_selector(@parent_object_type, :feature_object_type, :object_type, false) %> </p> <p> <%= f.label :subject %> <%= category_selector(@parent_subject, :feature_object_type, :subject, false) %> </p>

For the display, you treat it as a normal active record. For instance:

<%= @feature_object_type.object_type.title %>

The final argument of category_selector is a hash of options that will be sent directly into ModelSearcher. See the description of :options for category_searcher (below). category_selector and category_searcher use this argument in the same way.

If, instead of integrating a category with an edit action of a model with category_selector, you'd like to integrate category selection into a search interface, you'll want to use category_searcher:

<%= category_searcher(true, :category_id => 20, :field_name => 'object_type', :field_label => 'Feature type: ', :exclude_span => true, :options => {:hasTree => 'true'}) %>

The first argument determines whether the required JavaScript and stylesheet html tags are included. Multiple options are available in the subsequent arguments; these include:

:category_id The ID of the category that will be at the top of the hierarchical tree of categories (this will not be included in the tree).

:field_name The name of the field in which the selected category ID(s) will be placed.

:field_label The label of the above field

:exclude_span By default category_searcher will write JavaScript initializing ModelSearcher, as well as “<span id=”tmb_category_selector“></span>”, in which the JavaScript in ModelSearcher will put all of its HTML. If you'd like to manually write the span elsewhere, and have category_searcher only write the JavaScript, set :exclude_span => true.

:options A hash of options that will be passed directly to the ModelSearcher options. These are lowerCamelCased, in keeping with JavaScript convention. Important options include: :hasTree Determines whether a tree popup will be available for the user to use. (Default: false) :singleSelectionTree If :hasTree is true, this determines whether the user will be able to select only one category, as opposed to being able to select multiple categories. (Default: false) Other options are available for ModelSearcher. See the in-code documentation for more information.


Example goes here.


ModelSearcher, which is used by both category_selector and category_search, requires jQuery. It has been tested on jQuery 1.3.2 and jQuery 1.4, but is likely to work on other versions. If :hasTree is set to true in :options of either category_selector or category_searcher, the tree will be shown in a popup made by jQuery.fn.draggablePopup, which requires the jQuery UI Draggable plugin and all of its dependencies.

Copyright © 2008 Andres Montano (on behalf of THDL), released under the MIT license