Loading Amchart5 and Other External Libraries via Script Tags in Plugins
This article explains how to load external libraries, such as Amchart5, into Sisense plugins, such as plugins that create new custom widget visualization types, by dynamically adding script tags to the page header to load the library. This method can avoid potential issues associated with other loading techniques but also offers flexibility such as using an external CDN to reduce plugin size and file count. Previous articles have discussed how to load external libraries and modules for Sisense plugins via adding the file to the plugin folder, and adding the file to the "source" parameter array in the plugin.json.
What Is a Script Tag?
A script tag is an HTML element (<script>) used to embed or reference JavaScript code in an HTML document. When you include a script tag with a src attribute, the browser downloads and executes the external JavaScript file.
Why Use Script Tags for Loading External Libraries?
For certain JavaScript libraries, especially visualization libraries like Amchart5, loading the library via a script tag can help avoid issues that might arise from bundling the files directly into the plugin. The script tag method provides several benefits:
- Flexibility: It allows the option of using an external CDN. This can reduce the size of the plugin package and the number of files you need to manage.
- Auto-Updating: When using a CDN, the external library can be updated automatically without modifying the plugin.
- Self-Hosting Option: Alternatively, you can set the src parameter to a local path of JavaScript files uploaded within the plugin, ensuring that the plugin remains fully self-hosted and independent of any CDN.
Loading External Libraries: Self-Hosted or Using a CDN
Self-Hosted: The script’s src is set to point to the files within the plugin folder. This follows this very specific format:
/plugins/${name_of_plugin_folder}/{Any_subfolders_if_needed}/{full_name_of_the_file}This approach makes the plugin self-contained and avoids external dependencies. The src path must follow this format.
CDN-Hosted: The src parameter is set to the URL of the external CDN, such as:
https://cdn.amcharts.com/lib/5/xy.js
Using a CDN can reduce the plugin’s file size and benefit from auto-updating libraries, though it introduces a dependency on the CDN’s availability.
Example Loader Script
Below is an example of a loader file (loader.6.js) that dynamically adds script tags to the page header to load Amchart5 and its modules (AM5 is loaded in this example, as well as additional AM5 modules dealing with axises and animation, this is a self-hosted example and does not rely on a CDN).
// List of script URLs to add to the page header
const scriptUrls = [
"/plugins/am5Example/am5/index.js",
"/plugins/am5Example/am5/xy.js",
"/plugins/am5Example/am5/themes/Animation.js"
];
// Function to add a script tag to the header
function addScriptToHeader(url) {
const script = document.createElement("script");
script.src=url;
// Optionally set async or defer attributes if needed
script.async = false;
document.head.appendChild(script);
}
// Loop through each URL and add it to the header
scriptUrls.forEach(url => addScriptToHeader(url));
This can be modified to occur on a specific prism and dashboard event, as opposed to immediately when the plugin loads.
In this script:
- document.createElement("script"): Creates a new script tag.
- script.src: Specifies the source of the JavaScript file.
- document.head.appendChild(script): Adds the script tag to the Sisense page header.
- The async attribute is set to false to ensure that scripts load in the order they are added.
Configuring plugin.json
In your plugin’s plugin.json, reference the loader file and the library file itself. The loader file then adds the necessary external scripts. An example plugin.json configuration is shown below:
{
"name": "am5Example",
"pluginInfraVersion": 2,
"isEnabled": true,
"source": [
"am5/loader.6.js"
],
"folderName": "am5Example",
"version": "1.0.0"
}
This setup makes the external library (Amchart5, in this case) available to your plugin without bundling the entire library directly into the main codebase.
Conclusion
Using script tags to load external libraries like Amchart5 provides a flexible method for managing dependencies in Sisense plugins. Whether the libraries are self-hosted or rely on an external CDN, this method simplifies the management of external scripts and can lead to more efficient plugin development, and avoid issues with specific libraries such as Amchart5 that work best when loaded as a script element.
The example plugin that demonstrates this type of loading is available for download below.
