Plugin JavaScript API#

Introduction#

There is possibility to create JavaScript plugins for minerva. Tutorial on how to create plugins can be found in the minerva starter kit repository. Here we provide only documentation for the JavaScript API.

Registering with Minerva#

When the plugin is loaded into Minerva minervaDefine function is called, so this needs to be present in every plugin script. This function needs to return an object with methods that minerva will call to interact with plugin. List of all available methods can be found here.

Below you can find sample plugin:

minervaDefine(function () {
  return {
    register: function (minervaObject) {
      console.log("registering test plugin");
    },
    unregister: function () {
      console.log("unregistering test plugin");
    },
    getName: function () {
      return "test plugin";
    },
    getVersion: function () {
      return "0.0.1";
    }
  };
})

plugin methods that should be exposed to minerva#

• register: function (minervaObject) - this method will be called by minerva when plugin is being registered. minervaObject contains information about the current project and configuration of the platform.
• unregister: function () - this method will be called when plugin is being unregistered.
• getName: function () - this method should return name of the plugin
• getVersion: function () - this method should return version of the plugin
• minWidth: number - (optional) this is the minimum width of the tab that is required for proper visualization of the plugin
• defaultWidth: number - (optional) this is the default width of the tab that is recommended for proper visualization of the plugin
• notifyError: function(data) - (optional) this method will be called when listener registered by the plugin crash. data will provide detail information about the problem.

minervaObject#

minervaObject contains following properties:

• element - HTML div that should be used for GUI
• project - project data
• configuration - minerva configuration
• pluginData - entry point to manipulate plugin related data on the server side

Project data#

project contains following properties:

• data - interface to obtain data about map:
  • getBioEntityById({id, modelId, type}) - returns Promise of the BioEntity identified by the triplet:
    • id - unique BioEntity identifier,
    • modelId - submap on which BioEntity is expected
    • type - type of the BioEntity (‘ALIAS’ or ‘REACTION’)
  • getAllBioEntities() - returns Promise with array containing all BioEntities in given project
  • getReactionsWithElement({id, modelId, type}) - returns a Promise of an array with all reactions that include BioEntity identified by the parameter triplet
  • getProjectId() - returns string with project id
  • getName() - returns string with project name
  • getVersion() - returns string with project version
  • getDisease() - returns a structure with disease identifier associated with the project
  • getOrganism() - returns a structure with organism identifier associated with the project
  • getModels() - returns array with data about all submaps
  • getDataOverlays() - returns list of available data overlays
  • getOverviewImages() - returns list of available overview images
• map - interface to interact with minerva interface:
  • addListener({type, dbOverlayName, object, callback}) - adds a listener to database connector like drug database or to ‘object’ in minerva:
    • dbOverlayName - string representing database for which we want to register listener, available databases are: search, drug, chemical, mirna, comment
    • object - object type for which we want to register listener. Currently valid objects are: map, overlay, map-dialog, plugin
    • type - type of the event, supported db Events are:
      • for dbOverlayName: onSearch, onFocus
      • for ‘map’ object: onZoomChanged, onCenterChanged
      • for ‘overlay’ object: onShow, onHide
      • for ‘map-dialog’ object: onDrag, onDragStart, onDragStop, onResize, onResizeStart, onResizeStop, onOpen
      • for ‘plugin’: onResize, onUnload
  • removeListener({type, dbOverlayName, callback}) - removes listener added in addListener method
  • removeAllListeners() - removes all listeners added by addListener method
  • getHighlightedBioEntities(dbOverlayName) - returns a promise with list of elements that are currently highlight by the specific database
  • showBioEntity({element, type, options}) - highlight element on the map. Returns a Promise when operation is finished. Arguments:
    • element - triplet identifying the element, it should contain three fields: id, type, model
    • type - how do you want to visualize BioEntity: ‘ICON’, ‘SURFACE’
    • options - set of visualization options: color, opacity, lineColor, lineWeight, lineOpacity
  • hideBioEntity({element, type}) - hides element on the map. Arguments:
    • element - triplet identifying the element, it should contain three fields: id, type, model
    • type - how do you want to visualize BioEntity: ‘ICON’, ‘SURFACE’
  • setCenter({modelId, x, y}) - set center point on the map:
    • modelId - submap that should be centered
    • x, y - center coordinates
  • getCenter({modelId}) - returns center point on the map:
    • modelId - submap that we are interested in
  • fitBounds({modelId, x1, y1, x2, y2}) - zoom in the map in a way that rectangle defined by parameter coordinates is visible:
    • modelId - submap that we are interested in
    • x1, y1 - top left corner coordinates
    • x2, y2 - right bottom corner coordinates
  • getBounds({modelId}) - returns bounds of the map
    • modelId - submap that we are interested in
  • setZoom({modelId, zoom}) - set zoom level of the map
    • modelId - submap that we are interested in
    • zoom - zoom level (integer)
  • getZoom({modelId}) - returns zoom level of the map
    • modelId - submap that we are interested in
  • openMap({id}) - opens submap
    • id - submap that we are interested in
  • getVisibleDataOverlays() - returns Promise with list of visible data overlays
  • triggerSearch({dbOverlayName, query, coordinates, perfect, fitBounds, modelId, zoom}) - this method triggers search operation on the database identified by dbOverlayName. Search can be done via query or coordinates.
    • dbOverlayName - string representing database for which we want to trigger search operation, available databases are: search, drug, chemical, mirna, comment
    • query - when searching by query this property should represented searched string
    • perfect - when searching by query this property indicates if results should match perfectly or not
    • coordinate - when searching by coordinates this property should indicate x, y coordinates on the map
    • modelId - when searching by coordinates this property should indicate submap identifier
    • zoom - when searching by coordinates this property should zoom level at which we want to trigger search. Searching on different zoom level might give different results due to differences in distance of objects (in pixels) or visibility of elements (in Compartments and Pathways view)
    • fitBounds - should the map be resized to the rectangle fitting all results
• showOverviewImage(overviewImage) - opens popup window with overview image
  • overviewImage - overview image. This can obtained from getOverviewImages.
  • showOverviewImage() - closes popup window with overview image
  • showDataOverlay(overlay) - returns Promise resolved when data overlay is shown
    • overlay - overlay or identifier of the overlay to be shown. This can obtained from getDataOverlays.
  • hideDataOverlay(overlay) - returns Promise resolved when data overlay is hidden
    • overlay - overlay or identifier of the overlay to be hidden. This can obtained from getDataOverlays.

Configuration#

configuration contains following properties:

• elementTypes: list of all element types used in current minerva version
• reactionTypes: list of all reaction types used in current minerva version

Server side plugin data#

pluginData structure allows you to set/get some data on the server side. Here are methods that allows it:

• setGlobalParam(key, value) - sets global (for all users) key value property for given plugin; method returns Promise that is resolved when data is persisted
• getGlobalParam(key) - gets global (for all users) property for given key; method returns Promise that is resolved when data is obtained
• setUserParam(key, value) - sets key value property for given plugin and current user; method returns Promise that is resolved when data is persisted
• getUserParam(key) - gets key value property for given plugin and current user; method returns Promise that is resolved when data is obtained