Introduction

Before we begin, lets go over a few basics. If you are new to javascript, you should look at the examples below, and copy/paste them into your pages so you can see how they work. Then start changing around the variables and settings to get comfortable with them. Your browser of choice has javascript developer tools to help you with debugging. It is recommended that you first begin with the most basic component, the Viewer, to learn how to create the components, load molecules, and change visual specifications. Afterwards, it will be much easier to move on to the more advanced components.

Also note that all ChemDoodle Web Components are children of a class called Canvas and use the HTML 5 specification's canvas tag to produce its graphics. So the keyword, Canvas, will designate a function that works for all components.

Lastly, somehow you will need to get chemical data to these javascript functions. One way is to use server side scripts to set up javascript variables before the page is sent to the viewer. We provide some examples through PHP that are downloaded with this library. However, you should use your server side script of choice to populate the ChemDoodle Web Components on your webpage, and use our PHP scripts as examples. For this page, we initialize 5 global javascript variables (view the source of this page to see them) from MDL MOLFiles located on our server using the PHP function file2js(), so we can load them into the following components. The code will appear in a PHP file as follows.

<SCRIPT>         caffeine = <?php file2js('molecules/caffeine.mol'); ?>;         larger = <?php file2js('molecules/larger.mol'); ?>;         threed = <?php file2js('molecules/3d.mol'); ?>;         dna = <?php file2js('molecules/dna.mol'); ?>;         pyridine = <?php file2js('molecules/pyridine.mol'); ?>; </SCRIPT>

Components

There are currently 8 unique components:

1. Viewers
2. Hyperlinks
3. Rotators
4. Transformer
5. Slideshow
6. Doodler
7. MolGrabber
8. File Loader

The Viewers will replace all images of molecules. In the past, you would have to create the images by hand, or generate them from a servlet and cache them. No longer! Now you just load chemicals into Viewer components and change their styles. You may also change the default style for the whole page to easily fit your look and feel. They are fully customizable. No need to remake images for every small change! Visual specifications are covered in detail in the API, but very simply, they are grouped into component, atom and bond settings and are easily changed.

The Viewer is the most basic component in the set, and is a great example to begin with. All the components can be used by following three general steps:

1. Construction
2. Specify Settings
3. Load Molecule

1. The Viewer constructor takes only 3 parameters: name, width and height. The constructor will automatically create the component with the name and dimensions you give it. Note that it may be more convenient to keep the javascript variable name and the HTML component name the same for advanced development.
var viewer = new ViewerCanvas(name, width, height);
2. The constructor will automatically place the component on the page. After the component has been created, its settings may be changed by accessing its specs object. Consider the following examples where the specs object is called to change visuals and adhere to different look-and-feels. Any style, including ACS Document 1996, can be easily matched for professional websites. Complete information on all visual specifications is provided in the API.

	Using Images <SCRIPT>         var caffeine = <?php file2js('caffeine'); ?>;         var view1 = new ViewerCanvas('view1', 100, 100);         view1.setBackgroundImage('images/cappuccino.png');         view1.specs.atoms_color = '#FFC769';         view1.specs.bonds_color = '#FFC769';         view1.loadMolecule(readMOL(caffeine)); </SCRIPT>
	Customized Style <SCRIPT>         var viewCustom = new ViewerCanvas('viewCustom', 100, 100);         viewCustom.specs.backgroundColor = '#C9F9FF';         viewCustom.specs.atoms_font_size_2D = 12;         viewCustom.specs.atoms_font_families_2D[0] = 'Lucida Calligraphy';         viewCustom.specs.atoms_font_families_2D[1] = 'Mistral';         viewCustom.specs.atoms_font_families_2D[2] = 'URW Chancery L';         viewCustom.specs.atoms_color = 'green';         viewCustom.specs.bonds_color = 'purple';         viewCustom.specs.bonds_width_2D = .8;         viewCustom.specs.bonds_saturationWidth_2D = .3;         viewCustom.specs.bonds_symmetrical_2D = true;         viewCustom.loadMolecule(readMOL(caffeine)); </SCRIPT>
	ACS Document 1996 Style <SCRIPT>         default_bondLength_2D = 14.4;         var viewACS = new ViewerCanvas('viewACS', 100, 100);         viewACS.specs.bonds_width_2D = .6;         viewACS.specs.bonds_saturationWidth_2D = .18;         viewACS.specs.bonds_hasSpacing = 2.5;         viewACS.specs.atoms_font_size_2D = 10;         viewACS.specs.atoms_font_families_2D[0] = "Helvetica";         viewACS.loadMolecule(readMOL(caffeine)));         //reset bond length for subsequent components         default_bondLength_2D = 20; </SCRIPT>

