ChemDoodle Web Components

This is the application programming interface (API) for the ChemDoodle Web Components. The API will show you how to interact with the components in javascript to write more advanced functions and transfer chemical data. Note that this library is covered under the open source GPL license. Please read and understand this license before extending or changing this API. You may feel free to contact us for alternate licensing and for custom development. This page is for moderate to advanced programmers.

Data Structures
Canvases
Layouts
1. Layout
2. SimpleReactionLayout
Input/Output
Cheminformatics

1a. VisualSpecifications

The VisualSpecifications structure contains all the variables that define how all objects are drawn on the canvas. The variables are categorized into Canvas, Atom (atoms_) and Bond (bonds_) settings. All of these visual specifications are set by the defaults when a Canvas is constructed. The default variables are global and have the same names as the member variables, except that they are preceded by default_. Change the default settings to enforce visual specifications on entire webpages.

constructor = new Function VisualSpecifications(Number x, Number y)

Function getFontString(Number size
Unit: pixels, Array families
Unit: Array<String>): given a font size, and array of font families, returns the HTML formatted string necessary for the canvas context object
returns String
Function set3DRepresentation(String representation): presets the 3D representation for a Canvas3D, currently accepts: 'Ball and Stick', 'van der Waals Spheres', 'Stick', 'Wireframe'
//Canvas Specifications
Array lightDirection_3D: the direction the lighting points in 3D scenes
Default Value: [-.1, -.1, -1]
Unit: vector
Number angstromsPerBondLength: number of Angstroms per bond length
Default Value: 1.25
Unit: Å/bond length
Number bondLength_2D: length of the bonds, set the default_ before using an interpreter to read your file; for 2D depiction
Default Value: 20
Unit: pixels
Number projectionBackCulling_3D: the far camera cutoff distance in 3D scenes
Default Value: 10000
Unit: Angstroms
Number projectionFrontCulling_3D: the near camera cutoff distance in 3D scenes
Default Value: 0.1
Unit: Angstroms
Number projectionVerticalFieldOfView_3D: the field of view angle for the projection matrix in 3D scenes
Default Value: 45
Unit: degrees
Number projectionWidthHeightRatio_3D: the width/height ratio for the projection matrix in 3D scenes, this should be width/height of your canvas to keep the aspect ratio square
Default Value: 1
Unit: ratio
Number rotateAngle: rotation angle of the canvas
Default Value: 0
Unit: radians
Number scale: scale of the canvas, set this after the molecule has been loaded, then repaint the canvas
Default Value: 1
Unit: %/100
String backgroundColor: background color of the canvas, set this to null to create a see-through canvas
Default Value: white
Unit: color
String lightDiffuseColor_3D: the diffusive light color in 3D scenes
Default Value: '#FFFFFF'
Unit: color
String lightSpecularColor_3D: the specular light color in 3D scenes
Default Value: '#FFFFFF'
Unit: color
//Atom Specifications
Array atoms_font_families_2D: the atom text font families, families cascade through the array if not found on the users computer; for 2D depiction
Default Value: [Helvetica, Arial, Dialog]
Unit: Array<String>
Boolean atoms_circles_2D: draw atoms as circles, text is not drawn; for 2D depiction
Default Value: false
Unit: true/false
Boolean atoms_display: draw the atoms
Default Value: true
Unit: true/false
Boolean atoms_displayTerminalCarbonLabels_2D: show labels for terminal carbons
Default Value: false
Unit: true/false
Boolean atoms_implicitHydrogens_2D: render implicit hydrogens on all labels that are visible
Default Value: true
Unit: true/false
Boolean atoms_showHiddenCarbons_2D: show hidden carbons that are located between two nearly parallel bonds of the same bond order
Default Value: true
Unit: true/false
Boolean atoms_useJMOLColors: use JMOL colors for atoms
Default Value: false
Unit: true/false
Boolean atoms_useVDWDiameters_3D: use van der Waals diameters for atoms
Default Value: false
Unit: true/false
Number atoms_circleBorderWidth_2D: width of atom circle borders for 2D depiction
Default Value: 1
Unit: pixels
Number atoms_circleDiameter_2D: diameter of atom circles for 2D depiction
Default Value: 10
Unit: pixels
Number atoms_font_size_2D: atom text font size for 2D depiction
Default Value: 12
Unit: points
Number atoms_resolution_3D: the resolution of the sphere vertex buffer used to render atoms in 3D scenes
Default Value: 60
Unit: positive integer
Number atoms_sphereDiameter_3D: the diameter of atoms in 3D scenes (for ball and stick and wireframe type representations); atoms_useVDWDiameters_3D overrides this property
Default Value: 0.8
Unit: Angstroms
String atoms_color: atom color
Default Value: #000000
Unit: color
String atoms_materialAmbientColor_3D: the ambient color for atoms in 3D scenes
Default Value: #000000
Unit: color
String atoms_materialSpecularColor_3D: the specular color for atoms in 3D scenes
Default Value: #555555
Unit: color
//Bond Specifications
Boolean bonds_clearOverlaps_2D: draws a small background to the bond in the background color to contrast between overlapping bonds for 2D depiction
Default Value: false
Unit: true/false
Boolean bonds_display: draw the bonds
Default Value: true
Unit: true/false
Boolean bonds_symmetrical_2D: double bonds are drawn symmetrically always, instead of pointing towards the center of a ring, for instance; for 2D depiction
Default Value: false
Unit: true/false
Boolean bonds_useJMOLColors: color the bond by using a gradient between the JMOL colors of the connected atoms
Default Value: false
Unit: true/false
Number bonds_atomLabelBuffer_2D: the amount that the bond pulls back to avoid drawing under atom text for 2D depiction
Default Value: 0.25
Unit: %/100*bond length
Number bonds_cylinderDiameter_3D: the diameter of bonds in 3D scenes
Default Value: 0.3
Unit: Angstroms
Number bonds_hashSpacing_2D: the spacing of hashes for 2D depiction
Default Value: 2.5
Unit: pixels
Number bonds_hashWidth_2D: the width of hashes for 2D depiction
Default Value: 1
Unit: pixels
Number bonds_materialShininess_3D: the shininess of bonds in 3D scenes
Default Value: 32
Unit: positive integer
Number bonds_overlapClearWidth_2D: the extent of the overlap clearing in both directions for 2D depiction
Default Value: 0.5
Unit: pixels
Number bonds_resolution_3D: the resolution of the cylinder vertex buffer used to render bonds in 3D scenes
Default Value: 60
Unit: positive integer
Number bonds_saturationAngle_2D: the angle that saturated double bonds are clipped by for 2D depiction
Default Value: Math.PI/3
Unit: radians
Number bonds_saturationWidth_2D: relative saturation width of double and triple bond lines for 2D depiction
Default Value: 0.2
Unit: %/100*bondLength
Number bonds_wedgeThickness_2D: the thickness of stereochemical wedge bonds for 2D depiction
Default Value: 0.22
Unit: %/100*bondLength
Number bonds_width_2D: width of the bonds for 2D depiction
Default Value: 1
Unit: pixels
String bonds_color: bond color
Default Value: #000000
Unit: color
String bonds_ends_2D: bond end style for 2D depiction
Allowed Values: [butt, round, square]
Default Value: round
String bonds_materialAmbientColor_3D: the ambient color for bonds in 3D scenes
Default Value: #222222
Unit: color
String bonds_materialSpecularColor_3D: the specular color for bonds in 3D scenes
Default Value: #555555
Unit: color
//Spectrum Specifications
Array text_font_families: the spectrum text font families, families cascade through the array if not found on the users computer
Default Value: [Helvetica, Arial, Dialog]
Unit: Array<String>
Boolean plots_flipXAxis: flip the x-axis, typical for certain domain units of NMR and IR spectra
Default Value: false
Unit: true/false
Boolean plots_showGrid: display an grid using the axes' ticks
Default Value: false
Unit: true/false
Boolean plots_showIntegration: display an integration line, typically for NMR spectra
Default Value: false
Unit: true/false
Boolean plots_showYAxis: display the y-axis
Default Value: true
Unit: true/false
Number plots_gridLineWidth: width of the integration line
Default Value: 0.5
Unit: pixels
Number plots_integrationLineWidth: width of the integration line
Default Value: 1
Unit: pixels
Number plots_width: width of the plot line
Default Value: 1
Unit: pixels
Number text_font_size: spectrum text font size
Default Value: 12
Unit: points
String plots_color: plot color
Default Value: #000000
Unit: color
String plots_gridColor: integration line color
Default Value: gray
Unit: color
String plots_integrationColor: integration line color
Default Value: #c10000
Unit: color
String text_color: spectrum text color
Default Value: #000000
Unit: color

