BlueGenes is built in Clojure and ClojureScript, but we don't want to re-write all existing browser data vis and analysis tools, so we've built a way to integrate JavaScript tools into our pages.
You can take existing JavaScript biology applications and provide a wrapper for them, allowing them to interact with BlueGenes.
This document provides reference for the API specifications, but there is also a tutorial to walk you through creating a wrapper for your tool.
.
+-- myapp/
| +-- dist/
| +-- style.css (optional)
| +-- bundle.js (required)
| +-- src/
| +-- style.less (optional, could be some other preprocessor too.)
| +-- index.js (optional but recommended)
| +-- config.json (required)
| +-- package.json (required)
| +-- demo.html (optional)
| +-- preview.png (optional)
You may optionally also have additional folders, including node_modules, if needed. They won't interfere.
Put all of your prod-ready bundled files in here. Ideally this should be no more than two things:
Where do the bundled files come from? Probably the src directory. This is the folder you'll be doing most of your work in.
This is the preferred entry point to build dist/bundle.js. May import external libraries or node modules if needed. See bluegenesProtVista example. Make sure to export an object that matches your tool name and has a main method - e.g. for bluegenesProtVista, there is an exposed method called bluegenesProtvista.main()
.
The signature of the main method should look have the following signature:
var myApp.main = function(el, service, imEntity, state, config, navigate) {
// code to initialise your app here
}
el - The id of a dom element where the tool will render
service - An object representing an intermine service, like the following:
{
"root": "www.flymine.org/query",
"token": "bananacakes"
}
imEntity
An object representing the data passed to the app, e.g.:
{
"class": "Gene",
"format": "id",
"value": 456
}
To see a full example, look at how the method is called in bluegenesProtVista's ui demo file and how index.js uses the values passed to it
navigate
A function you can call to make BlueGenes navigate to a specific page.
// Navigate to a report page.
navigate("report", {type: "Gene", id: 1018204});
// Run a query and open the page showing the results.
navigate("query", myQueryObj);
You can optionally specify a third argument with the namespace of a mine (e.g. "humanmine"
).
This is the preferred entry point to build dist/styles.css. If your tool has a stylesheet already, make sure to import the styles and wrap them in a parent class to ensure the styles are sandboxed and don't leak into another file. See bluegenesProtVista's less file for an example and the css it compiled to.
This file provides bluegenes-specific config info. Some further config info is drawn from package.json as well.
{
"accepts": ["id", "ids", "records", "rows"],
"classes": ["Gene", "Protein", "*"],
"columnMapping" : {"Protein" : {"id" : "primaryAccession"}},
"files" : {
"css" : "dist/style.css",
"js" : "dist/bundle.js"
},
"toolName" : "Protein Features"
}
Plurality (i.e. id vs ids) will help to determine which context a tool can appear (report page, list analysis page)
classes default to *
if this tool isn't class / objectType specific. otherwise your tool might be specific to a certain class, e.g. a gene displayer.
columnMapping is an important way to specify (or override) which columns should be passed to the tool by BlueGenes. As an example, for a gene tool, you might want to pass a symbol, OR a primaryIdentifier, or even secondaryIdentifier - and this might change depending in the InterMine that is fuelling the BlueGenes. Set a default likely value here, and in the future individual bluegenes administrators can override it if needed.
files - one file each for css and js, please. This should be the file bundled/built with all dependencies except/ imjs if needed. CSS is optional if the tool has no styles.
toolName what would you want to see as a header for this tool? e.g. ProtVista might be called "Protein Features".
Optional preview image for the "app store" dashboard (when admins are selecting tools, this is the way to impress them!)
Credits: Thanks to Josh and Vivek for early work on the Tool API proposal.
Can you improve this documentation? These fine people already did:
uosl & Leandro DoctorsEdit on GitHub
cljdoc is a website building & hosting documentation for Clojure/Script libraries
× close