Tutorial > Initializing Canvases

All canvases can be initialized by following three general steps:

1. Construction
2. Load Data
3. Specify Settings

1. Construction

All canvases in the ChemDoodle Web Components library are children of the abstract Canvas class. Abstract means that the class is not instantiable and should never be called, its children should be used instead. Let's briefly go over the class hierarchy for Canvas. Classes in red are abstract. This is only a brief overview, the instantiable canvases are individually covered in the following links.

• Canvas - parent class for all canvases, provides generic functionality for displaying chemical data.
  • ViewerCanvas - simply displays an image of a molecule.
  • HyperlinkCanvas - displays an image of a molecule and provides "button" functionality for users.
  • TransformCanvas - displays an interactive molecule that can be rotated, translated and scaled.
  • MolGrabberCanvas - a more complex canvas that has an associated search field for accessing databases.
  • SketcherCanvas - a full-featured chemical sketcher.
  • AnimatorCanvas - parent class for all canvases that show animations; provides a framework for high-quality animations.
    • RotatorCanvas - shows a rotating animation of a molecule.
    • SlideshowCanvas - shows any number of molecules, one at a time, with animated transitions in between.
  • Canvas3D - parent class for all canvases that render 3D graphics using WebGL.
    • ViewerCanvas3D - simply displays a 3D rendering of a molecule.
    • RotatorCanvas3D - shows a rotating animation of a 3D rendering of a molecule.
    • TransformCanvas3D - displays an interactive 3D rendering of a molecule that can be rotated, translated and scaled.
    • MolGrabberCanvas3D - a more complex canvas that has an associated search field for accessing databases. Works like the TransformCanvas3D.
    • MovieCanvas3D - a component to display, animate and interact with molecular movies.
    • EditorCanvas3D - a complete interface for interacting with 3D data.
  • SpectrumCanvas - parent class for all canvases that render spectra.
    • ObserverCanvas - simply displays an image of a spectrum.
    • OverlayCanvas - displays several spectra overlaid on the same domain.
    • PerspectiveCanvas - displays an interactive spectrum where a user can zoom in and scale peaks.
    • SeekerCanvas - provides interactive tools for investigating spectrum coordinates.

For this example, we will be initializing the simplest Canvas, the ViewerCanvas. The ViewerCanvas constructor is the most basic and takes only 3 parameters: id, width and height in that order. The id is a string corresponding to the id of the <canvas> element that is used to generate the component. The constructor will automatically create the <canvas> tag in your HTML page with the name and dimensions you give it.

Finally, all canvas classes are accessed at the top level of the ChemDoodle variable. The ViewerCanvas is initialized by the following code:

<script>
    let myCanvas = new ChemDoodle.ViewerCanvas('id', 150, 150);
    myCanvas.emptyMessage = 'No Data Loaded!';
    myCanvas.repaint();
</script>

You should see the empty ViewerCanvas displayed above. Note that we set a variable for the canvas called emptyMessage. When emptyMessage is set to a non-undefined string, the canvas will render that message if no data is loaded. We will just add that for debugging purposes and to show something in this example. Lastly, we called the Canvas.repaint() function at the end, this function redraws the canvas on the page and is very useful when you want the Canvas to change after updating it.

As an optional note, notice that there is a 1 pixel thick, black border around the component. This is defined in the ChemDoodleWeb.css file that you installed on your website. Because all ChemDoodle Web Components are just HTML objects, their styles can be controlled by CSS. You may change this border, remove it, or add other styling by changing that file.

2. Load Data

Now that we have created our component, we can load data into it. The Canvas.loadMolecule() function takes a Molecule object that is derived from any of the methods described on the previous page (The SpectrumCanvas class has an analogous loadSpectrum() function). The Canvas.loadMolecule() function will then set the molecule, center it, scale it (if necessary to fit), and finish with the necessary cheminformatics algorithms (such as finding rings, etc.). This function also automatically repaints the canvas, so there is no need to use the Canvas.repaint() function at this time, so we will remove it. Our script from above should now be changed to look like this:

