Events#

Plugins can interact with Minerva by subscribing to events. These events allow plugins to respond to user actions, system events, or changes in the application state.

Add Event Listener#

To listen for specific events, plugins can use the addListener method in events object returned by window.minerva.plugins.registerPlugin. This method takes two arguments: the name of the event and a callback function to handle the event. Available Events:

• onAddDataOverlay - triggered after successfully adding an overlay; the created overlay is passed as an argument. Example argument:

{
  "name": "Example Overlay",
  "creatorId": 3,
  "creator": "3",
  "description": "Different",
  "genomeType": null,
  "genomeVersion": null,
  "id": 149,
  "publicOverlay": false,
  "type": "GENERIC",
  "order": 9
}

• onRemoveDataOverlay - triggered after successfully removing an overlay; the ID of the removed overlay is passed as an argument. Example argument:

43

• onShowOverlay - triggered after displaying an overlay on the map; the displayed overlay is passed as an argument. Example argument:

{
  "name": "Generic advanced format overlay",
  "creatorId": 3,
  "creator": "3",
  "description": "Data set provided by a user",
  "genomeType": null,
  "genomeVersion": null,
  "id": 20,
  "publicOverlay": true,
  "type": "GENERIC",
  "order": 9
}

• onHideOverlay - triggered after disabling an overlay on the map; the disabled overlay is passed as an argument. Example argument:

{
  "name": "colored overlay",
  "creatorId": 3,
  "creator": "3",
  "description": "",
  "genomeType": null,
  "genomeVersion": null,
  "id": 24,
  "publicOverlay": true,
  "type": "GENERIC",
  "order": 10
}

• onBackgroundOverlayChange - triggered after changing the background; the identifier of the new background is passed as an argument. Example argument:

15

• onSearch - triggered after completing a search; the elements returned by the search are passed as arguments.
  • a text search emits three separate ‘onSearch’ events, one per searched category: bioEntity, drugs and chemicals. All three are always emitted, also for a category that matched nothing (results is then empty). The order in which they arrive is not guaranteed, so a plugin that keeps state per search should reset it on the bioEntity event rather than on the first event it sees.
  • a click on a map element (or a search by coordinates) emits a single bioEntity event identifying the element that was hit. Clicking a reaction emits the reaction and its participants in this event.
  • a click on an empty area of the map emits the three events with empty searchValues and results, so that plugins can clear the selection of the previous search.
  • the reaction category emitted by version 21 is not emitted anymore; reactions arrive within bioEntity.
  Example argument:

{
  type: 'drugs',
  searchValues: ['PRKN'],
  results: [
    [{
      bioEntity: {
        id: 38253,
        map: 52,
        glyph: null,
        submap: null,
        compartment: 46644,
        elementId: 'path_0_sa11305',
        x: 18412,
        y: 3088.653195488725,
        z: 2298,
        width: 80,
        height: 40,
        fontSize: 12,
        fontColor: {
          alpha: 255,
          rgb: -16777216,
        },
        fontColorRgba: '#000000FF',
        fillColor: {
          alpha: 255,
          rgb: -3342388,
        },
        fillColorRgba: '#CCFFCCFF',
        borderColor: {
          alpha: 255,
          rgb: -16777216,
        },
        borderColorRgba: '#000000FF',
        visibilityLevel: '4',
        transparencyLevel: '0',
        notes: '',
        symbol: 'PRKN',
        fullName: 'parkin RBR E3 ubiquitin protein ligase',
        name: 'PRKN',
        nameX: 18412,
        nameY: 3088.653195488725,
        nameWidth: 80,
        nameHeight: 40,
        nameVerticalAlign: 'MIDDLE',
        nameHorizontalAlign: 'CENTER',
        synonyms: ['AR-JP', 'PDJ', 'parkin'],
        formerSymbols: ['PARK2'],
        activity: false,
        lineWidth: 1,
        complex: 38252,
        initialAmount: null,
        charge: null,
        initialConcentration: 0,
        onlySubstanceUnits: false,
        homodimer: 1,
        hypothetical: null,
        boundaryCondition: false,
        constant: false,
        modificationResidues: [{
          id: 58046,
          idModificationResidue: 'rs2',
          name: '',
          x: 18481.67916137211,
          y: 3118.9740341163433,
          z: 2299,
          width: 15,
          height: 15,
          borderColor: {
            alpha: 255,
            rgb: -16777216,
          },
          borderColorRgba: '#000000FF',
          fontSize: 10,
          state: null,
          size: 225,
          center: {
            x: 18489.17916137211,
            y: 3126.4740341163433,
          },
          elementId: 'rs2',
        }, ],
        stringType: 'Protein',
        substanceUnits: null,
        references: [{
          link: 'https://www.genenames.org/cgi-bin/gene_symbol_report?match=PRKN',
          type: 'HGNC_SYMBOL',
          resource: 'PRKN',
          id: 173229,
          annotator: 'HGNC',
        }, ],
        compartmentName: 'Dopamine metabolism',
        complexName: 'insoluble aggregates',
      },
      perfect: true,
    }, ],
  ],
};

