joshkh/im_tool_integration_proposal.md

## im_tool_integration_proposal.md

      
    Raw
  

              im_tool_integration_proposal.md
            
          
    Thanks to Vivek for his great proposal!
https://gist.github.com/vivekkrish/2e5e4128efbbf2014c194aae6b83d245
Assumptions:


Dependencies are bundled into the app (requirejs, browserify, webpack)

Our justification is that sharing dependencies between third party tools introduces levels of complexity that are expensive (time consuming) and can be challenging to developers. If we find that third party apps are truly to large then we'll reconsider a more complicated approach.
App structure:

.
+-- myapp/
|   +-- app.css (optional)
|   +-- config.json (required)
|   +-- package.json (required)
|   +-- src/myapp.js (reflected in package.json as "main")
|   +-- template.html (optional)

config.json

{
  "accepts": ["id" "ids" "list" "lists" "records" "rows"],
  "classes": ["Gene" "Protein" "*"]
}

id: a single database id
ids: multiple database ids
list: a single list name
lists: multiple list names
records: a raw result from POSTing to /query/results with format "jsonobjects"
rows: a raw result from POSTing to /query/results with format "json"

Plurality (i.e. id vs ids) will help to determine which context a tool can appear (report page, list analysis page)
Records and Rows can also be accepted. The advantage here is that BlueGenes has likely already run and stored the query results in memory, so the tool can skip a redundant call to the server.
myapp.js

Must export a constructor function with the same package name found in package.json
var MyApp = function(el, service, package, state) {
  // ...
}

el: the id of a dom element where the tool will render
service: an object representing an intermine service

{
  "root": "www.flymine.org/query",
  "token": "bananacakes"
}

package: an object representing the data passed to the app

{
  "class": "Gene",
  "format": "ids",
  "value": [123, 456]
}

state: the last state of the tool (more on this later)

package.json

This must have property specifying the entry point
{
  "main": "[some]/[app].js"
}
template.html

This is an optional chunk of HTML that will be injected into the div during initial rendering. No <head> or <body> tags.
app.css

If found it will be automatically namespaced and injected into the target element
Integration


Apps will be installed to bluegenes/resources/public/apps/[someapp]
If an app.css is present it will be preprocessed using LESS to provide a namespace
We will use jQuery's getScript() function to load the app on demand