<script>
    let myCanvas = new ChemDoodle.ViewerCanvas('id', 150, 150);
    myCanvas.emptyMessage = 'No Data Loaded!';
    let caffeineMolFile =
        'Molecule Name\n  CHEMDOOD08070920033D 0   0.00000     0.00000     0\n[Insert Comment Here]\n 14 15  0  0  0  0  0  0  0  0  1 V2000\n   -0.3318    2.0000    0.0000   O 0  0  0  1  0  0  0  0  0  0  0  0\n   -0.3318    1.0000    0.0000   C 0  0  0  1  0  0  0  0  0  0  0  0\n   -1.1980    0.5000    0.0000   N 0  0  0  1  0  0  0  0  0  0  0  0\n    0.5342    0.5000    0.0000   C 0  0  0  1  0  0  0  0  0  0  0  0\n   -1.1980   -0.5000    0.0000   C 0  0  0  1  0  0  0  0  0  0  0  0\n   -2.0640    1.0000    0.0000   C 0  0  0  4  0  0  0  0  0  0  0  0\n    1.4804    0.8047    0.0000   N 0  0  0  1  0  0  0  0  0  0  0  0\n    0.5342   -0.5000    0.0000   C 0  0  0  1  0  0  0  0  0  0  0  0\n   -2.0640   -1.0000    0.0000   O 0  0  0  1  0  0  0  0  0  0  0  0\n   -0.3318   -1.0000    0.0000   N 0  0  0  1  0  0  0  0  0  0  0  0\n    2.0640   -0.0000    0.0000   C 0  0  0  2  0  0  0  0  0  0  0  0\n    1.7910    1.7553    0.0000   C 0  0  0  4  0  0  0  0  0  0  0  0\n    1.4804   -0.8047    0.0000   N 0  0  0  1  0  0  0  0  0  0  0  0\n   -0.3318   -2.0000    0.0000   C 0  0  0  4  0  0  0  0  0  0  0  0\n  1  2  2  0  0  0  0\n  3  2  1  0  0  0  0\n  4  2  1  0  0  0  0\n  3  5  1  0  0  0  0\n  3  6  1  0  0  0  0\n  7  4  1  0  0  0  0\n  4  8  2  0  0  0  0\n  9  5  2  0  0  0  0\n 10  5  1  0  0  0  0\n 10  8  1  0  0  0  0\n  7 11  1  0  0  0  0\n  7 12  1  0  0  0  0\n 13  8  1  0  0  0  0\n 13 11  2  0  0  0  0\n 10 14  1  0  0  0  0\nM  END\n> <DATE>\n07-08-2009\n';
    let caffeine = ChemDoodle.readMOL(caffeineMolFile);
    myCanvas.loadMolecule(caffeine);
</script>

You should now see caffeine drawn in the canvas. We used the print method from the previous page to define the data for caffeine from a MDL MOLFile. Notice that we kept the emptyMessage variable set, but the message is no longer displayed because data has been loaded.

3. Specify Settings

We have now created a component and rendered a molecule in it. This is the default style of the rendering. For your own website, you may wish to customize how the molecule appears. Every last detail of how graphics are rendered in the ChemDoodle Web Components library is customizable. These graphics are affected by defining settings for the Canvas.styles object, and in ChemDoodle products are called styles.

To illustrate this point, we will conform the rendering of caffeine to ACS Document 1996 style. We will also render element labels with JMol colors for a little pizzaz. Complete information on all styles is provided in the API for the Styles object. Our script should now be updated to define the Canvas.styles options before we load the molecule (lines that begin with "//" are comments and will be ignored in JavaScript):