• onClear - triggered after clearing the search with the “Clear” button or with the plugin API clearAllElements call (when it clears content, drugs or chemicals; clearing only markers does not trigger it); no arguments are passed

• onZoomChanged - triggered after changing the zoom level on the map; the zoom level and the map ID are passed as argument. Example argument:

{
  "modelId": 52,
  "zoom": 9.033753064925367
}

• onCenterChanged - triggered after the coordinates of the map center change; the coordinates of the center and map ID are passed as argument. Example argument:

{
  "modelId": 52,
  "x": 8557,
  "y": 1675
}

• onBioEntityClick - triggered when someone clicks on a pin; the element to which the pin is attached is passed as an argument. Example argument:

{
  "id": 40072,
  "modelId": 52,
  "type": "ALIAS"
}

• onPinIconClick - triggered when someone clicks on a pin icon; the element to which the pin is attached is passed as an argument. Example argument:

{
  "id": 40072
}

Marker pin:

{
  "id": "b0a478ad-7e7a-47f5-8130-e96cbeaa0cfe"
}

• onSurfaceClick - triggered when someone clicks on an overlay surface; the element to which the pin is attached is passed as an argument. Example argument:

{
  "id": 18
}

Surface marker overlay:

{
  "id": "a3a5305f-acfa-47ff-bf77-a26d017c6eb3"
}

• onLineClick, onPolygonClick, onTextClick, onImageClick - triggered when someone clicks on a line, polygon, text or image marker added with addSingleMarker; the marker id is passed as an argument. Example argument:

{
  "id": "b0a478ad-7e7a-47f5-8130-e96cbeaa0cfe"
}

• onMapClick - triggered on every left click on the map, before the more specific click events above for the same click; the map id, the coordinates of the click and what the click hit are passed as an argument. Unlike the other click events it also fires when the click hits nothing, with target set to null. Only the topmost object under the cursor is reported. target is one of:
  • { "type": "element", "id": number } - an element of the map
  • { "type": "reaction", "id": number } - a reaction
  • { "type": "comment", "id": number } - a comment pin
  • { "type": "surface", "id": number or string } - a data overlay surface; id is the same as in onSurfaceClick
  • { "type": "marker", "markerType": string, "id": string } - a marker added with addSingleMarker; markerType is its type
  Example argument:

{
  "mapId": 52,
  "x": 8557,
  "y": 1675,
  "target": {
    "type": "element",
    "id": 40072
  }
}

• onSubmapOpen - triggered when submap opens; the submap identifier is passed as an argument. Example argument:

52

• onSubmapClose - triggered when a submap closes; the submap identifier is passed as an argument. Example argument:

51

• onPanelOpen - triggered after a panel opens; the name of the panel is passed as an argument. Example argument:

{
  "name": "search"
}

• onPanelClose - triggered after a panel closes; the name of the panel that was open is passed as an argument. Example argument:

{
  "name": "overlays"
}

Panel names: search, project-info, export, submaps, overlays, overlay-group, available-plugins, layers, reaction, bio-entity, comment. Switching directly from one panel to another emits onPanelClose for the old panel, then onPanelOpen for the new one. Both events are triggered whether the change came from the user or from openPanel / hidePanel (see Interface). The legend is not a panel and triggers neither event.

• onPluginUnload - triggered when a plugin is unloaded or reloaded; the hash of the unloaded plugin is passed as an argument. Example argument:

{
  "hash": "b0a478ad-7e7a-47f5-8130-e96cbeaa0cfe"
}

Example of adding event listener:#

const {
  element,
  events: { addListener, removeListener, removeAllListeners },
} = minerva.plugins.registerPlugin({
  pluginName,
  pluginVersion,
  pluginUrl,
});

const callbackShowOverlay = data => {
  console.log('onShowOverlay', data);
};

addListener('onShowOverlay', callbackShowOverlay);

Remove Event Listener#

To remove event listener, plugins can use the removeListener method in events object returned by window.minerva.plugins.registerPlugin. This method takes two arguments: the name of the event and the reference to the callback function previously used to add the listener.

const {
  element,
  events: { addListener, removeListener, removeAllListeners },
} = minerva.plugins.registerPlugin({
  pluginName,
  pluginVersion,
  pluginUrl,
});

const callbackShowOverlay = data => {
  console.log('onShowOverlay', data);
};

addListener('onShowOverlay', callbackShowOverlay);

removeListener('onShowOverlay', callbackShowOverlay);

Remove All Event Listeners#

To remove all event listeners attached by a plugin, plugins can use the removeAllListeners method in events object returned by window.minerva.plugins.registerPlugin.

const {
  element,
  events: { addListener, removeListener, removeAllListeners },
} = minerva.plugins.registerPlugin({
  pluginName,
  pluginVersion,
  pluginUrl,
});

const callbackShowOverlay = data => {
  console.log('onShowOverlay', data);
};

const callbackHideOverlay = data => {
  console.log('onHideOverlay', data);
};

const callbackOpenSubamp = data => {
  console.log('onSubmapOpen', data);
};

addListener('onHideOverlay', callbackHideOverlay);

addListener('onSubmapOpen', callbackOpenSubamp);

addListener('onShowOverlay', callbackShowOverlay);

removeAllListeners();