1b. Point

represents a 2D point and contains functions for various 2D geometric calculations

constructor = new Function Point(Number x, Number y)

Function add(Point p): add Point p
Function angle(Point p): returns the angle to Point p, with the current Point as the origin (y-axis is inverted for the inverted canvases)
returns Number
Unit: radians
Function angleForStupidCanvasArcs(Point p): same as angle(), but for the contradictory way canvas arcs are handled
returns Number
Unit: radians
Function distance(Point p): returns the distance to Point p
returns Number
Unit: pixels
Function sub(Point p): subtract Point p
Number x: x coordinate
Default Value: 0
Unit: pixels
Number y: y coordinate
Default Value: 0
Unit: pixels

1c. Atom

represents a chemical atom

constructor = new Function Atom(String label, Number x, Number y, Number z)

prototype = Point

Function add3D(Atom a): the 3D counterpart to the same Point function
Function distance3D(Atom a): the 3D counterpart to the same Point function
Function draw(Context ctx, VisualSpecifications specs): draws this atom to the canvas that owns the Context using the given VisualSpecifications
Function isLabelVisible(VisualSpecifications specs): returns true if label is not 'C'
returns Boolean
Unit: true/false
Function render(GLContext gl, VisualSpecifications specs): renders this atom to the 3D scene in the WebGL canvas that owns the GLContext using the given VisualSpecifications
Function sub3D(Atom a): the 3D counterpart to the same Point function
Boolean isHover: for DoodleCanvas, mouse is hovered over this, draws a brown circle
Boolean isLone: not connected to any other atoms (if Carbon, draws a grey dot)
Boolean isOverlap: for DoodleCanvas, overlaps another atom, draws a red circle
Boolean isSelected: for DoodleCanvas, mouse has clicked this, draws a blue circle
Number angleOfLeastInterference: metadata set by the containing Molecule, the angle in radians that points towards the largest open space between the bonds connected to the atom
Number bondNumber: metadata set by the containing Molecule, the number of bonds connected to the atom
Number charge: atomic charge
Default Value: 0
Number coordinationNumber: metadata set by the containing Molecule, the valency of the atom
Number z: z coordinate
Default Value: 0
Unit: pixels
String label: label of the atom, should be an element symbol
Default Value: C
Unit: Element Symbol

1d. Bond

represents a chemical bond

constructor = new Function Bond(Atom a1, Atom a2, Number bondOrder)

