Plugin Integration with Minerva#

To seamlessly integrate your plugin with Minerva, follow these guidelines to ensure smooth registration, HTML structure creation, and interaction with Minerva.

Changes in version 22.0#

If you maintain a plugin written for version 21, check the following changes.

Changes that can break a version 21 plugin:

onSearch event no longer emits the reaction category; clicking a reaction emits a bioEntity event with the reaction and its participants, see Events
addSingleMarker throws an error when a marker with the given id is already shown; use updateSingleMarker to change it, see Data / BioEntities
the VMH (Recon) fields of elements and reactions (abbreviation, formula, subsystem, …) are always empty, see Data / Elements and Data / Reactions
authors of a submap returned by getModels are always objects with an id, and their name, email and organisation can be null, see Submaps

New functionality:

polygon, text and image markers, and updateSingleMarker - Data / BioEntities
onMapClick, onPanelOpen, onPanelClose and marker click events; onSearch is emitted also for searches without results and for clicks on an empty area of the map, and onClear is emitted when the search is cleared - Events
window.minerva.legend.open(), close() and isOpen(), and the plugin legend methods getLegend() and isLegendActive() - Legend
openPanel takes the id of the reaction, bio-entity or comment to show - Interface
users.getAuthToken() to call the MINERVA API as the logged-in user - Users
colors as #RRGGBBAA strings (fillColorRgba, colorRgba, …), map/submap fields, and creatorId of overlays - Data / Elements, Data / Reactions, Overlays

Deprecated, but still working: the fields model, submodel, annotatorClassName, creator and the { alpha, rgb } color objects, and the panel names 'none', 'plugins' and 'legend'. They may be removed in a future major version.

The complete list of changes, including changes that affect only TypeScript type definitions, is in the minerva-plugin-api changelog.

Registering plugin with Minerva#

Your plugin should utilize the window.minerva.plugins.registerPlugin method for plugin registration. When the plugin is initialized, this method should be called inside plugin initialization method. The function window.minerva.plugins.registerPlugin takes an object as an argument:

{
  pluginName: string;
  pluginVersion: string;
  pluginUrl: string;
  withoutPanel: boolean | undefined;
}

Usage example:#

window.minerva.plugins.registerPlugin({
  pluginName: 'Your Plugin Name',
  pluginVersion: '1.8.3',
  pluginUrl: 'https://example.com/plugins/plugin.js',
  withoutPanel: false,
});

Creating Plugin’s HTML Structure#

The window.minerva.plugins.registerPlugin method returns object with element property which is a DOM element, allowing your plugin to append its HTML content to the DOM. Use this element to create and modify the HTML structure of your plugin.

// Plugin registration
const { element } = window.minerva.plugins.registerPlugin({
  pluginName: 'Your Plugin Name',
  pluginVersion: '1.0.0',
  pluginUrl: 'your-plugin-url',
});

// Modify plugin's HTML structure
const yourContent = document.createElement('div');
yourContent.textContent = 'Your Plugin Content';
element.appendChild(yourContent);

Interacting with Minerva#

All interactions with Minerva should happen through the window.minerva object. This object includes:

configuration: includes information about available types of elements, reactions, miriam types, configuration options, map types and so on
methods will be added in the future

Example of plugin code before bundling:#

require('../css/styles.css');
const $ = require('jquery');

let pluginContainer;

const createStructure = () => {
  $(
    `<div class="flex flex-col items-center p-2.5">
      <h1 class="text-lg">My plugin ${minerva.configuration.overlayTypes[0].name}</h1>
      <input class="mt-2.5 p-2.5 rounded-s font-semibold outline-none border border-[#cacaca] bg-[#f7f7f8]" value="https://minerva-dev.lcsb.uni.lu/minerva">
      <button type="button" id="remove-listeners">Remove all event listeners</button>
      <button type="button" id="remove-listener">Remove onShowOverlay listener</button>
    </div>`,
  ).appendTo(pluginContainer);
};

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

  pluginContainer = element;
  createStructure();

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

  const callbackRemoveDataOverlay = data => {
    console.log('onRemoveDataOverlay', data);
  };

  addListener('onShowOverlay', callbackShowOverlay);

  addListener('onRemoveDataOverlay', callbackRemoveDataOverlay);

  $('#remove-listener').on('click', function () {
    removeListener('onShowOverlay', callbackShowOverlay);
  });

  $('#remove-listeners').on('click', function () {
    removeAllListeners();
  });
}

initPlugin();