Tutorial > Loading Data
Somehow you will need to get chemical data to these JavaScript functions. There are a few ways to do this, some more convenient than others. To begin, let's discuss the data structures that are in play here, the Molecule and Spectrum data structures. These are the data structures that the components in ChemDoodle Web Components take as input. All data structures defined by the ChemDoodle Web Components library reside in the ChemDoodle.structures package.
Before we continue, let's write a small function in JavaScript that takes a Molecule data structure and displays the number of atoms and the number of bonds it contains. This way we can test our progress through the following examples. Remembering the alert() function that we used on the previous page, we are going to create a JavaScript function, named alertMessage(). This function simply pops up the message, "You ran a function!":
<script>
function alertMessage() {
let message = 'You ran a function!';
alert(message);
}
alertMessage();
</script>Note that after we created the function, we then call it. We can call it at anytime and anywhere to execute its function. Click on the Run button above to see the function in action. Now we will extend this function to display information about a Molecule object that is sent to it. We need to add a Molecule object as an incoming parameter (named mol), and we will also change the function name to alertMolecule() to make it more understandable. The Molecule data structure is quite complex, but for now, just know that it contains two arrays, atoms and bonds, that hold its constituent Atom and Bond data structures respectively. The function is written as follows:
<script>
function alertMolecule(mol) {
let message = 'This molecule contains ' + mol.atoms.length + ' atoms and ' + mol.bonds.length + ' bonds.';
alert(message);
}
alertMolecule(new ChemDoodle.structures.Molecule());
</script>Note that when calling the function, we sent in a newly created Molecule object by writing new ChemDoodle.structures.Molecule(). This created a new Molecule from the ChemDoodle Web Components library by correctly finding the Molecule class in the ChemDoodle.structures package. You can click on the Run button above to see this function in action; the new Molecule should have 0 atoms and 0 bonds. Ok, we are ready to load data!
Manually Creating Data
By far, the most tedious and inconvenient method of loading chemical data is by manually creating the data structures. But, this will give us a nice overview of the Molecule data structure, and advanced users of ChemDoodle Web Components will automate this process for powerful functions. The following code creates a hydrogen-depleted methanol molecule:
<script>
let mol = new ChemDoodle.structures.Molecule();
let carbon = new ChemDoodle.structures.Atom('C');
let oxygen = new ChemDoodle.structures.Atom('O');
let bond = new ChemDoodle.structures.Bond(carbon, oxygen, 1);
mol.atoms[0] = carbon;
mol.atoms[1] = oxygen;
mol.bonds[0] = bond;
alertMolecule(mol);
</script>See how tedious that was? Imagine doing this for a Molecule with 10 atoms, or 100!!! Anyway, when you run this script, you will see that the Molecule has 2 atoms and 1 bond. Click the Run button above to validate. There are a couple other downsides to this method as well:
- You will need to fully understand the entire Molecule API to adequately create them.
- There are no coordinates associated with the atoms, and that would make for pretty useless images. You can certainly also set coordinate data this way, but you definitely don't want to be assigning coordinates yourself.
- Molecules are only one type of data structure that you may need to use or visualize.
Loading Chemical Files
A better way to load chemical data is by importing chemical files. JavaScript is run on the client side, so the chemical data will need to be downloaded to the user. There are two common ways to do this, by printing the file content into a JavaScript string or by using the ChemDoodle.io.file package to retrieve the file content from a local url.
After the file content has been defined to a JavaScript string, the ChemDoodle Web Components library can parse the data and generate the corresponding data structure. ChemDoodle Web Components read the following formats natively (iChemLabs cloud services allow all of the chemical formats handled by ChemDoodle desktop to be read and written):
- MDL MOLFiles - have become a standard for basic molecular data. They end with a .mol extension. Use the ChemDoodle.readMOL() function to parse this data and return a Molecule data structure. Both v2000 and v3000 connection table formats are supported.
- MDL RXNFiles - are in the same family of CT files as the MOLFile and stores reaction data. They end with a .rxn extension. Use the ChemDoodle.readRXN() function to parse this data and return an object containing two arrays, molecules and shapes, for loading into Canvases with the Canvas.loadContent() function.
- CML (Chemical Markup Language) - is an open, XML based format for chemistry. They end with a .cml extension. Use the ChemDoodle.readCML() function to parse this data and return an array of molecules for loading into Canvases with the Canvas.loadContent() function.
- XYZ Files - are a common format for storing cartesian coordinates for atoms. There are no bonds in this file format, but the ChemDoodle Web Components will automatically deduce covalent bonds. Use the ChemDoodle.readXYZ() function to parse this data and return a Molecule data structure.
- RCSB PDB Files - contain structural data for molecules, but usually store large proteins and macromolecular structures. They end with a .pdb extension. Use the ChemDoodle.readPDB() function to parse this data and return a Molecule data structure.
- IUPAC JCAMP-DX Files - contain spectral data for mass spectrometry, NMR spectroscopy and IR spectroscopy. They end with a .jcamp or .jdx extension. Use the ChemDoodle.readJCAMP() function to parse this data and return a Spectrum data structure.
- Crystallographic Information Files - contain crystallographic data. They end with a .cif extension. Use the ChemDoodle.readCIF() function to parse this data and return a Molecule data structure and unit cell shape as an object. This function also allows you to create supercells.
There are several ways to print file data to the HTML page. The first is to manually copy and paste the data in. If you need to create the chemical data, then ChemDoodle can help you draw structures and export them to formats that ChemDoodle Web Components understand. ChemDoodle also has additional functionality to compress structure data to JSON protocol for efficiency. You can also use server-side scripts like PHP or JSP to programmatically print chemical data stored on your server to HTML pages before they are sent to the client. This method will download your website and the data to the user during the initial page load.
In the HTML file, a JavaScript string cannot contain new lines, so ChemDoodle Web Components will understand file data where all new lines are replaced with backslash and n character pairs, "\n". This is not a carriage return character, it is two separate characters, a backslash and an n, together in that order.
In the following example, the MOLFile for hydrogen-depleted pyridine has been pasted into the JavaScript source as the pyridineMolFile variable. It is then parsed by the ChemDoodle.readMOL() function and the corresponding Molecule data structure is returned:
<script>
let pyridineMolFile = 'Molecule Name\n CHEMDOOD01011121543D 0 0.00000 0.00000 0\n[Insert Comment Here]\n 6 6 0 0 0 0 0 0 0 0 1 V2000\n 0.0000 1.0000 0.0000 N 0 0 0 0 0 0 0 0 0 0 0 0\n -0.8660 0.5000 0.0000 C 0 0 0 0 0 0 0 0 0 0 0 0\n -0.8660 -0.5000 0.0000 C 0 0 0 0 0 0 0 0 0 0 0 0\n 0.0000 -1.0000 0.0000 C 0 0 0 0 0 0 0 0 0 0 0 0\n 0.8660 -0.5000 0.0000 C 0 0 0 0 0 0 0 0 0 0 0 0\n 0.8660 0.5000 0.0000 C 0 0 0 0 0 0 0 0 0 0 0 0\n 1 2 2 0 0 0 0\n 2 3 1 0 0 0 0\n 3 4 2 0 0 0 0\n 4 5 1 0 0 0 0\n 5 6 2 0 0 0 0\n 6 1 1 0 0 0 0\nM END';
let mol = ChemDoodle.readMOL(pyridineMolFile);
alertMolecule(mol);
</script>When running this script, you will be alerted that the molecule contains 6 atoms and 6 bonds. Notice that the file data in the source code is quite messy, but it is simple, synchronous and straightforward.
Obtain File Content via AJAXIn the ChemDoodle.io.file package, there is a function called content(url, callback). This function works via AJAX (more on AJAX in the next section), so you will only be able to access local files from your website's origin. Each call to this function will also be a separate HTTP connection, which may or may not be appropriate for your website. Regardless, it provides a very convenient method for obtaining file content without messing with server side scripts or string formatting.
In the following example, the ChemDoodle.io.file.content() function is used to retrieve a local MOLFile of pyridine from our server (click on the link to obtain the file). Once downloaded, the string (named fileContent in the code) is sent to the callback function, which is then parsed by the ChemDoodle.readMOL() function to generate the corresponding Molecule data structure.
<script>
// the url is the local path to the chemical file
ChemDoodle.io.file.content('/data/molecules/pyridine.mol', function(fileContent) {
let mol = ChemDoodle.readMOL(fileContent);
alertMolecule(mol);
});
</script>It is important to note, that while less messy that the above method, AJAX is asynchronous, and data will have to be downloaded every time the ChemDoodle.io.file.content() function is called. However, it is much more convenient if you want to simply access files on your server without using server side scripts.
So using these two methods, you can load chemical data from standard files into ChemDoodle Web Components. This method is much less tedious than manually creating the data structures. Other data, such as atom coordinates will also be provided by these files. Of course, you will need access to data files to use them, but you can obtain the files in many ways, one being ChemDoodle.
ChemDoodle JSON
In addition to the 3rd party text based formats that can be read as shown in the previous section, you can also load data in via JSON. JSON is the native JavaScript object notation, and the ChemDoodle JSON format describes how to represent chemical data for the ChemDoodle Web Components in JSON. Please see the ChemDoodle JSON documentation for instruction.
Using iChemLabs Cloud Services
By far, the most convenient way to load chemical data is by using iChemLabs cloud services. ChemDoodle Web Components has built in access to the entire ChemDoodle desktop API through AJAX XMLHttpRequest Level 2 (XHR2) calls to our server. XHR2 requires that our server recognize your origins (domains). Access to our services from academic organizations is free. Otherwise, our rates are very reasonable, please contact us for options.
All iChemLabs cloud services are accessed through the ChemDoodle.iChemLabs package. There are a lot of goodies in that package, but the functions of immediate interest to us are readSMILES() and getMoleculeFromDatabase(). Before we continue, a little background in AJAX is required. AJAX allows a browser to contact a server and update the JavaScript state without reloading the current webpage. This is a very powerful technology. Most AJAX calls will be instantaneous, but it is important to note that this is an additional connection to the internet, and lag can occur for any reason. In the case of lag, we don't want an AJAX call to hold up the loading of a webpage or to prevent responsiveness while the request is being handled, so these calls are made to be asynchronous. This is done by providing a callback function. When the server has finished handling the request, the response is returned to the callback function, which then executes. The following examples will demonstrate this technique.
The readSMILES() function takes a SMILES string and a callback function. You will also notice a blank object as the second parameter ({}). This is the options object, and is used to modify the functionality of the call. We won't be using it for readSMILES(), but we will use it in the subsequent example when we contact a database. There is also full documentation on iChemLabs Cloud services.
When our server finishes parsing the SMILES string, the generated Molecule is returned to the callback function, which then executes its functionality. The following source shows the SMILES string for caffeine being handled:
<script>
ChemDoodle.iChemLabs.readSMILES('N1(C)C(=O)N(C)C(C(=C1N1)N(C=1)C)=O', {}, function(content) {
alertMolecule(content.molecules[0]);
});
</script>The getMoleculeFromDatabase() function takes a query string as parameter as well as options and a callback function. In the options parameter, we will specify the database provider, in this example, PubChem. PubChem ('pubchem'), and our partners ChemExper ('chemexper') and ChemSpider ('chemspider') are supported. When our server finishes retrieving the requested data, the Molecule is returned to the callback function, which then executes its functionality. The following source retrieves the structure of morphine from PubChem:
<script>
ChemDoodle.iChemLabs.getMoleculeFromDatabase('morphine', {
'database': 'pubchem'
}, function(mol) {
alertMolecule(mol);
});
</script>These callback functions merely use the alertMolecule() function. You can make the callback function do much more advanced tasks, including setting the data to other variables which can then be used on the webpage. Both of these functions are much neater and simpler than the previous methods. Make sure to take advantage of them!
Continue to Initializing Canvases →
