Tutorial > Sketcher Canvas

The 2D Sketcher works in all browsers, including IE11+, Edge, Safari, Opera, Chrome and Firefox, as well as Mobile Safari and Chrome for Android.

The SketcherCanvas component is a complete and full-featured chemical sketcher. It is built from the ChemDoodle desktop application and optimized for both desktop browsers and mobile devices. There is also a Single Molecule Sketcher option, to optimize the sketcher for drawing only a single molecule, which is very convenient for a number of applications. This is the most professional web based sketcher available, as expected from the universal chemical drawing standard, and it is free and open source under the GPL license!

This page is more complex than others to cover the functionality of the sketcher. It is comprised of the following sections:

1. Installation
2. Initializing the Sketcher
3. Options
4. Additional Setup
5. Single Molecule Sketcher
6. Query Sketcher
7. Mobile Support
8. iChemLabs Cloud Services
9. Input/Output of Complex Content
10. Listening to User Changes
11. User Guide

Installation

To simplify the ChemDoodle Web Components library, the SketcherCanvas component is provided as a plugin with other components needing a more advanced user interface. In order to use the SketcherCanvas class, you need to link a few additional files as URI resources on your webpage that are provided in the uis folder of the ChemDoodle Web Components download:

<!--these two are required by the ChemDoodle Web Components library-->
<link rel="stylesheet" href="[path]/ChemDoodleWeb.css" type="text/css">
<script type="text/javascript" src="[path]/ChemDoodleWeb.js"></script>
<!--these two are required by the SketcherCanvas plugin-->
<link rel="stylesheet" href="[path]/jquery-ui-1.11.4.custom.css" type="text/css">
<script type="text/javascript" src="[path]/ChemDoodleWeb-uis.js"></script>

The SketcherCanvas class is provided in the ChemDoodleWeb-uis.js file. This plugin requires one library, jQuery UI, that powers the interface elements of the sketcher. jQuery UI requires the CSS file provided and the JavaScript library is included in the ChemDoodle scope through the ChemDoodleWeb-uis.js file.

jQuery UI Image Folder

In addition to the three additional URI resources required by the sketcher, there is one folder of images provided in the uis folder of the download. This folder is called images and contains the corresponding images for the jQuery UI CSS file. This folder should be placed in the same folder that the jQuery UI CSS file is placed on your server.

Sketcher Toolbar Icons

The icons for the sketcher are embedded directly in the ChemDoodleWeb-uis.js file source itself as data URIs, so there is no need to host those images. Please note that the ChemDoodleWeb-uis.js icons (that you see in the toolbars) are iChemLabs Proprietary and may only be used in projects using ChemDoodle Web Components.

Initializing the Sketcher

The SketcherCanvas class is a child of the Canvas class, so working with it is the same as with working with any other Canvas in the ChemDoodle Web Components library. To initialize it, we just call its constructor, which places it into the HTML page:

new ChemDoodle.SketcherCanvas(name, width, height, options);

The parameters are defined as follows:

• name - is the id of the <canvas> component in the HTML page.
• width - defines the width of the SketcherCanvas in pixels.
• height - defines the height of the SketcherCanvas in pixels.
• options - is an object that contains the option name/value pairs, as covered in the next section.

Options

The options object is just a generic object that contains names and values for options. It is created in the following way:

<script>
  let obj = {option1:value1, option2:value2};
</script>

You can include the right side of the assignment directly in the SketcherCanvas constructor.

The following options are controllable:

• floatDrawTools - is a boolean and is false by default. Set this to true to use a floating toolbar for the drawing tools (the bottom row of buttons), similar to the desktop software.
• includeQuery - is a boolean and is false by default. Set this to true to include the query tools in the sketcher instance.
• includeToolbar - is a boolean and is true by default. Set this to false to remove the toolbar, such as when creating your own interface to the SketcherCanvas <canvas> (such as in a mobile app).
• isMobile - is a boolean and optimizes the SketcherCanvas for use on mobile devices; if not declared, this option will automatically default to the appropriate value by checking the ChemDoodle.featureDetection.supports_touch() function; only set this if you are forcing behavior (for debugging for instance).
• oneMolecule - is a boolean and if true, optimizes the SketcherCanvas to sketch only a single molecule; by default, it is false and the Full Sketcher is used, such as the one at the top of this page; the Single Molecule Sketcher is covered below.
• requireStartingAtom - is a boolean and is true by default. Atoms are required to for sprouting any chemical structures by default in ChemDoodle brand sketchers. We find this is easier for students when learning how to use chemical drawing tools. Advanced users may not need this, so set this boolean to false to allow for faster drawing without starting atom requirements.
• resizable - is a boolean and is false by default. Set this to true and the sketcher canvas will be resizable via a hotspot in the bottom-right corner and through its right and bottom borders.
• useServices - is a boolean and should be true if you are registered with us to use iChemLabs cloud services to power popular sketcher features. If you do not want to use iChemLabs cloud services, then set this parameter to false, and any features that use iChemLabs cloud services will be removed from the sketcher interface. If you are an academic organization, we will provide free access to our services. Otherwise, our rates are very reasonable, please contact us for options. By default this is false.

