InterMine Ajax Embedding Tutorial

Changing the root class will clear your current query - are you sure?

The Basics
Customisation
Templates
Arbitrary Queries
Doing Other Things with Results
Styling Tables
Resources

The basics

You can now embed results from InterMine queries directly into your own web pages. All you need for this is a little knowledge of javascript - and there is a JavaScript client library available so you really do need only a little. If you want to do more, the techniques shown here are flexible and powerful enough to present information in any way you choose.

Example

Below you can see a table with results from the FlyMine preview site. On page ready the table structure was loaded in and the mine was queried for the count. The default behaviour is for results to be loaded into tables with only the title and count showing. Clicking the table will expand it, causing it to fetch data rows from the mine and insert them into itself, allowing you to see its contents.

This will be where the table goes

As you can see, you do not need a lot of code to get this effect:

<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>

Go here to see a very simple demo of the techniques shown on this page.

View The Source For a Complete Working Example

How To Set This Up

We have tried to keep the boilerplate you need to put into your code to a minimum, but there are a few things you need:

Some javascript libraries.

To use the InterMine Embedding library (imbedding.js), you will need to include the following scripts into your page: jQuery, jQuery-JSONP and imbedding.js library.

You do not need to download them, just add the following lines to the head of the page:
<head>  <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.4.4/jquery.min.js" type="text/javascript"> </script>  <script src="http://jquery-jsonp.googlecode.com/files/jquery.jsonp-2.1.4.min.js" type="text/javascript"> </script>  <script src="http://www.intermine.org/lib/imbedding/0.1/imbedding.min.js" type="text/javascript"> </script> </head>
Some css styles

To style the tables, you will also need to include some css with the appropriate classes.
Classes you can style in an embedded table:
- .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-column-data-row: The rows with the data
- .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/more/all 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
There are some stylesheets available (all the ones used on this page) via the web-hosting interface as well.
<head>  <link rel="stylesheet" href="http://www.intermine.org/lib/imbedding/0.1/style/bold.css" /> </head>
Go here to see an example of a stylesheet
A placeholder (or several) on the page

You will need to include an element to tell the table where to go.

<body> <div id="placeholder">The content of this div will be replaced by the table</div> </body>
Using placeholders means you can be precise about where you want your tables to appear on the page, and have as many of them as you want, without interference between them.
Placeholders also mean graceful fallback - simply supply alternative fallback material within the placeholder element: it will be overwritten when the table goes in.

Terribly sorry there is no pretty table to see here. Maybe you don't have JavaScript enabled? No worries, just go through to FlyMine for all the data you can eat
A Script to load the table in

You can either write your own separate library of functions and include it in your head, or you can insert a script element directly into the page:

<script type="text/javascript"> IMBedding.setBaseUrl("http://squirrel.flymine.org/intermine-test"); IMBedding.loadTemplate( { name: "ManagerLookup", size: 10, constraint1: "Manager", op1: "LOOKUP", value1: "*", code1: "A", }, '#placeholder1' ); </script>

Loading an Arbitrary Query

This tool is designed to help you write javascript functions for your pages by generating the code for you. You can paste in xml, experiment with JSON, or build a query from scratch. You can then see the generated code, and cut and paste it into your own page.

Queries can be passed to the loading function as either an xml text string, or as a json object. The loading module must be prepared with the base url before-hand in either case.

You can either define your query using the form below, or simply paste in some XML/JSON. When you press "Load Query" the results will be loaded, and the corresponding code will be generated for you to cut and paste into your own page (just click on the "Show the code" button.)

see information about the formats

Build A Query Paste in some XML/JSON

You can simply paste in xml or json into the appropriate box below, press load, and see the results, and the generating code for them.

Use:

<query name="" model="genomic" view="Gene.homologues.type Gene.homologues.gene.primaryIdentifier Gene.homologues.inParanoidScore Gene.homologues.homologue.primaryIdentifier Gene.homologues.homologue.organism.shortName" sortOrder="Gene.homologues.type asc">
  <constraint path="Gene.primaryIdentifier" op="&lt;" value="D"/>
  <constraint path="Gene.primaryIdentifier" op="&gt;" value="C"/>
</query>

{
    select: [
        "Gene.homologues.type", 
        "Gene.homologues.gene.primaryIdentifier", 
        "Gene.homologues.inParanoidScore", 
        "Gene.homologues.homologue.primaryIdentifier", 
        "Gene.homologues.homologue.organism.shortName"
    ],
    where: [
        {path: "Gene.primaryIdentifier", op: "<", value: "D"},
        {path: "Gene.primaryIdentifier", op: ">", value: "C"}
    ]
}

View Generated Code

The query defined above will go here

Loading a Template

This tool is designed to help you write javascript functions to load desired query results. It will generate code you can cut and paste into your web page to embed query results. Press "Show Source" to see the code generated for each query.

Enter a template name to see the list of templates for this mine. Selecting one will bring up a form for you to enter the values for the parameters that this template expects.

