Chemiscope as a library¶

It is possible to use chemiscope as a software library when writing your own web-based interface. This page documents how to get the library and provides a few usage examples.

Note

You should also look at the API documentation for a list of all public classes, interfaces and functions in chemiscope.

Dependencies¶

Chemiscope relies on different external dependencies that you should load in all the HTML pages using it. You can serve these from your own web server, or use a CDN to deliver them.

Bootstrap for HTML styling and basic UI;
3Dmol.js relies on the ubiquitous JQuery

Getting and building the code¶

Pre-built version¶

The easiest way to do so is to download the latest release from the release page on GitHub. The main file is chemiscope.min.js, containing the code required to create the default visualizer. This file exports a single global object Chemiscope, which contains references to

Partial builds are also available, in particular molecule-viewer.min.js which only contains code related to Chemiscope.MoleculeViewer, making the minified JavaScript file much smaller. Other partial builds containing only part of chemiscope can be added upon request.

Build from sources¶

Chemiscope is written in TypeScript, a statically typed language which compiles to JavaScript. It uses the standard JavaScript ecosystem tools for dependency management, npm. To build chemiscope from sources, you will first need to get the sources, either as an archive from the release page, or using git

git clone https://github.com/lab-cosmo/chemiscope

You will also need node.js and npm, which you can install with your favorite package manager.

cd chemiscope
npm install
npm run build

This should create a dist directory, containing all the minified JavaScript libraries.

Usage inside a JavaScript project¶

If you already have a JavaScript project using npm or yarn, you can use the version of Chemiscope available on npm. Add it to your project with

npm install chemiscope

And import the library inside your own code using

const Chemiscope = require("chemiscope");

If you are using TypeScript, definition files are also provided with the npm package, and should give you auto-completion, inline documentation and interface checking.

Usage example¶

Below is the minimal HTML and JavaScript code needed to load and use the default chemiscope interface. Additional code would be required to load the dataset, using JSON files or directly.

<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8" />
        <title>Chemiscope basic example</title>

        <!-- Load all dependencies -->
        <!-- jquery -->
        <script
            src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.4.1/jquery.min.js"
            integrity="sha256-CSXorXvZcTkaix6Yvo6HppcZGetbYMGWSFlBw8HfCJo="
            crossorigin="anonymous"
        ></script>

        <!-- Chemiscope code and default viewer code -->
        <script defer type="text/javascript" src="chemiscope.min.js"></script>
    </head>

    <body>
        <!-- Create basic DOM element for the different panels to live in -->
        <div id="meta"></div>
        <div id="map"></div>
        <div id="structure" style="width: 400px; height: 400px"></div>
        <div id="info"></div>
        <!-- We appreciate a citation back to the main chemiscope website -->
        <span style="font-size: x-small; float: right">
            powered by <a href="https://chemiscope.org">chemiscope</a>
        </span>
    </body>

    <script type="text/javascript">
        // show errors in the webpage
        window.onerror = (error) => {
            document.body.insertAdjacentHTML(
                'beforebegin',
                `<div style="margin: auto; color: red;">ERROR: ${error}</div>`
            );
        };
    </script>

    <script type="text/javascript">
        // load data from anywhere
        const dataset = {
            meta: // to be loaded
            structures: // to be loaded
            properties: // to be loaded
            shapes: // to be loaded
            environments: // to be loaded (optional)
        };

        const config = {
            // id of the different elements
            map: "map",
            meta: "meta",
            info: "info",
            structure: "structure",
        };

        document.addEventListener('DOMContentLoaded', () => {
            // once all javascript have been loaded, we can setup the
            // DefaultVisualizer instance.
            Chemiscope.DefaultVisualizer.load(config, dataset);
        });
    </script>
</html>