<script>
    let myCanvas = new ChemDoodle.ViewerCanvas('id', 150, 150);
    //the width of the bonds should be .6 pixels
    myCanvas.styles.bonds_width_2D = .6;
    //the spacing between higher order bond lines should be 18% of the length of the bond
    myCanvas.styles.bonds_saturationWidthAbs_2D = 2.6;
    //the hashed wedge spacing should be 2.5 pixels
    myCanvas.styles.bonds_hashSpacing_2D = 2.5;
    //the atom label font size should be 10
    myCanvas.styles.atoms_font_size_2D = 10;
    //we define a cascade of acceptable font families
    //if Helvetica is not found, Arial will be used
    myCanvas.styles.atoms_font_families_2D = ['Helvetica', 'Arial', 'sans-serif'];
    //display carbons labels if they are terminal
    myCanvas.styles.atoms_displayTerminalCarbonLabels_2D = true;
    //add some color by using JMol colors for elements
    myCanvas.styles.atoms_useJMOLColors = true;
    myCanvas.emptyMessage = 'No Data Loaded!';
    let caffeineMolFile =
        'Molecule Name\n  CHEMDOOD08070920033D 0   0.00000     0.00000     0\n[Insert Comment Here]\n 14 15  0  0  0  0  0  0  0  0  1 V2000\n   -0.3318    2.0000    0.0000   O 0  0  0  1  0  0  0  0  0  0  0  0\n   -0.3318    1.0000    0.0000   C 0  0  0  1  0  0  0  0  0  0  0  0\n   -1.1980    0.5000    0.0000   N 0  0  0  1  0  0  0  0  0  0  0  0\n    0.5342    0.5000    0.0000   C 0  0  0  1  0  0  0  0  0  0  0  0\n   -1.1980   -0.5000    0.0000   C 0  0  0  1  0  0  0  0  0  0  0  0\n   -2.0640    1.0000    0.0000   C 0  0  0  4  0  0  0  0  0  0  0  0\n    1.4804    0.8047    0.0000   N 0  0  0  1  0  0  0  0  0  0  0  0\n    0.5342   -0.5000    0.0000   C 0  0  0  1  0  0  0  0  0  0  0  0\n   -2.0640   -1.0000    0.0000   O 0  0  0  1  0  0  0  0  0  0  0  0\n   -0.3318   -1.0000    0.0000   N 0  0  0  1  0  0  0  0  0  0  0  0\n    2.0640   -0.0000    0.0000   C 0  0  0  2  0  0  0  0  0  0  0  0\n    1.7910    1.7553    0.0000   C 0  0  0  4  0  0  0  0  0  0  0  0\n    1.4804   -0.8047    0.0000   N 0  0  0  1  0  0  0  0  0  0  0  0\n   -0.3318   -2.0000    0.0000   C 0  0  0  4  0  0  0  0  0  0  0  0\n  1  2  2  0  0  0  0\n  3  2  1  0  0  0  0\n  4  2  1  0  0  0  0\n  3  5  1  0  0  0  0\n  3  6  1  0  0  0  0\n  7  4  1  0  0  0  0\n  4  8  2  0  0  0  0\n  9  5  2  0  0  0  0\n 10  5  1  0  0  0  0\n 10  8  1  0  0  0  0\n  7 11  1  0  0  0  0\n  7 12  1  0  0  0  0\n 13  8  1  0  0  0  0\n 13 11  2  0  0  0  0\n 10 14  1  0  0  0  0\nM  END\n> <DATE>\n07-08-2009\n';
    let caffeine = ChemDoodle.readMOL(caffeineMolFile);
    //the bond lengths should be 14.4 pixels
    caffeine.scaleToAverageBondLength(14.4);
    myCanvas.loadMolecule(caffeine);
</script>

The code is getting quite long, but luckily we are finished. Using this procedure, you can add any graphics to your websites with ease. The other canvases provide more functionality and they are described in the links at the top of this page.

To summarize, we set up the Canvas.styles object to render the molecule according to our preference. Also note that we used the Molecule.scaleToAverageBondLength() function to scale the coordinates so that the average bond length is 14.4 pixels, as defined by ACS Document 1996. If you have many canvases on a page, you may find it convenient to set the default styles so you do not need to do this for each canvas. To set the defaults to the settings defined in this example, use the following code on your HTML page before any canvases are initialized:

<script>
    ChemDoodle.DEFAULT_STYLES.bondLength_2D = 14.4;
    ChemDoodle.DEFAULT_STYLES.bonds_width_2D = .6;
    ChemDoodle.DEFAULT_STYLES.bonds_saturationWidthAbs_2D = 2.6;
    ChemDoodle.DEFAULT_STYLES.bonds_hashSpacing_2D = 2.5;
    ChemDoodle.DEFAULT_STYLES.atoms_font_size_2D = 10;
    ChemDoodle.DEFAULT_STYLES.atoms_font_families_2D = ['Helvetica', 'Arial', 'sans-serif'];
    ChemDoodle.DEFAULT_STYLES.atoms_displayTerminalCarbonLabels_2D = true;
    ChemDoodle.DEFAULT_STYLES.atoms_useJMOLColors = true;
</script>

And that is it, you now know all you need to know to become productive using the ChemDoodle Web Components library. Continue reading to learn how to use more advanced features. And of course, if you need anything, feel free to contact us.

Continue to Retrieving Data →