Marvin JS API Reference

Table of Contents

Static functions

marvin.Sketch.addRequestInterceptor(function(config))
Registers a function that complete the header of HTTP requests that Marvin JS sends to the remote services with extra fields.

Parameters:

marvin.Sketch.addResponseErrorHandler(function(message))
Registers a listener to get notification when any triggered HTTP request return with a failed response.

Parameters:

marvin.Sketch.addResponseErrorHandler( (message) => {
      console.log(message);
});
marvin.Sketch.removeResponseErrorHandler(function(message))
Unregister a previously appended response error handler.

Parameters:

  • handler - the response error handler to remove
marvin.Sketch.isSupported()boolean
Returns true if HTML5 canvas is supported, false otherwise.

Returns: true if HTML5 canvas is supported, false otherwise.

marvin.Sketch.license(String licenseURL Boolean isDynamic)
Applies a license for the sketcher.

Parameters:

  • licenseURL - the URL of the license file
  • isDynamic - Optional. Controls whether the license is granted by the license server in runtime. The default value is false.

marvin.ImageExporter.molToDataUrl(String source, String imageType, JavaScriptObject optionalSettings)String
Creates image data stream from the given molecule source.

Parameters:

  • source - molecule source in MDL molfile or null to apply an empty molecule
  • imageType - output image data stream MIME type (default value is "image/png").
  • optionalSettings - JavaScript object that describes display settings. The object contains key - value pairs.

    KeyTypeValuesDefault valueNotes
    "carbonLabelVisible"Boolean{true, false}falsedoes not apply in "BALLSTICK" displaymode
    "chiralFlagVisible"Boolean{true, false}true-
    "valenceErrorVisible"Boolean{true, false}true-
    "lonePairsVisible"Boolean{true, false}falseshow lone pairs if MRV source contains proper info or auto lone pair calculation is enabled
    "lonepaircalculationenabled"Boolean{true, false}falseSet it to true to calculate lone pair on the current structure.
    "circledsign"Boolean{true, false}falseDraw circle around positive and negative sign at charge or not.
    "atomIndicesVisible"Boolean{true, false}false-
    "atomMapsVisible"Boolean{true, false}true-
    "cpkColoring"Boolean{true, false}true-
    "displayMode"String{"WIREFRAME", "BALLSTICK", "STICK", "SPACEFILL"}"WIREFRAME"-
    "implicitHydrogen"String{"ALL", "OFF", "HETERO", "TERMINAL_AND_HETERO"}"TERMINAL_AND_HETERO"If "carbonLabelVisible" value is true, "HETERO" and "TERMINAL_AND_HETERO" values will be considered as "ALL".
    "backgroundColor"Stringcss color-do not set this to leave it transparent (png) or white
    "zoomMode"String{"fit", "autoshrink"}"fit""fit" will expand every molecule to the given size, "autoshrink" scales down large molecules only.
    "width"Numberpositive integer200-
    "height"Numberpositive integer200-

    E.g.:
     {
     'carbonLabelVisible' : false,
     'atomMapsVisible' : true,
     'chiralFlagVisible' : true,
     'valenceErrorVisible' : true,
     'lonePairsVisible' : false,
     'implicitHydrogen' : "TERMINAL_AND_HETERO",
     'displayMode' : "WIREFRAME",
     'backgroundColor' : "#ff00ff",
     'width' : 300,
     'height' : 350
     }
     

Returns: image stream encoded as an image data URL if image width/height is greater than zero

marvin.ImageExporter.mrvToDataUrl(String source, String imageType, JavaScriptObject optionalSettings)String
Creates image data stream from the given molecule source.