Function contains(Atom a): returns the Atom opposite Atom a
returns Boolean
Unit: true/false
Function draw(Context ctx, VisualSpecifications specs): draws this bond to the canvas that owns the Context using the given VisualSpecifications
Function getCenter(): returns a Point that specifies the center between the two Atoms in the Bond
returns Point
Unit: pixels
Function getLength(): returns the bond length on the XY plane
returns Number
Unit: pixels
Function getLength3D(): returns the 3D bond length
returns Number
Unit: pixels
Function getNeighbor(Atom a): returns the Atom opposite Atom a
returns Atom
Function render(GLContext gl, VisualSpecifications specs): renders this bond to the 3D scene in the WebGL canvas that owns the GLContext using the given VisualSpecifications
static String BOND_STEREO_AMBIGUOUS: specifies an ambiguous stereo bias
static String BOND_STEREO_NONE: specifies no stereo bias
static String BOND_STEREO_PROTRUDING: specifies a protruding stereo bias
static String BOND_STEREO_RECESSED: specifies a recessed stereo bias
Atom a1: first Atom
Atom a2: second Atom
Boolean isHover: for DoodleCanvas, mouse is hovered over this, draws brown handles
Number bondOrder: bond order
Allowed Values: [1, 2, 3]
Default Value: 1
Ring ring: the largest containing SSSR ring
String stereo: stereochemical bias of the bond, must be one of the BOND_STEREO constants
Default Value: BOND_STEREO_NONE

1e. Ring

represents a chemical ring

constructor = new Function Ring()

Function getCenter(): returns a Point that specifies the center of this Ring
returns Point
Unit: pixels
Function setupBonds(Point p): loops through bonds and sets all Bond.ring objects in to itself, caches center
Array atoms: constituent atoms
Array bonds: constituent bonds
Point center: the center of this Ring, cached for performance

1f. Molecule

represents a chemical molecule

Function check(): sets up the molecule for drawing by checking for lone carbons, rings and sorting, as well as setting up the metadata for drawing
Function draw(Context ctx, VisualSpecifications specs): draws this molecule to the canvas that owns the Context using the given VisualSpecifications
Function getAngles(Atom a): with a as the origin, returns an Array of all the angles to the immediately connected atoms in this Molecule, in ascending order
returns Array
Unit: radians
Function getAverageBondLength(): calculates the average bond length of the molecule, or returns 0 if there are no bonds, this is a 2D function
returns Number
Unit: pixels
Function getBonds(Atom a): returns an Array on Bond objects that contain the input Atom a in the molecule
returns Array
Unit: Bond
Function getCenter(): returns a Point that specifies the center of this Molecule
returns Point
Unit: pixels
Function getCenter3D(): returns an Atom that specifies the center of this Molecule in 3 dimensions
returns Atom
Unit: pixels
Function getCoordinationNumber(Array bs): adds the bond orders from the bs (Array of Bond) parameter together to calculate the coordination number
returns Number
Unit: coordination number
Function getDimension(): returns a Point that specifies the width and height of this Molecule in the XY plane. Among other uses, this method can be used to first find the dimensions of a molecule to set the dimensions of a Canvas to perfectly fit it (make sure to add some aesthetic buffer space).
returns Point
Unit: pixels
Function render(GLContext gl, VisualSpecifications specs): renders this molecule to the 3D scene in the WebGL canvas that owns the GLContext using the given VisualSpecifications
Function scaleToAverageBondLength(Number length): scales the molecule so that the average bond length equals the input length, this is a 2D function
Function setupMetaData(): sets up metadata for the molecule, used internally to determine how graphics are rendered
Function sortAtomsByZ(): sorts atoms in ascending order by z coordinate
Function sortBondsByZ(): sorts bonds in ascending order by their z coordinate
Array atoms: constituent atoms
Array bonds: constituent bonds
Array rings: constituent rings
Boolean findRings: will find rings in the check() function; this should be disabled by you, if not necessary, to improve performance
Default Value: true

1g. Spectrum

data structure to hold spectrum information

Function draw(Context ctx, VisualSpecifications specs, Number width, Number height): draws this spectrum to the canvas that owns the Context using the given VisualSpecifications, the canvas's width and height are also provided
Function getInverseTransformedX(Number x, Number width, Number offsetLeft): function to obtain the x-coordinate within the spectrum's plot space of the input x-coordinate from the canvas space
returns Number
Unit: x axis units
Function getTransformedX(Number x, VisualSpecifications specs, Number width, Number offsetLeft): used internally to obtain the x-coordinate within the canvas space of the input x-coordinate from the spectrum's plot space
returns Number
Unit: pixels
Function getTransformedY(Number x, VisualSpecifications specs, Number height, Number offsetBottom, Number offsetTop): used internally to obtain the y-coordinate within the canvas space of the input y-coordinate from the spectrum's plot space
returns Number
Unit: pixels
Function setup(): analyzes the data array for the default domain and scales the range between 0 and 1, called by the interpreters that read spectra files
Function zoom(Number pixel1, Number pixel2, Number width): given the input pixel1 and pixel2 values in the canvas's domain space (in any order), will focus in on that domain by appropriately setting the minX and maxX parameters given the canvas width
Array data: the spectrum plot as an array of Point objects
Boolean continuous: determines how the plot will be drawn, if continuous is true, then the plot is rendered as a path from Point to Point in the data array, if continuous is false, then each data point will be rendered as a vertical line from y = 0
Default Value: true
Number maxX: the maximum domain value, set up by the setup method to the largest x value in the data array after the spectrum is read, can also be manually set
Number minX: the minimum domain value, set up by the setup method to the smallest x value in the data array after the spectrum is read, can also be manually set
String title: the title of the spectrum, most spectrum file formats provide a title, no title is displayed if the value is null
Default Value: null
String xUnit: the unit of the domain to be displayed under the x-axis, no x-axis title is displayed if the value is null
Default Value: null
String yUnit: the unit of the domain to be displayed under the y-axis, no y-axis title is displayed if the value is null
Default Value: null