3. The molecule can be loaded after the visual specifications have been set. The Canvas.loadMolecule() function takes a Molecule object that is defined in the API. You can write a javascript function to create a molecule for your own specification, use any of the format interpreters provided with this library, or contact us for custom development. The following code reads a MDL MOLfile, molecule, which is stored in a javascript variable, interprets it using the MDLInterpreter provided with this library and sends the output molecule to the canvas. The function, Canvas.loadMolecule(), will then set the molecule, center it, scale it (if necessary to fit), then do the necessary cheminformatics algorithms (such as finding rings, etc.) before painting the canvas.
viewer.loadMolecule(readMOL(molecule));
And that's it, very simple.


The functional Hyperlink components provide a mechanism for interacting with visitors in a very common way: through pointing and clicking. In essence, they are customizable buttons with molecules drawn on them. They provide visual feedback when the mouse hovers over them. When clicked, they will open new websites, or execute any javascript functions bound to them. Most importantly, as with all components, they are extendable and easily altered. If you want a user to see a specific mouse over visual effect, just plug it in. If you want to incorporate clickable components into a web app you are making, then Hyperlinks are a perfect choice. The constructor for a Hyperlink component can take between 4-6 parameters. The first four are requred. The last two are optional and specify the color and width of the rectangle highlight that is drawn by default when a user mouses over the component. The urlOrFunction parameter can either be a String or a function as you will see in the examples below. If it is a string, the component will act as a HTML hyperlink and redirect the user to the url specified. If it is a function, then upon clicking, that function will be executed.

var hyperlink = new HyperlinkCanvas(name, width, height, urlOrFunction[, highlightColor[, highlightWidth]]);

	Basic Hyperlink <SCRIPT>         var hyperlink1 = new HyperlinkCanvas('hyperlink1', 100, 100, 'http://www.ichemlabs.com', '#33FF71');         hyperlink1.openInNewWindow = true;         hyperlink1.loadMolecule(readMOL(pyridine)); </SCRIPT>
	Hover Image and Function Call <SCRIPT>         var hyperlink2 = new HyperlinkCanvas('hyperlink2', 100, 100, function(){alert('Hi, I\'m Linus Pauling! You can use these Hyperlink objects to link to other pages or activate functions.');});         hyperlink2.setHoverImage('images/linusPauling.png');         hyperlink2.loadMolecule(readMOL(pyridine)); </SCRIPT>
	Custom Hover Painting <SCRIPT>         var hyperlink3 = new HyperlinkCanvas('hyperlink3', 100, 100, function(){alert('Don\'t the ChemDoodle Web Components make you smile?');});         // Override drawChildExtras to hijack the hover painting function         hyperlink3.drawChildExtras = function(ctx){                 //check to make sure the component is hovered by testing if e!=null                 if(hyperlink3.e!=null){                         // fill outer circle with yellow                         ctx.fillStyle = "yellow";                         ctx.beginPath();                         ctx.arc(50,50,50,0,Math.PI*2,true);                         ctx.fill();                         // draw smiley                         ctx.strokeStyle = "blue";                         ctx.lineWidth = "2";                         ctx.beginPath();                         ctx.arc(50,50,50,0,Math.PI*2,true); // Outer circle                         ctx.moveTo(85,50);                         ctx.arc(50,50,35,0,Math.PI,false);  // Mouth (clockwise)                         ctx.moveTo(40,40);                         ctx.arc(35,40,5,0,Math.PI*2,true);  // Left eye                         ctx.moveTo(70,40);                         ctx.arc(65,40,5,0,Math.PI*2,true);  // Right eye                         ctx.stroke();                 }         }         hyperlink3.loadMolecule(readMOL(pyridine)); </SCRIPT>

