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:

window.domains='*'

Exact domain:

window.domains='http://localhost:8080'

More domains (either localhost or example.com through any port and with any protocol):

window.domains=/(https?:\/\/)(localhost|\S+\.example\.com)(:\d+)?/gm

Basic Example

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

Load the client.js file of the Marvin JS package. It will load the ChemaxonMarvinJs API.
Define a div DOM element with a unique ID where would you like to insert the editor.
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>
<html>
<head>
    <script src="js/client/client.js"></script>
</head>
<body>
    <div id="sketch"></div>
    <script>
        ChemaxonMarvinJs.createEditor("sketch");
    </script>
</body>
</html>

API Usage

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

<script>
    ChemaxonMarvinJs.createEditor("sketch", "http://localhost:8080/");
</script>

createEditor(parentID: string, marvinUrl: string, settings: any): Promise<Editor>

The createEditor method expects the following parameters:

parentID: ID of the parent element where the editor is going to be inserted. If it cannot be found, the editor is appended to the end of the document.
marvinUrl: The URL of the Marvin JS directory (it can be relative or absolute url but only http: and https: protocols are accepted).
settings: a JSON with thed isplay settings (leave it empty unless you need customization).

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.

Editor

<script>
    ChemaxonMarvinJs.createEditor("sketch",'..').then(function(e) {
        editor = e;
        editor.importStructure('smiles','CCC');
    });
</script>

Molecule Import

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

Load a structure into the editor.

format: Input format of the given structure (null or empty string for auto recognition).
source: The molecule source to be imported.
options: Import options in JSON format (optional parameter).

How to import SMILES:

editor.importStructure('smiles','CCCCC');

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:

editor.pasteStructure('smiles','CCCCC');

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).

format: Output format (chemical format or image type).
options: Export options in JSON format (optional). The given properties can be different depending on the output format.

How to export in MRV format:

editor.exportStructure('mrv').then(function (mrv) {
            console.log(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;
    document.appendChild(img);
});

Get Settings

getDisplaySettings(): Promise<any>

How to retrieve current display settings:

editor.getDisplaySettings().then(function (settings) {
            console.log(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.

settings: A JSON with certain display properties to be updated, see available properties here.

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

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