see information about templates

The template results will go here

Other ways to use the data you get back

The previous examples all demonstrate the default functionality, where a table is inserted into the page at the location of the given selector string. However, any arbitrary behaviour is possible by passing a function instead of a selector. The examples below demonstrate some potential applications of this, with two graphs and an alternative tabular display.

One difference between this and the default behaviour is the fact that you will need to specify a result format. The two that will be most useful are jsonpobjects, which all these examples use, and jsonprows, which is similar but provides less syntactic sugar for accessing fields of the result items.

function loadGraph1() {
    IMBedding.loadQuery(
        {
            select: ["Employee.age", "Employee.department.company.name"],
            from: "testmodel"
        },
        {size: 1000, format: "jsonpobjects"},
        function(resultSet) {
            var graphData = [];
            var ageSum = 0;
            var countAtAgeAtCompany = {};
            for (i in resultSet.results) {
                var employee = resultSet.results[i];
                var age = employee.age;
                var company = employee.department.company.name
                ageSum += age;
                if (! countAtAgeAtCompany[company]) {
                    countAtAgeAtCompany[company] = {};
                }
                if (! countAtAgeAtCompany[company][age]) {
                    countAtAgeAtCompany[company][age] = 1;
                } else {
                    countAtAgeAtCompany[company][age] 
                        = countAtAgeAtCompany[company][age] + 1;
                }
            }
            for (name in countAtAgeAtCompany) {
                var company = countAtAgeAtCompany[name];
                var count = 0;
                var sum = 0;
                var companyData = {
                    data: []
                }
                for (age in company) {
                    count += company[age];
                    sum += age * company[age];
                    companyData.data.push([age, company[age]]);
                }
                var companyAverage = parseInt(sum / count);
                companyData.label = 
                    name + " [av: " + companyAverage + "]";
                graphData.push(companyData);
            }
            var options = {
                series: {
                    stack: true,
                    lines: {show: false},
                    bars: {show: true, barWidth: 0.9},
                },
                legend: {position: "nw"}
            };
            var plot = $.plot("#graph", graphData, options);
            var averageAge = parseInt(ageSum / resultSet.results.length);
            $('<span></span>').html("Age (average:" + averageAge + ")")
                              .addClass("axis-label").appendTo('#graph');
        }
    );
}

function loadGraph2() {
    IMBedding.loadQuery(
        {
            select: ["Manager.age", "Manager.seniority", "Manager.name"],
            where: [{path: "Manager.age", op: ">", value: 30}],
            from: "testmodel"
        },
        {size: 1000, format: "jsonpobjects"},
        function(resultSet) {
            var graphData = [];
            var managers = {};
            var ageVsSen = {
                label: "Seniority by Age",
                color: "rgb(0, 115, 234)",
                points: {show: true},
                data: []
            };
            var trendLine = {
                label: "Trend Line",
                color: "rgb(255, 0, 132)",
                lines: {show: true},
            };
            for (i in resultSet.results) {
                var manager = resultSet.results[i];
                var seniority =manager.seniority;
                var age = manager.age;
                ageVsSen.data.push([age, seniority]);
                managers[age + "-" + seniority] = manager;
            }
            trendLine.data = findLineByLeastSquares(ageVsSen.data);
            graphData.push(ageVsSen);
            graphData.push(trendLine);
            var options = {
                grid: {hoverable: true, clickable: true},
                legend: {position: "nw"}
            };
            var plot = $.plot("#graph", graphData, options);
            $('#graph').bind("plothover", function(event, pos, item) {
                if (item) {
                    $("#tooltip").remove();
                    var x = item.datapoint[0].toFixed(2),
                        y = item.datapoint[1].toFixed(2);
                    var key = parseInt(x) + "-" + parseInt(y);
                    var manager = managers[key];
                    showTooltip(item.pageX, item.pageY, manager.name);
                }
                else {
                    $("#tooltip").remove();
                    previousPoint = null;            
                }
            }).bind("plotclick", function(event, pos, item) {
                if (item) {
                    var x = item.datapoint[0].toFixed(2),
                        y = item.datapoint[1].toFixed(2);
                    var key = parseInt(x) + "-" + parseInt(y);
                    var manager = managers[key];
                    var url = baseUrl + "/objectDetails.do?id=" 
                                + manager.objectId;
                    window.location.replace(url);
                }
            });
            $('<span></span>').html("Age").addClass("axis-label").appendTo('#graph');
        }
    );
}