Parameters:

  • source - molecule source in MRV or null to apply an empty molecule
  • imagType - output image data stream MIME type (default value is "image/png").
  • optionalSettings - JavaScript object that describes display settings. The object contains key - value pairs.

    KeyTypeValuesDefault valueNotes
    "carbonLabelVisible"Boolean{true, false}falsedoes not apply in "BALLSTICK" displaymode
    "chiralFlagVisible"Boolean{true, false}true-
    "valenceErrorVisible"Boolean{true, false}true-
    "lonePairsVisible"Boolean{true, false}falseshow lone pairs if MRV source contains proper info or auto lone pair calculation is enabled
    "lonepaircalculationenabled"Boolean{true, false}falseSet it to true to calculate lone pair on the current structure.
    "circledsign"Boolean{true, false}falseDraw circle around positive and negative sign at charge or not.
    "atomIndicesVisible"Boolean{true, false}false-
    "atomMapsVisible"Boolean{true, false}true-
    "cpkColoring"Boolean{true, false}true-
    "displayMode"String{"WIREFRAME", "BALLSTICK", "STICK", "SPACEFILL"}"WIREFRAME"-
    "implicitHydrogen"String{"ALL", "OFF", "HETERO", "TERMINAL_AND_HETERO"}"TERMINAL_AND_HETERO"If "carbonLabelVisible" value is true, "HETERO" and "TERMINAL_AND_HETERO" values will be considered as "ALL".
    "backgroundColor"Stringcss color-do not set this to leave it transparent (png) or white
    "zoomMode"String{"fit", "autoshrink"}"fit""fit" will expand every molecule to the given size, "autoshrink" scales down large molecules only.
    "width"Numberpositive integer200-
    "height"Numberpositive integer200-

    E.g.:
     {
     "carbonLabelVisible" : false,
     "atomMapsVisible" : true,
     "chiralFlagVisible" : true,
     "valenceErrorVisible" : true,
     "lonePairsVisible" : false,
     "implicitHydrogen" : "TERMINAL_AND_HETERO",
     "displayMode" : "WIREFRAME",
     "backgroundColor" : "#ff00ff",
     "zoomMode" : autoshrink,
     "width" : 300,
     "height" : 350
     }
     

Returns: image stream encoded as an image data URL if image width/height is greater than zero

marvin.Sketch.removeRequestInterceptor(function(config))
Unregisters the previously injected function for completing Marvin JS generated HTTP request headers with extra fields.

Parameters:

  • interceptor - the function to remove.

Classes

marvin.ImageExporter

marvin.ImageExporter(JavaScriptObject params)

Constructor with predefine parameters for the rendering.

Parameters:

  • params - parameters enclosed into a JavaScript Objects.
    imageTypethe format of the generated image (image/png, image/jpeg, image/svg)"image/png"
    settingsdisplay settings. Applies the same values than marvin.ImageExporter.mrvToDataUrl(String,String,JavaScriptObject). { width: 200, height: 200 }
    inputFormatpredefine the format of the molecule source to be converted (or null to auto recognize) (If webservices are not specified, only "mol" and "mrv" are accepted, if it presents any format are accepted that molconverter service supports.)null
    servicesOptinally, you can specify webservice settings to inject molconverter and stereo calculation functionality. See marvin.Sketch.setServices(JavaScriptObject).null

marvin.ImageExporter()

Constructor with default parameters.

render(String source)JavaScriptObject
Generate image from the given molecule source. Returns a Promise object to get a notification when image conversion is ready.

Parameters:

  • source - the source of the molecule to render (the input format is determined by the creation of the ImageExporter instance).

Returns: a Promise object

marvin.Sketch

marvin.Sketch()

Creates a new editor widget and inserts it into the body of the current page.

marvin.Sketch(String id)

Creates a new editor widget and inserts it into the specified DOM element.

Parameters:

  • id - the ID of the DOM element whose child will be the editor widget.
  • config - initial parameters.

getDisplaySettings()JavaScriptObject
Retrieves the current display settings of the editor wrapped into a JavaScript object.

Returns: map of display setting is wrapped into a JavaScript object.

