Back to index

Integration Guide

This API provides a seamless solution to integrate Marvin JS editor into your HTML page no matter whether the resources of the Marvin JS editor are located on the same domain or not.
It also resolves CORS issues when you load and run the editor from a different domain.

You can control from which domains the editor is available. The default rule is strict, that is, only the same domain is accepted.
See the configuration on how to control domain restrictions.

Setting Up Access Rules

The js/origin.js file lists the accepted domains. You can add domains to it by either using strings or regular expressions.

Accept only same origin:

window.domain = window.origin

No restriction:'*'

Exact domain:'http://localhost:8080'

More domains (either localhost or through any port and with any protocol):\/\/)(localhost|\S+\.example\.com)(:\d+)?/gm

Basic Example

Follow the steps below to insert an editor into your page.

  1. Load the client.js file of the Marvin JS package. It will load the ChemaxonMarvinJs API.
  2. Define a div DOM element with a unique ID where would you like to insert the editor.
  3. Call the createEditor method and give the ID of the above div as parameter.

The editor will be displayed in the desired div element.

<!DOCTYPE html>
    <script src="js/client/client.js"></script>
    <div id="sketch"></div>

API Usage

The createEditor method returns with a Promise object that is resolved with a reference to the editor object when it is loaded.

    ChemaxonMarvinJs.createEditor("sketch", "http://localhost:8080/");
createEditor(parentID: string, marvinUrl: string, settings: any): Promise<Editor>

The createEditor method expects the following parameters:

The editor object provides various methods to control the usage of the loaded editor component. Each of them returns with a Promise object as there are async callings in the background.


    ChemaxonMarvinJs.createEditor("sketch",'..').then(function(e) {
        editor = e;

Molecule Import

importStructure(format: string, source: string, options: any): Promise<void>

Load a structure into the editor.

How to import SMILES:


Paste Structure

pasteStructure(format: string, source: string, options: any): Promise<void>

Add the given structure to the editor content, see importStructure for parameters.

How to paste SMILES:


Molecule Export

exportStructure(format: string, options: any): Promise<string>

Export the contents of the canvas in the desired molecule format or image (as base64 encoded data uri).

How to export in MRV format:

editor.exportStructure('mrv').then(function (mrv) {

How to retrieve the image representation of the contents of the canvas and append an image to the end of the document:

editor.exportStructure('png', {'background-color': 'red' }).then(function(datauri) {
    var img = document.createElement('img');
    img.src = datauri;

Get Settings

getDisplaySettings(): Promise<any>

How to retrieve current display settings:

editor.getDisplaySettings().then(function (settings) {

Update Settings

setDisplaySettings(settings: any): Promise<any>

Apply a JSON with various properties to customize the rendering of the editor. You can list most of the controllable properties with the getDisplaySettings method.

How to change carbon label visibility property:

editor.setDisplaySettings({ 'carbonLabelVisible': false });

Is Empty

isEmpty(): Promise<boolean>

Provide information whether the canvas is empty.

Print canvas state:

editor.isEmpty().then(function(b) {
    console.log((b? 'empty canvas' : 'has structure'));
}); // like isEmpty(): Promise<boolean>;


clear(): Promise<void>

Event Listeners

on(eventType: string, eventHandler: function): Promise<void>

You can register event listeners for the editor (all event types are enumerated in the example).
Note that the registered events are performed on the host page. The remote editor only notifies the host page about the changes.

function onChange(eventType) {
    console.log(eventType + " event is invoked");
    editor.exportStructure('mrv').then(function(mrv) {
        molSource = mrv;

editor.on('molchange', function () { onChange("molchange") }); // as editor canvas content has been changed (edit content, import structure, undo, redo, ...)
editor.on('selectionchange', function () { onChange("selectionchange") }); // as the list of selected atoms/bonds are changed.
editor.on('undo', function () { onChange("undo") }); // as undo action is invoked
editor.on('redo', function () { onChange("redo") }); // as redo action is invoked

Back to index