Marvin JS Example - Structure Checker (using JChem Web Services Classic)

Structure Checker configuration

Structure Errors

Code comments

This example requires molchange.js that defines MolChangeHandler class to aggregate molecule change events.

First of all, Structure Checkers checks which services are available. It provides a Promise to notify when the list of the available services arrived (or notify if services are unreachable).

After that, the following steps will be executed:

• With the add function of the Checkers object, selected structure checkers are initialized.
• Retrieves the reference for the sketcher that runs in the iframe and runs the onSketchLoaded function.

$(document).ready(function handleDocumentReady (e) {
	var config = [
		{id: "BondLengthChecker", color: "#ffe211", title: "Bond length"},
		{id: "BondAngleChecker", color: "#ef6671", title: "Bond angle"},
		{id: "AtomMapChecker", color: "#d26ff1", title: "Atom map"}
	];
	CheckersWS.then(function(services) {
		for(var i = 0; i < config.length; i++) {
			if($.inArray(config[i].id, services)) {
				Checkers.add(config[i].id, config[i].color, config[i].title);
			}
		}
		MarvinJSUtil.getEditor("#sketch").then(onSketchLoaded, function () {
			alert("Cannot retrieve sketcher instance from iframe");
		});
	}, function(error) {
		$('#checkers-panel-result').html('structure checker is not available');
	});
});
});

The onSketchLoaded function instantiates a MolChangeHandler. Its first parameter is the reference of the editor to which it listens. The second one is a callback function that is performed at each mol change event.

function onSketchLoaded(sketcherInstance) {
	marvinSketcherInstance = sketcherInstance;
	// aggregator for molecule change events
	new MolChangeHandler(sketcherInstance, onMolChange);
}

If you take a look at the add function of Checkers, you can see that it creates a CheckerWidget object for each checker.

	/** Appends a new checker to the document.
	* @param id - the name of the checker as referred in JChem WS (see JChem WS documentation)
	* @param color - colorizes the result (atoms/bonds) in the editor with this color
	* @param title - the short description of the checker that displays in the config panel below.
	*/
	function add(id, color, title) {
		var widget = new CheckerWidget(id, color, title);
		$("#checkers-panel-config").append(widget.asWidget());
		widgets.push(widget);
	}

Returning to the onMolChange function, you can see that it resets the current highlight on the sketcher, gets the source of the current structure and performs a structure check on it.

function reset() {
	// reset current highlight
	marvinSketcherInstance.setHighlight({});
	$('#checkers-panel-result').empty();
}

var last = null;

function onMolChange(e) {
	last = e;
	reset();
	e.target.exportStructure("mrv").then(function(source) {
		if(!e.isDeprecated) { // unless a newer molchange event deprecate this event
			e.source = source;
			Checkers.check(source);
		}
	},alert);
}

If you take a closer look at the Checkers.check function, you can see those CheckerWidgets are enabled where the checkboxes were previously checked. It creates the input for the Structure Checker web service. Finally, it calls the send method with the created object.

	/**
	* Performs the structure checking on the given molecule source.
	* @param source - the molecule source in MRV format.
	*/
	function check(source) {
		var json = {};
		json.structure = source;
		json.parameters = {};
		json.parameters.checkers = [];
		for(var i = 0; i < widgets.length; i++) {
			var widget = widgets[i];
			if(widget.isEnabled()) {
				json.parameters.checkers.push({"checkerId": widget.getId() });
			}
		}
		if(json.parameters.checkers.length == 0) {
			return;
		}
		send(json);
	}

The send invokes the web service, then call onSuccess function when the response of web service is received or onFail if any error occured.

	/* Sends an async request to Structure checker web service. */
	function send(json) {
		// arrange the input for the Structure Checker web service
		$.ajax({
			"url": "/webservices2/rest-v0/util/calculate/structureChecker"
			,"type": "POST"
			,"dataType": "json"
			,"contentType": "application/json"
			,"data": JSON.stringify(json)
		}).done(function (data, textStatus, jqXHR) {
			onSuccess(data);
		}).fail(onFail);
	}

The onSuccess function gets the response of the web service as a parameter (data). Its header field contains the id of the performed checkers. Each checker result can be referred with its own id. E.g. data.bondlength describes the result of bondlength checker. A checker result can contain many fields but only the following one are relevant in this case:

• checkerName: the title of the checker
• description: the error message
• errors: a complex object that also describes which atoms and bonds are affected.

The checkerName and the decription is displayed on the current page in the checkers-panel-result div. Meanwhile the affected atoms and bonds are highlighted in the sketcher.

/* Callback to process web service result. */
	function onSuccess(data) {
		var highlights = [];
		if(typeof data.headers == 'object') {
			for(checkerId in data.headers) {
				if(data.headers.hasOwnProperty(checkerId) && isCheckerResult(data[checkerId])) {
					var widget = getWidget(checkerId);
					if(widget) {
						// display error message
						var message = "("+data[checkerId].checkerName+"): "+data[checkerId].description;
						$('#checkers-panel-result').append(widget.createErrorWidget(message));
						// calculate context to highlight
						if(typeof data[checkerId].errors == 'object') {
							var indexes = {};
							indexes.atoms = getAtoms(data[checkerId].errors.atoms);
							indexes.bonds = getBonds(data[checkerId].errors.bonds);
							if(indexes.atoms.length || indexes.bonds.length) { // add highlight unless context is empty
								highlights.push({
									'style': {
										'color': widget.getColor(),
										'opacity': 0.25
									},
									'indexes': indexes
								});
							}
						}
					}
				}
			}
		}
		// highlight atoms and bonds
		marvinSketcherInstance.setHighlight(highlights);
	}

Changing of the configuration (check/uncheck checkbox or modify checker color) also triggers the checking of the structure (whose source was already stored in the source property of the last molchange event).

function onConfigChange(e) {
	// reevaluate last consumed molchange event when congfiguration is changed
	if(last && !last.isDeprecated && (typeof last.source == 'string')) {
		reset();
		Checkers.check(last.source);
	}
}