KeyTypeValuesDefault valueNotes
"carbonLabelVisible"Boolean{true, false}falsedoes not apply in "BALLSTICK" displaymode
"chiralFlagVisible"Boolean | String{true, false, "disabled"}true When set to false, the absolute stereo chiral flag is hidden from the canvas. When set to "disabled", the absolute stereo chiral flag is hidden from the canvas and the absolute stereo property cannot be set from the context menu anymore. The visibility of the stereo chiral flag cannot be changed from the View Settings dialog.
"atomIndicesVisible"Boolean{true, false}false-
"atomMapsVisible"Boolean{true, false}true-
"cpkColoring"Boolean{true, false}true-
"valenceErrorVisible"Boolean{true, false}true-
"lonePairsVisible"Boolean{true, false}false-
"displayMode"String{"WIREFRAME", "BALLSTICK", "STICK", "SPACEFILL"}"WIREFRAME"-
"implicitHydrogen"String{"ALL", "OFF", "HETERO", "TERMINAL_AND_HETERO"}"TERMINAL_AND_HETERO"If "carbonLabelVisible" value is true, "HETERO" and "TERMINAL_AND_HETERO" values will be considered as "ALL".
"backgroundColor"Stringcss color-custom non-transparent color
"circledsign"Boolean{true, false}falseDraw circle around positive and negative sign at charge or not.
"fogEffect3D"Boolean{true, false}trueFog effect in 3D mode.
"mdlExportDisabled"Boolean{true, false}falseRemoves the V2000 MDL-related formats (Molfile, Rxnfile, RGfile, RDFile, SDFile) from the export dialog.

E.g.:

 {
  "carbonLabelVisible" : false,
  "atomIndicesVisible" : false,
  "atomMapsVisible" : true,
  "chiralFlagVisible"  : true,
  "valenceErrorVisible"  : true,
  "lonePairsVisible" : false,
  "cpkColoring" : true,
  "implicitHydrogen" : "TERMINAL_AND_HETERO",
  "displayMode" : "WIREFRAME",
  "backgroundColor" : "#ffffff",
  "fogEffect3D" : true,
  "mdlExportDisabled": false
 }
 

setDisplaySettings(JavaScriptObject jso)
Applies a map of settings for the editor. Check the return value of the getDisplaySettings() function to look up the full display settings map.

