Upgrade Notes

Review the notes to upgrade your ChartIQ library from release to succeeding release.

If you need help, let us know: support@chartiq.com.

Best practices for upgrades

Today's industry leaders are those who are able to identify and blend best of breed solutions which leverage the best technology from an array of firms. This allows your company to stay focused on your core competency instead of spending cycles building solutions for which industry-adopted solutions already exist. For charting needs, ChartIQ's software development kit (SDK) is a highly extensible, customizable product. As such, when implementing ChartIQ, there are certain best practices to keep into account from a development perspective.

We recommend staying as current to the latest release of ChartIQ as feasible; minor and patch releases occur 2-4 times a year, with major versions incrementing every 2-3 years. Though the SDK is designed to be customized, there are development methodologies that will simplify the ChartIQ upgrade process enabling you to provide the best user experience to your clients. These include coding patterns, file organization, and markup considerations.

The customization methodology

ChartIQ is meant to be customized! Very rarely do we see two identical implementations by clients, and we value and support your customization needs. However, there have been instances where significant changes have resulted in difficulty during the upgrade process. By using our customization methodology, your team will have a smoother experience when it comes time to do your routine upgrade of ChartIQ in order to take advantage of our latest and greatest features.

This document will help orient you to how we expect to see customizations to not only streamline your upgrades, but also so that we can be of best service to you if you require support. Remember, our team is only an email away: support@chartiq.com.

Files that change

When upgrading a ChartIQ implementation, certain files inherently change, including the HTML, CSS, and JavaScript files. Not all version upgrades touch all files or necessitate a rework of your customizations, but be aware that these can change. The customization methodology recommended is to modify and extend in separate files from the core provided files.

Don't touch!

ChartIQ's license package is provided as a zip file of a complete HTML/CSS/JavaScript filestack, intended to be hosted on a web server. As such, all ChartIQ files inherently live client-side, and for purposes of security and intellectual property considerations, certain files (most notably chartiq.js, standard,js, and advanced,js) are mostly obfuscated to protect ChartIQ innovations. While it may be tempting to reverse-engineer the obfuscated code, especially during the debugging phase, do not attempt to modify this source code. If problems arise that block your progress moving forward in your development, please reach out to the support team; providing a minimally obfuscated package that makes debugging easier is usually a possibility depending on your contract.

File structure

Most ChartIQ packages are similar to the following file structure. Certain directories have been collapsed for brevity:

.
├── README.md
├── chartiq
│   ├── css
│   ├── examples
│   │   ├── data
│   │   ├── feeds
│   │   ├── help
│   │   ├── markers
│   │   ├── markets
│   │   ├── templates
│   │   └── translations
│   ├── helloworld.html
│   ├── js
│   │   ├── addOns.d.ts
│   │   ├── addOns.js
│   │   ├── advanced-DEV-ONLY-source.js
│   │   ├── advanced.d.ts
│   │   ├── advanced.js
│   │   ├── chartiq-DEV-ONLY-source.js
│   │   ├── chartiq.d.ts
│   │   ├── chartiq.js
│   │   ├── componentUI.d.ts
│   │   ├── componentUI.js
│   │   ├── components.js
│   │   ├── defaultConfiguration.js
│   │   ├── deprecated.js
│   │   ├── extras
│   │   ├── standard-DEV-ONLY-source.js
│   │   ├── standard.d.ts
│   │   ├── standard.js
│   │   └── thirdparty
│   ├── mobile
│   │   ├── README.md
│   │   ├── css
│   │   ├── js
│   │   ├── partials
│   │   ├── sample-template-native-sdk.html
│   │   └── thirdparty
│   ├── package.json
│   ├── plugins
│   ├── technical-analysis-chart.html
│   ├── webpack-example
│   └── webpack4-example
└── chartiq-8.7.0.tgz

For more information on the directory structure, refer to Library Directory Structure.

Tarball

For use in NPM-managed frameworks, the ChartIQ versioned tarball (.tgz file) is available for your NPM installing use. When upgrading from one version to another, it is important to uninstall the previous version and then to install the latest. This is in contrast to many NPM packages, which, when hosted remotely, will usually update themselves. Due to the local nature of the ChartIQ tarball, the following steps should be taken when upgrading:

$ npm uninstall chartiq
$ npm install ./chartiq-x.x.x.tgz

where x.x.x is replaced by the version number in the filename of the tarball.

For more information on npm/tarball, refer to Installing the Library Using npm.

A note on bundle size

It is important to note that, when using the tarballed version of the library, you may find yourself needing to migrate certain files from the node_modules directory to your source code directory and rework some import directives. The reason for this is that the tarball is designed as a fully-fledged implementation of ChartIQ which is basically identical to the rest of the files in the zip package in the chartiq directory. To slim your package and reduce your bundle size, it's recommended to cull unused files and use tree shaking.

Common files and how to use them

Though your package may differ from the above example depending on your ChartIQ entitlements, the main ideas remain: HTML and CSS files (templates) are provided to speed your development process by providing a robust, fully-functional UI; JavaScript files to control interaction; and supplementary plugin, mobile, and other example files for your convenience. Note that the example templates in the /chartiq/examples/templates directory are intended to be moved to the root /chartiq directory before all assets are properly pathed.

Edit these as need be!