function loadDepartmentSummary(departmentName) {
    departmentName = departmentName || "Sales";
    IMBedding.loadQuery(
        {
            select: [
                "Department.name", "Department.company.name", 
                "Department.employees.name", 
                "Department.employees.age", 
                "Department.employees.address.address", 
                "Department.manager.name",
                "Department.company.departments.name"
            ],
            where: [
                {
                    path: "Department.name", 
                    op: "=", value: departmentName
                },
                {
                    path: "Department.company.name", 
                    op: "=", value: "Wernham-Hogg"
                }
            ],
            from: "testmodel"
        },
        {size: 1000, format: "jsonpobjects"},
        function(resultSet) {
            var department = resultSet.results[0];
            var summary = $('<div></div>').addClass("department-summary");
            var title = document.createElement("h2");
            title.appendChild(document.createTextNode(
                        department.company.name + ": "));
            var depSelect = document.createElement("select");
            $(depSelect).button();
            var noOfDeps = department.company.departments.length;
            for (var i = 0; i < noOfDeps; i++) {
                var dep = department.company.departments[i];
                var depOption = document.createElement("option");
                if (dep.objectId == department.objectId) {
                    depOption.selected = true;
                }
                depOption.innerHTML = dep.name;
                depSelect.appendChild(depOption);
            }
            title.appendChild(depSelect);
            $(depSelect).change(function() {
                loadDepartmentSummary($(depSelect).val());
            });
            summary.append(title);
            var subtitle = document.createElement("h3");
            subtitle.innerHTML = "Manager: " + department.manager.name;
            summary.append(subtitle);
            var employeeCount = department.employees.length;
            var list = document.createElement("ul");
            for (var i = 0; i < employeeCount; i++) {
                var employee = department.employees[i];
                if (employee.objectId == department.manager.objectId) {
                    continue;
                }
                var item = document.createElement("li");
                var link = document.createElement("a");
                link.href = baseUrl + "/objectDetails.do?id=" 
                                    + employee.objectId;
                link.innerHTML = employee.name;
                item.appendChild(link);
                $(link).hover(
                    getEmployeeTooltipper(employee),
                    function(event) {
                        $('.tooltip').remove();
                    }
                );
                list.appendChild(item);
            }
            summary.append(list);
            $('#graph').empty().append(summary);
        }
    );
};

This will be where the graph goes

Styling The Tables

The tables produced with the imbedding.js library are designed to be easily stylable. Customisation is possible by using the classes that the elements are decorated with:

Classes you can style in an embedded table:

.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

There are three styles supplied here with the tutorial, and you can see how changing them changes the appearance of the table below:

Customising the Tables

What properties can I configure, and what are the defaults?

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]"`
expandHelpText	the text to display in the "show table" links	`string`	`"show table"`
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`
resultsDescriptionText	the text to display in the toolbox. If given, this setting overrides any value returned from the server.	`string`	`null`
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"`
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 used for 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 ...

Furthermore, the table itself is an object of type "Table", and upon production and and updates it is passed to the (no-op) functions IMBedding.afterBuildTable(table) and IMBedding.afterTableUpdate(table, resultSet) respectively. To get access to the table automatically, simply replace the no-op versions with your own code:

IMBedding.afterBuildTable = function(table) {doSomethingWith(table)};

The table object provides you with deep low level access to many aspects, including all the elements (which are attributes of it, as jQuery objects) and many methods. For example if you load a template but don't want one of the columns, you could do something like this:

IMBedding.afterTableUpdate = function(table) { table.table.children('tr').each(function() { $(this.children[unwantedColIndex]).remove(); }); };

The above code will then apply to all tables built by IMBedding. To alter the behaviour for just one table, supply a value for the afterBuildTable and afterTableUpdate options values. Both the table specific function, and the global one will be run.

Showing Contents on Load

Setting openOnLoad to true loads the table pre-opened. Clicking on the titlebar of this table will collapse it.

View Source

Changing Title Click Behaviour

The default behaviour for a click on the title is to expand/collapse the table. You can choose other behaviours:

Default Behaviour

This will be where the table goes

Click Through to Mine

This will be where the table goes

No Behaviour

This will be where the table goes

Arbitrary Behaviour

This will be where the table goes

View Source

Configuring What is Shown

As well as the title, by default the table will also contain export links, a link to the results in the originating mine, a count of the total results, and pages with 10 rows of results. The tables below show adjustments to these features.

No Export Links

options.showExportLinks = false;

This will be where the table goes

No Count

options.showCount = false;

This will be where the table goes

No Mine Link

options.showMineLink = false;

This will be where the table goes

A Different Number of Rows

data.size = 15;

This will be where the table goes

A Different Language

data.nextText = "avanti"; // and others

This will be where the table goes

View Source

InterMine Ajax Embedding Tutorial

The basics

Example

How To Set This Up

Some javascript libraries.

Some css styles

A placeholder (or several) on the page

A Script to load the table in

Loading an Arbitrary Query

Views

Constraints

Joins

Loading a Template

Other ways to use the data you get back

Styling The Tables

You May Be Interested In

Customising the Tables

What properties can I configure, and what are the defaults?

Showing Contents on Load

Changing Title Click Behaviour

Default Behaviour

Click Through to Mine

No Behaviour

Arbitrary Behaviour

Configuring What is Shown

No Export Links

No Count

No Mine Link

A Different Number of Rows

A Different Language