Parameters:

  • jso - map of display setting is wrapped into a JavaScript object.

    KeyTypeValuesDefault valueNotes
    "carbonLabelVisible"Boolean{true, false}falsedoes not apply in "BALLSTICK" displaymode
    "chiralFlagVisible"Boolean | String{true, false, "disabled"}true When set to false, the absolute stereo chiral flag is hidden from the canvas. When set to "disabled", the absolute stereo chiral flag is hidden from the canvas and the absolute stereo property cannot be set from the context menu anymore. The visibility of the stereo chiral flag cannot be changed from the View Settings dialog.
    "atomIndicesVisible"Boolean{true, false}false-
    "atomMapsVisible"Boolean{true, false}true-
    "cpkColoring"Boolean{true, false}true-
    "valenceErrorVisible"Boolean{true, false}true-
    "lonePairsVisible"Boolean{true, false}false-
    "displayMode"String{"WIREFRAME", "BALLSTICK", "STICK", "SPACEFILL"}"WIREFRAME"-
    "implicitHydrogen"String{"ALL", "OFF", "HETERO", "TERMINAL_AND_HETERO"}"TERMINAL_AND_HETERO"If "carbonLabelVisible" value is true, "HETERO" and "TERMINAL_AND_HETERO" values will be considered as "ALL".
    "backgroundColor"Stringcss color--
    "defaultTool"String{"rectangleSelection", "lassoSelection", "rotate3d"}"rectangleSelection"set default tool
    "toolbars"String{"standard", "education", "reaction", "markush", "search", "basicSearch", "reporting", "view3d", "ws_view3d", "searchWithReaxys"}"standard"to render toolbars by the given predefined layout
    "copyasmrv"Boolean{true, false}falseTo prefer MRV instead of MDL molfile format at copy
    "lonepaircalculationenabled"Boolean{true, false}trueEnable automatic lone pair calculation
    "circledsign"Boolean{true, false}falseDraw circle around positive and negative sign at charge or not.
    "fogEffect3D"Boolean{true, false}trueFog effect in 3D mode.
    "disableContextMenu"Boolean{true, false}falseSet true to disable the context menu
    "multiplesgroup"Boolean{true, false}trueThe property specifies how the repeating groups with exact repetition numbers are represented in the generated molecule source. If the value is set true, these are represented as multiple groups; if the value is false, these are represented as repeating units. The setting affects the generated molecule source in the Export dialog, and the sources placed on the clipboard in MRV and Mol formats. It may influence the result of a web service call (triggered by web service based actions like Clean 2D).
    "mdlExportDisabled"Boolean{true, false}falseRemoves the V2000 MDL-related formats (Molfile, Rxnfile, RGfile, RDFile, SDFile) from the export dialog.

    E.g.:
     {
      "carbonLabelVisible" : false,
      "atomIndicesVisible" : false,
      "atomMapsVisible" : true,
      "chiralFlagVisible"  : true,
      "valenceErrorVisible"  : true,
      "lonePairsVisible" : false,
      "cpkColoring" : true,
      "implicitHydrogen" : "TERMINAL_AND_HETERO",
      "displayMode" : "WIREFRAME",
      "backgroundColor" : "#ffffff",
      "defaultTool" : "lassoSelection",
      "toolbars" : "standard",
      "fogEffect3D" : false,
      "mdlExportDisabled": true
     }
     

clear()
Remove the canvas content.
isEmpty()boolean
Determines whether the canvas is empty or not.

Returns: True if nothing on the canvas, else false.

pasteStructure(String format, String source, options)JavaScriptObject
Returns a Promise object to paste a molecule source. If the paste operation is successful, the new structure will be added to the old one at the center of the current viewport. See also: importStructure(String,String).

Parameters:

  • format - the input format getSupportedFormats() or null to recognize the format automatically.
  • source - the molecule source

Returns: the Promise object

getSupportedFormats()JavaScriptObject
Returns an object which describes the available import and export formats with the following properties: "importFormats", "exportFormats". The number of the available formats depend on whether the default webservices are set or not.

Returns: the JavaScript object.

setServices(JavaScriptObject jso)
Sets up services for the editor. See the webservices.js for the list of supported services.

Parameters:

  • jso - map of services wrapped into a JavaScript object. The property names correspond to the supported web services. The property values can either be a single string, representing the URL, or an other JavaScript object, containing the URL and the protocol name of the web service. If the protocol is not specified, its value is set to "default".
     {
     "clean2dws" : <url of Clean2D webservice>
     "clean3dws" : <url of Clean3D webservice>
     "molconvertws" : <url of MolConvert webservice>
     "stereoinfows" : <url of CIP Stereo Info webservice>
     "reactionconvertws" : <url of Reaction converter webservice>
     "hydrogenizews" : <url of hydrogenize webservice>
     "automapperws" : <url of auto mapper webservice>
     "aromatizews" : {
      "url" : <url of aromatize webservice>
      "protocol" : <protocol of aromatize webservice>
      }
     }
     
addButton(JavaScriptObject jso, function())
Appends a new button to the specified toolbar and binds its onClick event with the given function.

Parameters:

  • jso - attributes of button is wrapped into a JavaScript object. E.g.:
     {
      "name": "customButton", // JS String
      "image-url": "images/custom-button.png" // JS String
      "toolbar": "W" // JS String: "W" as West, "E" as East, "N" as North, "S" as South toolbar
     }
     

addTemplate(JavaScriptObject jso)
Append a new button to the template toolbar with the specified template structure.

