IMBedding.js - the InterMine JavaScript table embedding library

Purpose

To help those who would like to embed the results of queries against an InterMine data warehouse in their own pages, InterMine provides a javascript client library to simplify access to our REST webservice API.

This library is designed to facilitate access to information when you already know what you are looking for, and present the results neatly in an easily customisable table, such as:

Installation

The JavaScript library does not need to be installed. You are very welcome to download it and host it for your pages yourself, but InterMine does also host it for you.

To download the library:

wget http://www.intermine.org/lib/imbedding/imbedding-0.1.tar.gz

to use the hosted version, include the following lines in the head of your page:

<!-- jQuery (hosted by Google) -->
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.4.4/jquery.min.js" type="text/javascript"></script>

<!-- jquery-jsonp (from another online repository) -->
<script src="http://jquery-jsonp.googlecode.com/files/jquery.jsonp-2.1.4.min.js" type="text/javascript"></script>

<!-- Similarly imbedding.js is hosted on intermine.org -->
<script src="http://www.intermine.org/lib/imbedding/0.1/imbedding.min.js" type="text/javascript"></script>

How to Use IMBedding

To load a table of data into your page you need:

• A place to load it into, marked out by a place-holder element
• A call to the IMBedding library, made in a script

eg:

<div id="some-placeholder"></div>
<script type="text/javascript">
    IMBedding.setBaseUrl("http://preview.flymine.org/preview");
    IMBedding.loadTemplate(
        {
            name:           "Gene_RegionOverlappingTFbindingsite",

            constraint1:    "Gene",
            op1:            "LOOKUP",
            value1:         "CG2328",
            code1:          "A",
        },            
        '#some-placeholder',
    );
</script>

The two functions on the IMBedding object that are most useful are:

• loadTemplate(templateValues, placeholderSelector, options)
• loadTable(query, requestData, placeholderSelector, options)

IMBedding.loadTemplate

Loads the results of a template query as a table

This function expects at least two arguments, and an optional options object.

Parameters:

templateValues

The template values as an object mapping names to values (see below)

placeholderSelector

a jQuery selector as a string, or a callback function to process data. See USER DEFINED CALLBACKS

options

an object with a map of optional values (see CUSTOMISATION below)

Template Values Object

The template values object requires the following keys:

• name: The name of the template to query
• For each editable constraint: (where [i] represents an incrementing integer)
  • constraint[i]: The path of the constraint (eg: "Gene.symbol")
  • op[i]: The operator of the constraint (eg: "=", "IN", "LOOKUP")
  • value[i]: The value of the constraint. Multi-value constraints should have their values joined with commas.
  • [in the case of LOOKUP constraints] extra[i]: The search area (usually organism)

You may optionally include the following values:

• start: the index of the first result to include (default: 0)
• size: the page size (how many result rows to return at once) - default: 10
• format: You can access data in different formats - see OTHER DATA FORMATS below

IMBedding.loadQuery

Loads the results of an arbitrary query as a table

This function expects at least three parameters, with an optional map of optional values.

Parameters:

query

the query, represented as an XML string, or a javascript object

requestData

an object holding parameters valid just for this request

placeholderSelector

a jQuery selector as a string, or a callback function to process data. See USER DEFINED CALLBACKS

options

an object with a map of optional values (see CUSTOMISATION below)

query

You can provide information about the query as either an XML string, or as a JavaScript object.

Here is an example of the XML format for our path query API:

<query name="queryName" model="modelName" view="Gene.name Gene.proteins.name" sortOrder="Gene.name">
    <constraint path="Gene.length" op="&gt;" value="500"/>
    <pathDescription path="Gene.name" description="The gene name"/>
    <join path="Gene.proteins" status="OUTER"/>
</query>

The json object format is basically the same as the XML, except that its view is expected to be an array and it has arrays of joins and constraints in the place of the repeated join and constraint xml tags. Also: it accepts from as a synonym for model, where as a synonym for constraints, and select as a synonym for view (as in the example below). The json object format will also correctly interpret < and > when used as operators, whereas the xml will have to be correctly formatted by hand to escape these operators.

var query = {
    view: ["Gene.name", "Gene.proteins.name"],
    constraints: [{code: "A", path: "Gene.length", op: ">", value: "500"}],
    joins: [{path: "Gene.proteins", style: "OUTER"}],
    sortOrder: "Gene.name ASC", model: "genomic"
};

// is equivalent to:
var query = {
    select: ["Gene.name", "Gene.proteins.name"],
    where: [{code: "A", path: "Gene.length", op: ">", value: "500"}],
    joins: [{path: "Gene.proteins", style: "OUTER"}],
    sortOrder: "Gene.name ASC", from: "genomic"
};

Customisation

There are lots of user configurable properties, and they all have sane defaults. Below you can see a list of values you can pass into the options object of any loadQuery and loadTemplate call, and their default values:

property	description	takes	default value
additionText	the text to display in the "load x more rows" links	string	"Load [x] more rows"
afterBuildTable	a function to call after the table is built	function	function(table) {}
afterTableUpdate	a function to call after the table is updated with new data	function	function(table, resultSet) {}
allRowsText	the text to display in the links offering to show the remaining rows	string	"Show remaining rows"
collapseHelpText	the text to display in the "hide table" links	string	"hide table"
countText	the text to display in parentheses beside the title	string	"[x] rows"
defaultQueryName	the text to display in the title box if the query has no name	`string	Query Results
emptyCellText	the text to display in cells that have no value	string	"[NONE]"
errorHandler	A function to handle errors from results	function	function(error, statusCode) {console.log("Error:", error, statusCode)}
expandHelpText	the text to display in the "show table" links	string	"show table"
formatCount	whether to format the count for legibility	boolean	true
nextText	the text to display in the "next page" links	string	"Next"
onTitleClick	what to do when the user clicks the table title	"collapse", "mine", "none", or function	"collapse"
openOnLoad	whether the table should be loaded open or not	boolean	false
previousText	the text to display in the "previous page" links	string	"Previous"
queryTitleText	the text to display as the title of the table. If given, this setting overrides any value returned from the server.	string	null
replaceRightArrows	whether or not to replace the string "-->" in titles with a unicode arrow	boolean	true
resultsDescriptionText	the text to display in the toolbox. If given, this setting overrides any value returned from the server.	string	null
rightArrowStyle	the replacement string for the right arrow replacement	string	"\u21E8" (⇨)
showAdditionsLink	whether to show the links offering "x more rows"	boolean	true
showAllCeiling	The maximum number of rows a query can return and still have the table offer to show all rows	int	75
showAllLink	whether to show the links offering "show remaining rows"	boolean	true
showCount	whether to show the count or not	boolean	true
showExportLinks	whether to show the export links (csv, tsv) or not	boolean	true
showMineLink	whether to show the mine links	boolean	true
throbberSrc	the location of a throbber to show when the table is first loaded	location	"images/throbber.gif"
thousandsSeparator	The string to use between groups of digits in the formatted count	string	","
titleHoverCursor	the cursor to show when the mouse is held over the title (unless its behaviour is "none"	string	"pointer"

|Note that options that take a parameter (such as countText) should indicate the position of the parameter with the string "[x]"

If you want all your tables to share the same set of options, you can specify that globally; the example below shows how this can be done to provide internationalisation:

function setLang(code) {
    if (code == "en") {
        return;
    } else if (code == "de") {
        IMBedding.setDefaultOptions({
            additionText: "[x] Mehr Zeilen Anzeigen", 
            allRowsText: "Alle Zeilen Anzeigen", 
            collapseHelpText: "Tafel ausblenden",
            countText, "[x] Zeilen",
            defaultQueryName: "Ergebnisse",
            emptyCellText: "[KEINS]",
            expandHelpText: "Tafel anzeigen"
            exportCSVText: "Als CSV herunterladen",
            exportTSVText: "Als TSV herunterladen",
            mineLinkText: "Tafel im Mine anschauen",
            nextText: "Weiter", 
            previousText: "Zur&uumlck", 
            resultsDescriptionText: "Ergebnisse Ihrer Abfrage"
        });
    } else if (code == "it") {
        IMBedding.setDefaultOptions({
            additionText: "carica altre [x] righe",
            allRowsText: "carica tutte righe",
            collapseHelpText: "chiudi tabella",
            countText: "[x] righe",
            defaultQueryName: "Risultato",
            emptyCellText: "[NIENTE]",
            expandHelpText: "mostra tabella",
            exportCSVText: "Esporta il risultato in formato CSV", 
            exportTSVText: "Esporta il risultato in formato TSV", 
            mineLinkText: "Guarda in Mine",
            nextText: "avanti", 
            previousText: "indietro",
            resultsDescriptionText: "il risultato della loro interrogazione"
        });
    } else // and so on ...

Styling Tables

One of the great advantages of building the table in the client's browser is the ability to apply custom styles. You can do this by supplying a stylesheet with the appropriate class definitions:

imbedded-table-container	The outer container that holds the table
imbedded-table-titlebox	The box that holds the title and count
imbedded-table-title	The text with the actual title
imbedded-table	The table element
imbedded-column-header-row	The row with the column headings
imbedded-cell	Each cell of the table
imbedded-row-odd	Odd numbered table rows
imbedded-row-even	Even numbered table rows
imbedded-column-odd	Odd numbered table columns
imbedded-column-even	Even numbered table columns
imbedded-exportlink	The CSV and TSV export links
imbedded-pagelink	The previous/next paging links
imbedded-mineresultslink	The link to the results in the originating mine
imbedded-prev	The previous paging link
imbedded-next	The next paging link
imbedded-table-tooltip	The tooltip that contains the template description
imbedded-table-expand-help	The link that says "show/hide table"
imbedded-null	Cells that have no value

As well as hosting the javascript library, we also host three variant stylesheets you can use to experiment with, and use as the basis for writing your own CSS stylesheets.

light.css

bold.css

dark.css

Further Examples

You do not even have to write your own code - you can get the webapp for your preferred webservice to generate the code for you - simply click on one of the code generation links at the bottom of any query-builder or template-form page. This will produce code you can immediately run, and perhaps later edit to refine the query. For the JavaScript? files, it will produce code you can just cut and place into the appropriate place in your webpage.

Other clients

We also have client libraries for:

• Perl
• Python
• Java