2a. Canvas

is the parent class for all ChemDoodle Web Component Canvases, it should not be instantiated. Its basic functionality allows for molecules to be drawn and loaded. This class also hosts the system for handling user input events from the mouse and the keyboard. This class should be extended for custom canvases.

constructor = new Function Canvas()

Function center(): centers the loaded molecule in the canvas
Function create(String id, Integer width, Integer height): this function places the canvas in the HTML page and is called in every constructor of the children classes. The id is the HTML id of the canvas element, with width and height its dimensions
Function getMolecule(): returns the Molecule currently associated with the canvas
returns Molecule
Function loadMolecule(Molecule mol): loads the given Molecule, mol, and checks it
Function prehandleEvent(Event e): conditions the user input event and sets a new variable in the Event object named p that contains the coordinates of the event in the canvas
Function prehandleMobileEvent(Event e): conditions the user input event from Mobile devices and sets a new variable in the Event object named p that contains the coordinates of the event in the canvas
Function repaint(): repaints the canvas
Function setBackgroundImage(String url): sets the background image to the image specified by the url parameter
optional abstract Function drawChildExtras(Context ctx): draws extra graphics on top of the base graphics, override this for your custom canvases
optional abstract Function subCreate(): additional function to be called during create(), such that child classes can do additional setup before returning to the child constructor
//Mobile Touch Events and Gestures
optional abstract Function gesturechange(Event e): receives the gesture move event for mobile devices, override this for your custom canvases
optional abstract Function gestureend(Event e): receives the touch end event for mobile devices, override this for your custom canvases
optional abstract Function gesturestart(Event e): receives the gesture start event for mobile devices, override this for your custom canvases
optional abstract Function touchend(Event e): receives the touch end event for mobile devices, override this for your custom canvases, forwards to mouseup if not implemented
optional abstract Function touchmove(Event e): receives the touch move event for mobile devices, override this for your custom canvases, forwards to drag if not implemented
optional abstract Function touchstart(Event e): receives the touch start event for mobile devices, override this for your custom canvases, forwards to mousedown if not implemented
//Mouse Events
optional abstract Function click(Event e): receives the mouse click event, override this for your custom canvases
optional abstract Function dblclick(Event e): receives the mouse double click event, override this for your custom canvases
optional abstract Function drag(Event e): receives the mouse drag event, override this for your custom canvases
optional abstract Function middleclick(Event e): receives the mouse middle click event, override this for your custom canvases
optional abstract Function middlemousedown(Event e): receives the mouse middle mouse down event, override this for your custom canvases
optional abstract Function middlemouseup(Event e): receives the mouse middle mouse up event, override this for your custom canvases
optional abstract Function mousedown(Event e): receives the mouse down event, override this for your custom canvases
optional abstract Function mousemove(Event e): receives the mouse move event, override this for your custom canvases
optional abstract Function mouseout(Event e): receives the mouse out event, override this for your custom canvases
optional abstract Function mouseover(Event e): receives the mouse over event, override this for your custom canvases
optional abstract Function mouseup(Event e): receives the mouse up event, override this for your custom canvases
optional abstract Function mousewheel(Event e, Number delta): receives the mouse wheel event, override this for your custom canvases; delta is the amount the wheel has spun
optional abstract Function rightclick(Event e): receives the mouse right click event, override this for your custom canvases
optional abstract Function rightmousedown(Event e): receives the mouse right mouse down event, override this for your custom canvases
optional abstract Function rightmouseup(Event e): receives the mouse right mouse up event, override this for your custom canvases
//Keyboard Events
optional abstract Function keydown(Event e): receives the key down event, override this for your custom canvases
optional abstract Function keypress(Event e): receives the key press event, override this for your custom canvases
optional abstract Function keyup(Event e): receives the key up event, override this for your custom canvases
static Boolean ALT: keeps track of whether the alt key is held down
static Boolean SHIFT: keeps track of whether the shift key is held down
static Canvas CANVAS_DRAGGING: keeps track of the canvas that the mouse is currently dragging from. This is null if no Canvas is currently being dragged from
static Canvas CANVAS_OVER: keeps track of the canvas that the mouse is currently over. This is null if the mouse is over no canvas
Image image: the background image, overrides the VisualSpecification backgroundColor property; if null, no image is drawn
Integer height: the height of the associated HTML element
Integer width: the width the associated HTML element
Molecule molecule: the molecule associated with this canvas
String emptyMessage: the message to be displayed if the molecule is null. If this variable is null, no message is displayed if the molecule is null
String id: the HTML id of the associated HTML element
VisualSpecifications specs: the visual specifications that define how content should be painted

2b. Canvas3D

is the parent class for all 3D ChemDoodle Web Component Canvases, it should not be instantiated. Its basic functionality allows for molecules to be rendered in a 3D scene and loaded. This class should be extended for custom 3D canvases.

constructor = new Function Canvas3D()

prototype = Canvas