Parameters:

  • jso - a JavaScript object that describes the template. It has to contains the following properties:
    NameTypeDescription
    structureStringMRV source of the template structure
    nameStringtitle of the template button (optional, auto generated)
    iconString24x24 pixel size icon for the button as base64 encoded data image (optional, auto generated)
    E.g.:
    {
     "structure": "<cml><MDocument><MChemicalStruct><molecule molID=\"m1\"><atomArray><atom id=\"a1\" elementType=\"C\" x2=\"-12.5625\" y2=\"6.539048685882614\"/><atom id=\"a2\" elementType=\"C\" x2=\"-13.808366329017026\" y2=\"5.633832087370612\"/><atom id=\"a3\" elementType=\"C\" x2=\"-13.332503911629807\" y2=\"4.169284647450719\"/><atom id=\"a4\" elementType=\"C\" x2=\"-11.792496088370193\" y2=\"4.169284647450719\"/><atom id=\"a5\" elementType=\"C\" x2=\"-11.316633670982972\" y2=\"5.633832087370612\"/></atomArray><bondArray><bond atomRefs2=\"a1 a2\" order=\"1\"/><bond atomRefs2=\"a1 a5\" order=\"1\"/><bond atomRefs2=\"a2 a3\" order=\"1\"/><bond atomRefs2=\"a3 a4\" order=\"1\"/><bond atomRefs2=\"a4 a5\" order=\"1\"/></bondArray></molecule></MChemicalStruct></MDocument></cml>",
     "name": "CycloPentane",
     "icon": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAABBElEQVRIie3UK08DQRiF4UdW1q4CfgISW7kSRYIrihBEJQkKi0OiCKJQSVAEtRJD0CgkqYGAIhjEzCYFlr1Mi+ubfMlezpyZPd/ssGTBHOPwP4z7uME9HnCNbFHmG3jCSbzv4TQ+G8xrfoBX5BXvcjziKMV4DQXu4nWT7rZB940tTDFqqe9F7RTbTeJLIdv1tquZYRDHXtSt5B0rCeYlq3iLXpWcYW+OCXajx5/kQtNSKTRs3Z7QrH6CeYZnNfGUTKTF1BhPyaZwLHSlUP1D/iIlpgwfWsRTMsFOhwmGuOqg7xxTIfSgNX28YF/4kp81nKkRPiXsvHOMhZ1RV2M1x8OSRr4A1pQ2FuhcylgAAAAASUVORK5CYII="
     }

getSelection()JavaScriptObject
Returns the indexes of the selected atoms and bonds. Atoms are indexed from 1.

Returns: JavaScript object with indices of selected atoms and bonds. E.g.:

 {
   "atoms" : "1,2,3",
   "bonds" : "1-2,2-3"
 }
 

setSelection(JavaScriptObject jso)
Selects bonds and atoms of the specified indices (assuming the indices start from 1). Bonds are identified by their atoms' indices (separate indices with '-').

Parameters:

  • selection - JavaScript object that describes atoms and bonds to select. E.g.:
     {
       "atoms" : "1,2,3",
       "bonds" : "1-2,2-3"
     }
     

setHighlight(JavaScriptObject[] jsoArray)
Overwrites the highlight definitions in the editor. You can specify multiple definitions if you would like to use various highlight style in the same time. The definition should contains information about the style (color, opacity, size) and the scope (which atoms/bonds should be painted with this style). You can specify atoms and bonds to highlight by unique ID (UID) or by atom indeces. If an atom or bond is given in several definitions, each patch is applied for the desired atom/bond. So the patch may overlap each other.