The HTML templates are provided for your use and convenience; they should serve you well as a jumping-off point for your own customizations, though certain new features and developments within ChartIQ may depend on modified or additional HTML. Be prepared to take note of extensive customizations and, ideally, document their previous state. Do take note that certain features are dependent on their corresponding markup, so be sure to test often when making alterations to the HTML.

Extend, don't edit

ChartIQ's templates are built using W3C standard web components (read more about them in our documentation) and so they inherently have functionality and styling ascribed to them by supporting CSS and JavaScript files. Of most note are the files /chartiq/js/componentUI.js and /chartiq/js/components.js. These files contain JavaScript classes for the UI components of which the templates are composed. Let's consider an example.

In components.js, you can find a class definition for Comparison. If you're unfamiliar with the component, Figure 1 is a quick screenshot of it.

Comparison web component
Figure 1. The Comparison web component is a symbol picker for adding a comparison series to the chart.

Figure 2 shows the methods that make up the Comparison class. For the purposes of this example, we'll tackle a small customization to the Comparison class: a simple console.log of the data received by the component as well as automatically displaying the comparison as a mountain chart instead of a line chart.

Comparison web component anatomy
Figure 2. Comparison web component anatomy.

When extending web components, it's not necessary to copy the entire class. Instead, we can leverage the object-oriented nature of JavaScript's classes to only rewrite the parts that we need. By exposing the source code of the components, ChartIQ's methodology aims to help you write less code as you modify your components.

Let's look at the code of the extension. In a new file (let's name it /js/customizations.js), we'll add the following code:

01: import { CIQ } from "./standard.js";
02:
03: class CustomComparison extends CIQ.UI.components('cq-comparison')[0].classDefinition {
04: 	constructor() {
05: 		super();
06: 	}
07:
08: 	selectItem(obj) {
09:
10: 		// @Customization
11: 		console.log(obj)
12:
13: 		var context = this.context;
14: 		var self = this;
15: 		function cb(err, series) {
16: 			if (err) {
17: 				series.parameters.error = true;
18: 			}
19: 			self.loading[series.parameters.symbolObject.symbol] = false;
20: 			self.renderLegend();
21: 		}
22: 		var swatch = this.node.find("cq-swatch");
23: 		var color = "auto",
24: 			pattern = null,
25: 			width = 1;
26: 		if (swatch[0]) {
27: 			var style = swatch[0].style;
28: 			color = style.backgroundColor;
29: 			pattern = style.borderTopStyle;
30: 			width = style.width || 1;
31: 		}
32: 		var stx = context.stx;
33: 		this.loading[obj.symbol] = true;
34: 		var params = {
35: 			name: "comparison " + obj.symbol,
36: 			symbolObject: obj,
37: 			isComparison: true,
38: 			color: color,
39: 			pattern: pattern,
40: 			width: width || 1,
41: 			data: { useDefaultQuoteFeed: true },
42: 			forceData: true,
43: 		};
44:
45: 		// don't allow symbol if same as main chart, comparison already exists, or just white space
46: 		var exists = stx.getSeries({ symbolObject: obj });
47: 		for (var i = 0; i < exists.length; i++)
48: 			if (exists[i].parameters.isComparison) {
49: 				this.loading[obj.symbol] = false;
50: 				return;
51: 			}
52:
53: 		// don't allow symbol if same as main chart or just white space
54: 		if (
55: 			obj.symbol &&
56: 			obj.symbol.trim().length > 0 &&
57: 			(!context.stx.chart.symbol ||
58: 				context.stx.chart.symbol.toLowerCase() !== obj.symbol.toLowerCase())
59: 		) {
60: 			stx.addSeries(obj.symbol, {...params, renderer: "Lines", type: "mountain"}, cb); // @Customization
61: 		} else {
62: 			this.loading[obj.symbol] = false;
63: 		}
64: 	}
65: }
66:
67: CIQ.UI.addComponentDefinition('cq-comparison', CustomComparison);

The first thing to note is the extension of cq-comparison, the name of the web component in the markup. That is, when adding the web component to the page, you will include the HTML tag <cq-comparison></cq-comparison>. By modifying only the selectItem method, we can leverage the whole web component while only modifying lines 11 and 60.

We then include the extended web component in the page's markup:

import "./js/customizations.js";

and we're able to leverage our component's changed functionality:

Modified web component
Figure 3. Using the modified web component.

By extending the web component's functionality, you will be able to accommodate for changes to the components.js file during upgrades, as you will not have modified the core file.

The upgrade path

With each release of ChartIQ, the Upgrade Notes are added to, showing the various differences to account for from version-to-version. It is highly recommended to stay within one to two versions of the library to keep the upgrade process smooth and reduce the number of sweeping changes necessary when falling behind. When properly customized and regularly updated, the upgrade process can take as little as a few hours to complete.

The exact path you take to upgrade your ChartIQ instance may take several forms, depending on how you've customized the implementation. At a minimum, the ChartIQ JavaScript files should be replaced with the latest versions. Since you've extended the functionality instead of modifying core files, the upgrade process should consist of replacing the JavaScript files.

For user interface (UI) customizations or to implement features that depend upon HTML/CSS, it is recommended to take a close look at the HTML of the template in the new package and compare and contrast it with your customizations. In most cases, you will be able to activate new features that depend on a new web component by placing the appropriate web component tag in place in your HTML.