Function afterLoadMolecule(): helper method to reset the scene if a gl parameter has been altered
Function setViewDistance(Number distance): helper method to move the camera the input distance away from the center of the scene; distance is in Angstroms
Function setupScene(): creates the 3D scene
override Function center(): centers the molecule in 3D around the origin
override Function drag(Event e): performs the mouse drag action
override Function mousedown(Event e): performs the mouse down action
override Function mousewheel(Event e): performs the mouse scroll action
override Function repaint(): renders the 3D scene
override Function rightmousedown(Event e): performs the mouse right click action
override Function subCreate(): sets up GLContext, alerts viewer to warning if GLContext cannot be created; initializes shaders and scene
static Boolean NO_WEBGL_WARNING: if true, no warning will be displayed if WebGL cannot be initialized
Default Value: false
Unit: true/false
Matrix rotationMatrix: the rotation matrix to be applied before rendering the 3D scene
Default Value: Matrix.I(4)
Unit: 4x4 matrix
Matrix translationMatrix: the translation matrix to be applied before rendering the 3D scene
Default Value: Matrix.I(4)
Unit: 4x4 matrix
Point lastPoint: the last point in the canvas's space that the user initiated a mouseDown event

2c. AnimatorCanvas

is a child of the Canvas class and is the parent class for all animated ChemDoodle Web Component Canvases, it should not be instantiated. It provides an extendable framework for creating animations. This class should be extended for custom animated canvases.

constructor = new Function AnimatorCanvas()

prototype = Canvas

Function isRunning(): returns true if the animation is currently running
returns Boolean
Unit: true/false
Function startAnimation(): initializes the animation
Function stopAnimation(): terminates the animation
abstract Function nextFrame(): called by the timer, in the frequency specified by the interval timeout, this must be overridden for your custom canvases, repaints the canvas after each call
Number timeout: the default refresh rate
Default Value: 50 (~20fps)
Unit: ms
Timer handle: a handle on the current Timer so it can be started and stopped

2d. SpectrumCanvas

is a child of the Canvas class and is the parent class for all ChemDoodle Web Component spectrum Canvases, it should not be instantiated. It provides an extendable framework for laying out Spectrum objects. This class should be extended for custom spectrum canvases.

constructor = new Function SpectrumCanvas()

prototype = Canvas

Function getSpectrum(): returns the Spectrum currently associated with the canvas
returns Spectrum
Function loadSpectrum(Spectrum spectrum): loads the given Spectrum, spectrum, and checks it
override Function repaint(): repaints the canvas
Spectrum spectrum: the spectrum associated with this canvas
String emptyMessage: the message to be displayed if the spectrum is null or is empty. If this variable is null, no message is ever displayed.
Default Value: No Spectrum Loaded or Recognized

2e. DoodleCanvas

is a child of the Canvas structure and provides a basic canvas for users to draw molecules with

constructor = new Function DoodleCanvas(String id, Integer width, Integer height)

prototype = Canvas

override Function drag(Event e): performs the mouse drag action
override Function drawChildExtras(Context ctx): draws extra graphics on top of the base graphics
override Function keydown(Event e): performs the key down action
override Function mousedown(Event e): performs the mouse down action
override Function mousemove(Event e): performs the mouse move action
override Function mouseup(Event e): performs the mouse up action
Atom tempAtom: a temporary holder for soon to be placed atoms
Boolean isHelp: true if the user is hovering over the help icon
Point helpPos: the position of the help icon

2f. FileCanvas

is a child of the Canvas structure and provides a basic canvas for users to load molecule from their computer with. The action is the server side script to be called that loads the file into a hidden frame. After the asynchronous call is finished, the correct function is called to load the molecule into the canvas with the associated id

constructor = new Function FileCanvas(String id, Integer width, Integer height, String String, String urlOrFunction, String color, Number size)

prototype = Canvas

2g. HyperlinkCanvas

is a child of the Canvas structure and provides a basic button-like canvas: it responds to mouse overs and executes a link or action when clicked on

constructor = new Function HyperlinkCanvas(String id, Integer width, Integer height, String urlOrFunction)

prototype = Canvas

Function setHoverImage(String url): sets the canvas's hover image to the image url specified
override Function click(Event e): performs the mouse click action
override Function drawChildExtras(Context ctx): draws extra graphics on top of the base graphics
override Function mouseout(Event e): performs the mouse out action
override Function mouseover(Event e): performs the mouse over action, currently not called
Boolean openInNewWindow: if true and urlOrFunction is a url, then the url will be opened in a new window instead of changing the current page
Default Value: false
Unit: true/false
Event e: keeps track of the last event
Image hoverImage: if this is initialized, then the mouse over will display an image instead of a hyperlink-like decoration
Number size: the width of the mouse over highlight
Default Value: 2
Unit: pixels
String color: the color of the mouse over highlight
Default Value: blue
Unit: color
String urlOrFunction: this is the url to be directed to when clicked, this can also be a function object and the function will be executed when clicked

2h. MolGrabberCanvas

is a child of the Canvas structure and provides a basic canvas for users to search databases with. The action is the server side script to be called that loads the queried data into a hidden frame. After the asynchronous call is finished, the correct function is called to load the molecule into the canvas with the associated id

constructor = new Function MolGrabberCanvas(String id, Integer width, Integer height, String String)

prototype = Canvas

Function setSearchTerm(String term): automatically searches for and loads the input search term

2i. MolGrabberCanvas3D

is a child of the Canvas3D structure and provides a basic 3D canvas for users to search databases with. The content may then be transformed just as in the Transformer3D canvas. The action is the server side script to be called that loads the queried data into a hidden frame. After the asynchronous call is finished, the correct function is called to load the molecule into the canvas with the associated id

constructor = new Function MolGrabberCanvas3D(String id, Integer width, Integer height, String String)

prototype = Canvas3D

Function setSearchTerm(String term): automatically searches for and loads the input search term