Parameters:

  • jsoArray - array of JavaScriptObject that describes highlight in the following format:
    {
       // give uids or indexes field (depend on how you would like to specify atoms/bonds to highlight)
       uids: {
         // string array with UIDs of atom
         atoms: [],
         // string array with UIDs of bond
         bonds: []
       },
       indexes: {
         // string array of indeces of atom
         atoms: [],
         // string array of pair of atom indeces to describe bond
         bonds: []
       },
       style: {
         // CSS color (rgb, rgba, hsl, hsla, hexa or web-safe color name)
         color: <string>,
         // value between 0.0 and 1.0 (default value is 1.0), if color has alpha value (rgb, rgba) this field is ignored.
         opacity: <number>
          // size of the patch that is relative to the selection patch, 1.0 means the same patch than the selection.
         size: <double>
       }
     }
    In the following example, there are two definitions, at the first one atoms and bonds are specified by UIDs, at the second atom indeces are used. In the first case, color contains alpha value, so the opacity property is needless in this case. At the second case, the pink color is defined and specified the desired opacity explicitly.
    sketch.setHighlight( [
       {
         uids: { atoms: ["e2ff0039baee12e2", "be3f1024c1f5e3f1"], bonds: ["3e1a21c74df9ae81"] },
         style: { color: "rgba(20,230,50, 0.5)", size: 0.8 }
       },
       {
         indexes: { atoms: ["1","2","3"], bonds: ["1-2","1-3"] },
         style: { color: "pink", opacity: 0.6, size: 0.8 }
       }
     ] );

addMolImportListener(function(String))
Registers a listener to mol import events. The event is triggered when a molecule source is loaded via the user interface (Open dialog, paste or Drag&drop action).

Parameter:

  • callback - this function is performed after the event happened. The molecule source is passed to the function as a string parameter.

removeMolImportListener(function(String))
Unregisters one or more event handlers for the mol import event.

Parameter:

  • callback - the reference of a previously attached event handler function to remove. At null value, all event handlers are removed.

on(String eventType, function())
Attaches an event handler function for the specified event to the editor. Supported events:
  • "molchange": molecule change events
  • "selectionchange": selection change events
  • "undo": events when undo is performed
  • "redo": events when redo is performed

Parameters:

  • type - the event type ("molchange" or "selectionchange")
  • callback - this function is performed after the specified event is invoked.

off(String eventType, function())
Removes one or more event handlers for the specified event to the editor.

Parameters:

  • type - the event type (accept same types as on(String,function()))
  • callback - the reference of a previously attached event handler function to remove or null to remove all event handlers for the specified event.

exportStructure(String format, JavaScriptObject optionsJso)JavaScriptObject
Returns a Promise object to access the molecule source.

Parameters:

  • format - the output molecule format getSupportedFormats().
  • options - a JavaScript object that describes further options for export (optional).
    • -- png or jpeg: same as optionalSettings parameter of marvin.ImageExporter.mrvToDataUrl(String,String,JavaScriptObject)
    • -- any chemical format:
      • extra:It force conversion with web services and assigns the value of this property as a parameter of the output format. E.g., exportStructure('mrv', { 'extra': '+H'}) will appear in the web service request as { 'parameters': 'mrv:+H', ...}. Please consult with the web service documentation which options are accepted by the web service.
      • multiplesgroup: It specifies how to represent S-groups when the repetition is an exact number in the generated molecule source. If the value is false, they are represented as SRU S-group.
    • -- mrv: Accept only hasUID property. If it is true, export atom/bond UIDs as atom/bond properties (_mjs::uid). Its default value is false.

Returns: the Promise object

importStructure(String format, String source, options)JavaScriptObject
Returns a Promise object to import a molecule source. If the import operation is successful, the old structure will be replaced by the new one. See also: pasteStructure(String,String).

Parameters:

  • format - the input format getSupportedFormats() or null to recognize the format automatically.
  • source - the molecule source

Returns: the Promise object

setAutoChirality(boolean enable)
Setup auto chirality mode. When you activate it, setup chiral flag on current structure and force it on every imported structure later.

Parameters:

  • enable - true to activate this feature, false to deactivate it (default behaviour).