Additional Setup

In addition to just calling the constructor, you may wish to also set the following common sketcher options, which will change the graphics to improve the user experience. The following code is the exact code used to initialize the SketcherCanvas at the top of this page:

<script>
  // changes the default JMol color of hydrogen to black so it appears on white backgrounds
  ChemDoodle.ELEMENT['H'].jmolColor = 'black';
  // darkens the default JMol color of sulfur so it appears on white backgrounds
  ChemDoodle.ELEMENT['S'].jmolColor = '#B9A130';
  // initializes the SketcherCanvas
  let sketcher = new ChemDoodle.SketcherCanvas('sketcher', 500, 300, {useServices:true, oneMolecule:false});
  // sets terminal carbon labels to display
  sketcher.styles.atoms_displayTerminalCarbonLabels_2D = true;
  // sets atom labels to be colored by JMol colors, which are easy to recognize
  sketcher.styles.atoms_useJMOLColors = true;
  // enables overlap clear widths, so that some depth is introduced to overlapping bonds
  sketcher.styles.bonds_clearOverlaps_2D = true;
  // sets the shape color to improve contrast when drawing figures
  sketcher.styles.shapes_color = 'c10000';
  // because we do not load any content, we need to repaint the sketcher, otherwise we would just see an empty area with the toolbar
  // however, you can instead use one of the Canvas.load... functions to pre-populate the canvas with content, then you don't need to call repaint
  sketcher.repaint();
</script>

We do not preload a Molecule into the sketcher, although we can if we want to using the Canvas.loadMolecule() function, just like we would with any other Canvas. Because we do not call this function, we have to call the Canvas.repaint() function instead to update the drawing after changing the settings.

Single Molecule Sketcher

The Full Sketcher, which is the one initialized on the top of this page, allows a user to draw complex figures, involving many molecules and shapes. However, in many cases, the required input will be just a single molecule. For instance, you may just want to look up a molecule in a database, or calculate the properties of a single structure. The ChemDoodle Web Sketcher was developed with this in mind and setting the oneMolecule option to true for the SketcherCanvas constructor will optimize the instance for drawing a single molecule as shown here.

<script>
  // ...
  let sketcher = new ChemDoodle.SketcherCanvas('sketcher', 500, 300, {useServices:true, oneMolecule:true});
  // ...
</script>

You will notice that the toolbar for the Single Molecule Sketcher is different than the toolbar for the Full Sketcher. This is to simplify the interface and make it quick to draw a single molecule. You will also notice that there is a little circle in the middle of the sketcher. This is a carbon atom and defines the start of a structure; the entire ChemDoodle family of sketchers works in this fashion. By always forcing at least a carbon atom, you can be sure that any call to the getMolecule() function will always return a valid molecule from the Single Molecule Sketcher.

Query Sketcher

Query features and the Query Sketcher are covered on their own page.

Mobile Support

While the sketcher is modeled after the popular ChemDoodle desktop application, we have also spent a lot of time and effort optimizing the sketcher for mobile use. In mobile browsers, there is no such thing as a hover event, so the SketcherCanvas class makes some changes to allow users to draw molecules by touching the screen. The SketcherCanvas class also implements gesture events that allow for much more complex functionality. This includes the pinch gesture, which will scale the content and the twist gesture, which will rotate the content.

Of course, everything works intuitively and is easy to learn. Just go to this page on your iPad, iPhone or Android device to test the sketcher above for mobile interfaces.

iChemLabs Cloud Services

The ChemDoodle Web Components library has full access to the entire ChemDoodle API through AJAX. Therefore, any and all functionality provided in the desktop version of ChemDoodle is instantly accessible through this library. Some of the functions in the sketcher take advantage of this, such as the clean function. If you have any requests for specific functionality that is not currently provided, please view our support options.

In order to use iChemLabs cloud services, your origins (domains) must be recognized by our servers. If you are an academic organization, we will provide free access to our server resources. Otherwise, our rates are very reasonable, please contact us for options and begin accessing the ChemDoodle API today!

In addition to accessing our servers, our customers get priority feature requests, priority support and access to our development builds. Don't miss this chance to take advantage of the universal chemical drawing standard. Contact us today.

Input/Output of Complex Content

To handle the input and output of complex content, you should use the native ChemDoodle JSON format. This format is covered in detail here.

Listening to User Changes

This sketcher allows your users to describe and submit chemical information to your systems. But there may be times where you need to provide your users with immediate feedback as they are drawing their figures. This tutorial describes how to achieve this functionality.

User Guide

For user instructions to draw structures and figures with the ChemDoodle Web Sketcher, please see the Sketcher demo.