2j. ObserverCanvas

is a child of the SpectrumCanvas structure and provides a basic canvas for simply displaying a static styled spectrum drawing

constructor = new Function ObserverCanvas(String id, Integer width, Integer height)

prototype = SpectrumCanvas

2k. PerspectiveCanvas

is a child of the SpectrumCanvas structure and provides a basic canvas for users to inspect (change domain [drag], scale y-axis [mousewheel], reset [double click]) a spectrum with

constructor = new Function PerspectiveCanvas(String id, Integer width, Integer height)

prototype = SpectrumCanvas

override Function dblclick(Event e): catches double click events and resets the spectrum view
override Function drag(Event e): performs the mouse drag action
override Function drawChildExtras(Context ctx): draws extra graphics on top of the base graphics
override Function gesturechange(Event e): handles any pinch actions from mobile devices which will scale the y-axis
override Function mousedown(Event e): performs the mouse down action
override Function mouseup(Event e): performs the mouse up action
override Function mousewheel(Event e, Number delta): performs the mouse wheel action
Point dragRange: keeps track of the first and last x-coordinates of drag events

2l. RotatorCanvas

is a child of the AnimatorCanvas structure and provides a basic canvas for displaying molecular rotation animations

constructor = new Function RotatorCanvas(String id, Integer width, Integer height, String String, Boolean rotate3D)

prototype = AnimatorCanvas

override Function dblclick(Event e): catches double click events and toggles the animation
override Function nextFrame(): updates the state during the rotation
Boolean rotate3D: the animation will rotate in 3 dimensions if true, will only rotate around the z axis if false
Default Value: false
Number xIncrement: the x rotation increment
Default Value: Math.PI/360
Unit: radians
Number yIncrement: the y rotation increment
Default Value: Math.PI/360
Unit: radians
Number zIncrement: the z rotation increment
Default Value: Math.PI/360
Unit: radians

2m. RotatorCanvas3D

is a child of the Canvas3D structure and provides a basic canvas for displaying molecular rotation animations in a 3D scene

constructor = new Function RotatorCanvas3D(String id, Integer width, Integer height)

prototype = Canvas3D

Function isRunning(): returns true if the animation is currently running, absorbed from AnimatorCanvas
returns Boolean
Unit: true/false
Function startAnimation(): initializes the animation, absorbed from AnimatorCanvas
Function stopAnimation(): terminates the animation, absorbed from AnimatorCanvas
override Function dblclick(Event e): catches double click events and toggles the animation, absorbed from RotatorCanvas
override Function drag(): set to null to ignore this gesture
override Function mousedown(): set to null to ignore this gesture
override Function mousewheel(): set to null to ignore this gesture
override Function nextFrame(): called by the timer, in the frequency specified by the interval timeout, this must be overridden for your custom canvases, repaints the canvas after each call
override Function rightmousedown(): set to null to ignore this gesture
Boolean rotate3D: the animation will rotate in 3 dimensions if true, will only rotate around the z axis if false
Default Value: false
Number timeout: the default refresh rate, absorbed from AnimatorCanvas
Default Value: 50 (~20fps)
Unit: ms
Number xIncrement: the x rotation increment
Default Value: Math.PI/360
Unit: radians
Number yIncrement: the y rotation increment
Default Value: Math.PI/360
Unit: radians
Number zIncrement: the z rotation increment
Default Value: Math.PI/360
Unit: radians
Timer handle: a handle on the current Timer so it can be started and stopped

2n. SlideshowCanvas

is a child of the AnimatorCanvas structure and provides a basic canvas for displaying transitions between several molecular structures

constructor = new Function SlideshowCanvas(String id, Integer width, Integer height)

prototype = AnimatorCanvas

Function addMolecule(Molecule molecule): adds a molecule to the slideshow
Function breakInnerHandle(): completes the second phase of the animation and the molecule switch
override Function drawChildExtras(Context ctx): draws extra graphics on top of the base graphics
override Function nextFrame(): updates the state during the rotation
Array molecules: the molecular structures to be displayed in the order they are to be displayed in, this should not be empty
Integer curIndex: keeps track of the current index in molecules
Integer phase: keeps track of the current phase (different types of animations) during the transition
Number alpha: keeps track of the current alpha during the transition
Number timeout: this parameter is inherited from AnimatorCanvas, but it is set to a larger value
Default Value: 5000
Unit: ms
Timer innerHandle: holds on to the second inner Timer for performing the transition, so it can be started and stopped

2o. TransformCanvas

is a child of the Canvas structure and provides a basic canvas for users to transform (translate [alt+drag], rotate [drag], scale [mousewheel]) molecules with

constructor = new Function TransformCanvas(String id, Integer width, Integer height)

prototype = Canvas

override Function drag(Event e): performs the mouse drag action
override Function gesturechange(Event e): handles any pinch actions from mobile devices which will scale the molecule
override Function mousedown(Event e): performs the mouse down action
override Function mouserightdown(Event e): performs the mouse right down action, currently not called
override Function mousewheel(Event e, Number delta): performs the mouse wheel action
Boolean rotate3D: will rotate in 3 dimensions if true, will only rotate around the z axis if false
Default Value: false
Boolean useQuaternions: will use quaternion rotation if true, will rotate in 3D around the X and Y axes if false; currently the quaternion rotation is useable but some of the directions are reversed
Default Value: false
Number rotationMultMod: multiplication modifier for the rotation calculations, larger numbers correspond to faster rotations
Default Value: 1.3
Point lastPoint: keeps track of the last mouse position

2p. TransformCanvas3D

