Annotations Plugin (for Ruby on Rails applications)

Original Author:Jiten Bhagat (mail@jits.co.uk)
Copyright:© 2008-2009, the University of Manchester and the European Bioinformatics Institute (EMBL-EBI)
License:BSD
Version:0.1.0

Overview

This plugin allows arbitrary metadata to be stored and retrieved for any model object in your Ruby on Rails (v2.2+) application. This metadata is in the form of attribute/value data pairs that, together with provenance information, make up ‘annotations’. These annotations are “attached” to a model object in your application.

The idea is to abstract out and decouple annotations from your application’s core data model and allow layering in of metadata easily.

Examples of things you can use the annotations plugin for:

The main benefit is that annotations are stored and retrieved in a uniform manner with a common API. Parts of the plugin can also be extended and overridden in your application (see the Usage section for more info).

The annotations plugin is currently being used successfully in the BioCatalogue codebase to allow easy annotation of web services and their deployments/versions/operations/inputs/outputs/etc. Check out www.biocatalogue.org.

Features:

Full Documentation

To generate full documentation (including this readme and full API docs) do the following:

Install RDoc (v2.3.0 or above):

  % [sudo] gem install rdoc

Install the darkfish-rdoc gem:

  % [sudo] gem install darkfish-rdoc

Run the following command in the plugin’s root directory (vendor/plugins/annotations):

  % rdoc -SHNU -w 2 --title='Annotations Plugin' -m 'INDEX.rdoc' -x '(/doc|/tasks|/script|/test)'

The generated documentation will be in the doc folder of the annotations plugin.

Conceptual Data Model

At a conceptual level, an Annotation consists of:

This can be represented as:

  Annotation = Annotatable + Source + Attribute + Value + Value Type + Version Info + Timestamps

The database model for an Annotation is made up of the following fields:

  | id | annotatable_type | annotatable_id | source_type | source_id | attribute_id | value | value_type | version | version_creator_id | created_at | updated_at |

This makes use of ActiveRecord polymorphic relationships to allow any ActiveRecord model to be an Annotatable or Source.

Note: The version_creator_id field is only relevant when there are more than one version of an Annotation. I.e.: for the first version of the annotation the version_creator_id will be nil.

Annotation Attributes currently only consist of a name. This is the attribute or property you are describing for an Annotatable. Examples: ‘tag’, ‘description’, etc.

Versioning of Annotations

Whenever an Annotation is updated, a new AnnotationVersion entry is created in the db (corresponding model name = Annotation::Version).

This uses a library from the version_fu plugin. A customised version of this is embedded within the Annotations plugin (which won’t conflict if version_fu is installed in the main codebase).

Installation and Setup

Important Requirements

Installation

To install the plugin as a git cloned repo (this allows you to easily update the plugin in the future):

  ruby script/plugin install git://github.com/jits/annotations.git

Note: this requires git to be installed.

To install the plugin the regular way:

  ruby script/plugin install http://github.com/jits/annotations.git/

Setup

The Annotations plugin has now been installed and is ready for use. See the Usage section for further details.

Usage

Quick Use

See _More Examples_ below.

Important Usage Notes

Config Options

All the config options can be found in lib/annotations/config.rb, listed below:

TODO: explain and document these.

More Examples

TODO: add more advanced examples!

Extending the Plugin

Most of the aspects of this plugin can be extended/overridden in your codebase.

Examples:

TODO: add more!

See Also

The BioCatalogue codebase contains many examples of using the Annotations plugin successfully. Some pointers:

The prototype Shims Library also makes use of the Annotations plugin successfully and may provide some useful examples.

Updating the Plugin

Update the plugin code using the appropriate mechanism. Then:

  ruby script/generate annotations_migration vX

… where X is the version of the migration you want to generate

Main Plugin Contents

TODO: list files and what the purpose of each is.

Known Issues

Troubleshooting

Future Plans

In no particular order:

Appendix A: Data Model

Annotations

Table name: annotations

Fields:

Annotation Versions

Table name: annotation_versions

Fields:

Annotation Attributes

Table name: annotation_attributes

Fields:

Annotation Value Seeds

Table name: annotation_value_seeds

Fields:

[Validate]

Generated with the Darkfish Rdoc Generator 1.1.6.