The Rotators will impressively show off your creations and synthetic achievements. You may specify their direction of rotation and rotation speed. Play around with different visual specifications to show off different types of models, such as ball and stick and wireframe. Use these on webpages to help new chemists get a better sense of 3D chemicals.

The Rotator components are declared similar to the Viewer components, except there is an optional boolean parameter that specifies 3D rotation if true and 2D rotation otherwise. The RotatorCanvas is a child of the AnimatorCanvas class, which in turn, is a child of the Canvas class.

var rotator = new RotatorCanvas(name, width, height[, rotateIn3D]);
After the constructor has been called, several variables can be set to specify rotation increments, animation speed, and to start and stop the animation. There are three rotation increment variables that correspond to the frequency of rotation around the given axes in radians: RotationCanvas.xIncrement, RotationCanvas.yIncrement and RotationCanvas.zIncrement. For 2D rotation, only the RotationCanvas.zIncrement is considered. The default increment for all axes is 1°. The animation speed can also be set by specifying the AnimatorCanvas.timeout variable in milliseconds. This variable controls how many milliseconds elapse before the next frame is painted. The default is 33ms, which specifies a refresh rate of about 30 frames per second. When everything is ready, the AnimatorCanvas.startAnimation() function will start the rotation while the AnimatorCanvas.stopAnimation() function will stop it.

2D <SCRIPT>         var rotate2D = new RotatorCanvas('rotate2D', 200, 200);         rotate2D.specs.atoms_useJMOLColors = true;         rotate2D.loadMolecule(readMOL(larger));         rotate2D.startAnimation(); </SCRIPT>		3D <SCRIPT>         var rotate3D = new RotatorCanvas('rotate3D', 200, 200, true);         rotate3D.specs.atoms_useJMOLColors = true;         rotate3D.specs.atoms_circles_2D = true;         rotate3D.specs.bonds_symmetrical_2D = true;         rotate3D.specs.backgroundColor = '#E4FFC2';         rotate3D.yIncrement = -Math.PI / 360;         rotate3D.loadMolecule(readMOL(threed));         rotate3D.startAnimation(); </SCRIPT>

The Transformer allows your visitors to actually move, rotate and scale a molecule. Controls are as follows: rotate by clicking and dragging, translate by holding the alt key and clicking and dragging, scale using the mouse wheel. You will never have to wrestle with applets ever again!

Just like the Rotator component, the Transformer constructor has an optional boolean, that when not set to true locks users into only allowing rotation around the z-axis.
var transform = new TransformCanvas(name, width, height[, rotateIn3D]);

To look like a 3D modeling application <SCRIPT>         var transform1 = new TransformCanvas('transform1', 350, 200, true);         transform1.specs.bonds_useJMOLColors = true;         transform1.specs.bonds_width_2D = 3;         transform1.specs.atoms_display = false;         transform1.specs.backgroundColor = 'black';         transform1.specs.bonds_clearOverlaps_2D = true;         transform1.loadMolecule(readMOL(dna)); </SCRIPT>

While very complex programmatically, the Slideshow component simply displays multiple molecules, one at a time, with transitions in between. The Slideshow constructor takes the same parameters as the Viewer constructor.

var slideshow = new SlideshowCanvas(name, width, height);
After initialization, you add molecules to the Slideshow with the SlideshowCanvas.addMolecule() function. The order that you add the molecules in is retained during the animation. As with the RotatorCanvas, the SlideshowCanvas is a child of the AnimatorCanvas class, which in turn, is a child of the Canvas class. So, the animation speed (time between transitions) can also be set by specifying the AnimatorCanvas.timeout variable in milliseconds. The default is 5000ms, which will swap molecules every 5 seconds. The transition is 1 second by itself, so for best results, choose a timeout of at least 2 seconds. When everything is ready, the AnimatorCanvas.startAnimation() function will start the slideshow while the AnimatorCanvas.stopAnimation() function will stop it.