is a child of the Canvas3D structure and provides a basic canvas for users to transform (translate [alt+drag], rotate [drag], scale [mousewheel]) molecules with in a 3D scene

constructor = new Function TransformCanvas3D(String id, Integer width, Integer height)

prototype = Canvas

2q. ViewerCanvas

is a child of the Canvas structure and provides a basic canvas for simply displaying a static styled structural drawing

constructor = new Function ViewerCanvas(String id, Integer width, Integer height)

prototype = Canvas

2r. ViewerCanvas3D

is a child of the Canvas3D structure and provides a basic canvas for simply displaying a static 3D scene of a molecule

constructor = new Function ViewerCanvas3D(String id, Integer width, Integer height)

prototype = Canvas

override Function drag(): set to null to ignore this gesture
override Function mousedown(): set to null to ignore this gesture
override Function mousewheel(): set to null to ignore this gesture
override Function rightmousedown(): set to null to ignore this gesture

3a. Layout

is the parent class for all ChemDoodle Web Component Layouts, it should not be instantiated. It provides minimal, but essential, inherited functionality to aid in creating child classes that can organize complex layouts of Canvas objects and other HTML elements. This class should be extended for custom layouts.

constructor = new Function Layout()

Function create(String name): Sets up the component in the constructor. Essentially this just registers the unique name for the layout. This should be called as the last function in all constructors for classes that extend Layout.
Function layout(): lays out the component on the webpage. This method should not be overriden, instead set the layout rules in the innerLayout() function of the child class, which is called by this method.
abstract Function innerLayout(): this method is defined by all child classes of Layout. This method should define the html to layout the component and write it to the HTML document.
VisualSpecifications specs: the visual specifications that define how content should be painted. All contained Canvas objects will inherit this VisualSpecifications object.

3b. SimpleReactionLayout

is a child of the Layout class and allows the building and displaying of simple single reactions.

constructor = new Function SimpleReactionLayout(String name)

prototype = Layout

Function addProduct(Molecule product): add the input Molecule to the end of the products Array.
Function addReactant(Molecule reactant): add the input Molecule to the end of the reactants Array.
override Function innerLayout(): lays out the reactant and products canvases in a HTML table with HTML elements in between to show the reaction decorations.
Array products: an array holding the product molecules
Array reactants: an array holding the reactant molecules
String arrow: any HTML content to represent the arrow between the reactants and products
Default Value: →
Unit: HTML
String plus: any HTML content to represent the plus symbol placed between multiple reactants or products
Default Value: +
Unit: HTML
String textAbove: any HTML content to represent the text to be displayed above the reaction arrow, if null, then nothing is displayed above the arrow.
Default Value: null
Unit: HTML
String textBelow: any HTML content to represent the text to be displayed below the reaction arrow, if null, then nothing is displayed below the arrow.
Default Value: null
Unit: HTML

4a. Input Events (Desktop and Mobile Devices)

Users can interact with ChemDoodle Web Components through a desktop browser using a keyboard and mouse or through a mobile browser using touch events and gestures. For desktop browsers, implement the mouse and keyboard event listeners to perform actions. On mobile devices, the touch events and gestures will be closely mapped to the most equivalent mouse and keyboard event handlers. This is perfect for simple applications as the drag, mousedown and mouseup events are closely matched to touch events. However, hovering is something that is not possible on mobile devices, so mousemove handlers will never be called. Additionally, gestures like pinching have no mouse equivalent.

To rectify this, write event handlers for any of the touch or gesture events to have mobile device interactions forwarded to more appropriate methods. If those mobile gesture handlers are implemented, the Canvas class will forward the corresponding events to them instead of to the mapped mouse and keyboard events. This way, you can implement all of the handlers for your canvas and you will get a perfect handling of input events on both desktop and mobile browsers, with only having to write a single component!

4b. File Formats

There are several popular chemical file formats out there. Currently, ChemDoodle Web Components only reads and writes basic MDL MOLFiles and reads basic RCSB PDB files. This is sufficient for most chemical applications. Also note that ChemDoodle Web Components are optimized for individual molecules, so files containing many molecules may not be appropriate. To convert files to MDL MOLFile or RCSB PDB format, use ChemDoodle, which currently reads and writes 16 popular chemical filetypes.

4c. File Input

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 example, below we initialize 4 global javascript variables from MDL MOLFiles located on our server using the PHP function file2js(), so we can load them into components on the same page.

<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'); ?>;

</SCRIPT>

4d. MDLInterpreter

is a static class for reading and writing MDL files

static Function fit(String data, Number length): helper method for writing data to fixed lengths, returns the formatted String
returns String
static Function readMOL(String content, Number multiplier): reads the MOLFile content and returns the corresponding Molecule object; the optional multiplier variable will override the default_anstromsPerBondLength variable, set it to 1 for 3D scenes in Angstroms
returns Molecule
static Function writeMOL(Molecule molecule): writes and returns a String containing the MOLFile of the given Molecule object
returns String

4e. PDBInterpreter

is a static class for reading RCSB PDB files

static Function readPDB(String content, Number multiplier): reads the PDB file content and returns the corresponding Molecule object; the optional multiplier variable will override the default_anstromsPerBondLength variable, set it to 1 for 3D scenes in Angstroms
returns Molecule

4f. JCAMPInterpreter

is a static class for reading JCAMP-DX files

static Function readJCAMP(String content): reads the JCAMP file content and returns the corresponding Spectrum object
returns Spectrum

5a. Element

is data structure for holding information about an element; parameters not set by the constructor are set by the ElementalData script.

constructor = new Function Element(String symbol, String name, Number atomicNumber)

