Contributing to the Development of the Library
===============================================

This library is a set of tools which construct user interface
elements in an HTML 5 capable web browser for interaction with
InterMine data-warehouse systems. It is built on the following
technologies:

 * **CoffeeScript** - The language of the library.
 * **Backbone** - An MVC and eventing abstraction layer
 * **Bootstrap** - User interface patterns (in css and javascript)
 * **d3** - Data visualisation
 * **FontAwesome** - Scalable icon font.
 * **Google-Prettify** - Syntax highlighting.

Utility functions are supplied by **underscore.js**, and most DOM
manipulation is performed with **jQuery**. HTTP communication and API
calls are abstracted through **imjs**, the API transport library for
the InterMine project.

Some of these resources can be bundled into the built version of the
library itself, so that it can be served as a single file. Other parts,
such as the d3 SVG manipulation library, are fetched on demand, with
acceptable fallbacks available for their absence. 

Getting Started
------------------

Before you start, you will need node.js installed. Git is highly
recommended.

A fresh clone of the repository needs a few commands run before you can
get started with development:

  # Fetch the dependencies required for building the library.
  npm install

  # Fetch the dependencies required for serving the demo. These files are
  # also used when bundling dependencies.
  bower install

Once all dependencies are supplied, you can build the library itself with the
following command:

  make js

Coding Style
--------------

Code contributed to this library is expected to be coffee-script files, following
the standard style conventions of the coffee-script community (two-space indentation,
one-line functions where possible, minimisation of brackets and line noise). See
the coffeelint file for a specification of the style conventions that are 
enforced.

All new classes are expected to use the `define/using` dependency management
framework (see below), and keep to the following guidelines:

 * No more than one exported object per file. This should usually be a class.
 * File sizes should not exceed 500 lines. File sizes of less than 200 lines should
   be aimed for.
 * Objects should be exported for external access only very rarely.
 * No raw strings should be present in presentational code. All labels, icons
   and text should live in the `intermine.messages` or `intermine.icons`
   namespaces.

Code Framework
----------------

An important requirement of this library is to be embeddable in as many different
contexts as possible, which means working in circumstances where we do not
have full control over the environment in terms of dependencies, available 
libraries, or even versions of the libraries we do have. This means that 
where dependencies are used, they are bundled where applicable, and in
general, dependencies are minimised where practical. The project is still 
reasonably complex, and tools such as Backbone, Bootstrap and jQuery are employed 
to deal with this complexity; but inclusion of other dependencies is strongly
discouraged.

One dependency that would be welcome but which is off the table is require.js.
Nonetheless a code dependency management system is employed within the library
with enables writing modular code. This makes use of two functions defined within
this library itself: `define` and `using`. Please see `DEPENDENCY_MANAGEMENT` for
an introduction to this system and how it should be used.

Backbone is used for managing the complexities of state and presentation. New code is
expected to follow standard MVC design principles where an object models the 
domain state, and the presentation layer reflects that state in the DOM. 

Best Practices
-----------------

This library tries to adhere to the following principles:

 * Being aware that it may be a guest on the page, it should respect its host's
   boundaries. This means all efforts should be made to *avoid global references*.
   This means *no global variables*, no attaching things to the `body`, or
   listening to the `document`, and equally it means prefixing *all* css
   classes with `im-`, to avoid clashing with common css class names. It also means
   all css references but be in the form of DOM structure (element names) or
   css classes. No id attributes are allowed.
 * Being aware that multiple instances of this library may be instantiated, all
   efforts should be made to be as *frugal with resources* as possible. This means
   not making pointless requests before they are actually needed, especially
   if there is any chance they will never be needed. This means *caching* results
   of requests that have been made when we can be confident that we can do so.
   This means cleaning up after yourself, in terms of *deallocating resources*, and
   *unbinding event handlers*.
   This also means *releasing access to potentially shared resources* such as queries,
   for example by cloning them so that each widget has its own independent copies.
 * Being aware that this is an open-source library for use by the scientific
   research community, this library should make no efforts to hide information,
   complexity or choice from its users. *If an action is possible, this library
   should expose it to the end user*. It is the responsibility of the library
   designer to manage the complexity to avoid overwhelming users, and judge the
   right amount of information to present at any one time. There are many tools that
   can be used to help with this, and they should be used when they make things
   simpler, never for their own sake.
 * Aware that repetition is a breeding ground for bugs, the library designer
   should strive, all things being equal, to get by with *as little code as possible*.
   No functions should be duplicated, strings should be references from the
   `intermine.messages` object, available tools should be understood and used
   (make sure you are familiar with all of the Backbone API, especially
   events and the Collection methods). Underscore is available as it is a dependency
   for Backbone, so feel free to utilise it to make your code more concise. Any
   duplication should be seen as an opportunity for refactoring. This also means
   getting by with *as few external dependencies as possible*. New dependencies
   should only be considered if they provide features that are compelling, they
   cannot be made optional and lazily loaded, and they deal with a problem
   domain of sufficient complexity that attempting to tackle it would be more
   likely to produce inefficient, bug filled code than a concise elegant solution.

The present author is well aware that he is guilty of gross infractions of all
of these above principles.