A fun marker style <SCRIPT>         var slideshow1 = new SlideshowCanvas('slideshow1', 250,250);         slideshow1.specs.backgroundColor = '#FFD6CC';         slideshow1.specs.bonds_width_2D = 2;         slideshow1.specs.bonds_saturationWidth_2D = .3;         slideshow1.specs.bonds_atomLabelBuffer_2D = .35;         slideshow1.specs.atoms_useJMOLColors = true;         slideshow1.specs.atoms_font_size_2D = 18;         slideshow1.specs.atoms_font_families_2D[0] = "Comic Sans MS";         slideshow1.specs.atoms_font_families_2D[1] = "cursive";         slideshow1.specs.atoms_font_families_2D[2] = "sans-serif";         slideshow1.addMolecule(readMOL(<?php file2js('planar1'); ?>));         slideshow1.addMolecule(readMOL(<?php file2js('ringSystem1'); ?>));         slideshow1.addMolecule(readMOL(<?php file2js('planar2'); ?>));         slideshow1.addMolecule(readMOL(<?php file2js('planar3'); ?>));         slideshow1.startAnimation(); </SCRIPT>

The Doodler component was created to be a non-intrusive object on your webpage. It's an intuitive chemical drawing tool without any buttons! Allow your visitors to draw molecules quickly and easily. Send their molecule to your servlet or javascript functions for quick and easy analysis.

This component mimics ChemDoodle in every way, from the optimize zone to the intuitive hover controls. The green question button in the upper-right corner opens up a screencast demonstration about how to use the application. All the chemistry fundamentals are covered, including elements and single/double/triple bonds. For more advanced functionality, please contact us for custom development. The drawing controls are as follows:

• Add Bond: Click on atom and drag to position, release to place. Alt and Shift modify fixed lengths and angles.
• Change Bond Order: Click on bond to cycle.
• Change Atom Label: Hover over an atom and press a letter to cycle through related elements.
• Translate: When no atom is hovered, click and drag, or use the arrow keys.
• Delete: Hover over an atom and press delete or backspace.

<SCRIPT>         var doodle1 = new DoodleCanvas('doodle1', 350, 250); </SCRIPT>

After the molecule has been drawn, you can obtain it using the Canvas.getMolecule() function, which will return a Molecule object that is defined in the API. You can then write a javascript function to analyze the structure, or use any of the format interpreters provided with this library to output the molecule to a format that can be passed to a backend servlet. The following code will obtain the molecule from the Doodler component and generate its MDL MOLfile using the MDLInterpreter provided with this library.

var molfile = writeMOL(doodle1.getMolecule());

The MolGrabber component provides access to online databases of chemical data. Just type in a search term and click return or the Show Molecule button to grab it. Currently, only the PubChem database is supported, but the Protein Data Bank and ChemSpider will also be supported in the future.

Do you have a great algorithm and you want your visitors to try it with their own molecules? No problem, now they can quickly search with MolGrabber for a molecule of interest. After loading, you can retrieve their molecule with Canvas.getMolecule() to send to whatever functions you desire. More information on post-analysis is provided in the Doodler section.

The use of this component requires access to your own server and backend processes such as CGI or PHP. We provide sample PHP code that queries the PubChem and Protein Data Bank databases. These server side functions are called when the corresponding action is activated. The action parameter in the following constructor is a path to the server side script to be executed. Use our provided PHP scripts as examples. You should write your own server side scripts to appropriately suit your own website's security and logistic concerns.

var molgrabber = new MolGrabberCanvas(name, width, height, action);

<SCRIPT>         var molgrabber1 = new MolGrabberCanvas('molgrabber1', 200, 200, '/CDWPubChem.php');         molgrabber1.specs.bonds_clearOverlaps_2D = true;         molgrabber1.specs.bonds_overlapClearWidth_2D = 2;         molgrabber1.setSearchTerm('morphine'); </SCRIPT>

The File Loader component is just one more way to easily receive input data for your website. Using this component, users can provide chemicals they have on their computer.

As with the previous two components, after loading, you can retrieve the molecule with Canvas.getMolecule() to send to whatever functions you desire.

As with the MolGrabber component, the use of this component requires access to your own server and backend processes such as CGI or PHP. We provide sample PHP code.

var fileloader = new FileCanvas(name, width, height, action);

<SCRIPT>         var file1 = new FileCanvas('file1', 200, 200, '/CDWGetLocalFile.php'); </SCRIPT>