Number atomicNumber: the atomic number of the element
Number covalentRadius: the covalent radius of the element
Number valency: the maximum valency for an element, or 0 if unknown
Number vdWRadius: the van der Waals radius of the element
String jmolColor: the jmol color of the element
String name: the name of the element
String symbol: the symbol of the element

5b. ElementalData

ElementalData holds two arrays, and sets up the data for the Elements.

symbols, which contains all the element symbols, with each symbol index the corresponding atomic number - 1.
ELEMENT, where the key is the element name, and the data is the corresponding Element object.

5c. Counter

is an interface for calculating integer descriptors given a Molecule object. It should not be instantiated. To obtain a value from a Counter, use the following command where mol is a Molecule object and ChildOfCounter is a child of the Counter class: new ChildOfCounter(mol).value

Function fuse(): a helper method to find the bonds that belong to the perceived rings if only the atoms are specified.
Function setMolecule(Molecule molecule): sets the molecule and performs the descriptor calculation. Should be called as the last method in all child constructors.
abstract Function innerCalculate(Molecule molecule): this method is defined by all child classes of Counter. This method should calculate the descriptor value given the Molecule stored.
Molecule molecule: holds the Molecule object being analyzed by the child derivative
Number value: the result of the Counter algorithm

5d. FrerejacqueNumberCounter

is a child of the Counter class and calculates the Frèrejacque Number, which is the SSSR count.

constructor = new Function FrerejacqueNumberCounter(Molecule molecule)

prototype = Counter

override Function innerCalculate(Molecule molecule): calculates the Frèrejacque Number. This should never be manually called as it is called by the constructor after setup.

5e. NumberOfMoleculesCounter

is a child of the Counter class and calculates the real number of molecules in a Molecule object, which can hold disjoint graphs.

constructor = new Function NumberOfMoleculesCounter(Molecule molecule)

prototype = Counter

override Function innerCalculate(Molecule molecule): calculates the number of molecules. This should never be manually called as it is called by the constructor after setup.

5f. RingFinder

is an interface for ring perception algorithms. It should not be instantiated. Contains helper methods for ring perception and for storing rings. So to obtain a ring set, use the following command where mol is a Molecule object and ChildOfRingFinder is a child of the RingFinder class: new ChildOfRingFinder(mol).rings

Function fuse(): a helper method to find the bonds that belong to the perceived rings if only the atoms are specified.
Function reduce(Molecule molecule): reduces this input molecule graph to discard most non-ring atoms and all lone atoms to speed up runtimes, sets the atoms and bonds Arrays to the reduced graph.
Function setMolecule(Molecule molecule): sets the molecule and performs the ring perception. Should be called as the last method in all child constructors.
abstract Function innerGetRings(Molecule molecule): this method is defined by all child classes of RingFinder. This method should find rings based on the reduced atoms and bonds Arrays and then place perceived rings in the rings Array.
Array atoms: all atoms that will be analyzed during ring perception are stored here, set by RingFinder.reduce()
Array bonds: all bonds that will be analyzed during ring perception are stored here, set by RingFinder.reduce()
Array rings: this array holds all the perceived rings

5g. SSSRFinder

perceives the Smallest Set of Smallest Rings (SSSR) as defined by Plotkin. The SSSR set is not unique. This is not a child of the RingFinder class, as it uses the EulerFacetRingFinder class to perceive rings, and the SSSR is retrieved from that result. It works identically to a RingFinder derivative.

constructor = new Function SSSRFinder(Molecule molecule)

Array rings: this array holds all the perceived rings

5h. EulerFacetRingFinder

is a child of the RingFinder class and perceives a set of rings that defines all Euler facets in a molecule using an algorithm developed by Kevin Theisen. This ring set is thorough, unique and adequately describes rings as a 3D representation of a 2D drawing.

constructor = new Function EulerFacetRingFinder(Molecule molecule)

prototype = RingFinder

override Function innerGetRings(Molecule molecule): implements the algorithm to find the Euler facet ring set. This should never be manually called as it is called by the constructor after setup.
static Number EULER_FACET_FINGER_BREAK: is a cutoff for the size of rings to be found. Defines the length of a ring path which is half of a ring. So a value of 5 specifies that only 8 membered rings and smaller should be perceived. Use this setting to improve performance.
Default Value: 5

5i. HanserRingFinder

is a child of the RingFinder class and perceives all rings within a structure using the algorithm developed by Hanser. This ring set is unique and exhaustively defines every graph cycle. It is very fast for small molecules but does not scale well.

constructor = new Function HanserRingFinder(Molecule molecule)

prototype = RingFinder

override Function innerGetRings(Molecule molecule): implements Hanser algorithm. This should never be manually called as it is called by the constructor after setup.

5j. BondDeducer

is a static class for analyzing bonds

static Function deduceCovalentBonds(Molecule molecule, Number customPointsPerAngstrom): deduces covalent bonds for the input molecule and appends them to the molecule's bonds array. Uses the covalent radii data provided in atomicData. The customPointsPerAngstrom parameters allows you to change the value from that specified by default.
static Function getPointsPerAngstrom():
returns Number
Unit: pixels/Angstrom
static Number LEEWAY: the amount of flexibility in calculating bonds; the larger the number, the more bonds found
Default Value: 1.1
Unit: bond lengths

5k. HydrogenDeducer

is a static class for manipulating Hydrogens

static Function removeHydrogens(Molecule molecule): removes all Hydrogens and bonds attached to them from the given molecule

5l. StructureBuilder

is a static class for copying and creating molecular structures

static Function copy(Molecule molecule): returns a new Molecule object that is a copy of the input molecule
returns Molecule

Contents