Integrating the Library with Frameworks

The default UI provided with the library package is written using Web Components, and it is used on all our sample HTML templates.
But the ChartIQ library can also be integrated with a range of different JavaScript frameworks.

There are several reasons why you might want to use the ChartIQ library with a framework:

  • You want a completely different look and feel from what the web components provide.
  • You're integrating the charts into an existing application that is already implemented in a framework
  • You prefer a deep integration with a UI framework for more control over the individual components.

Whatever your reason, integration with a framework is straightforward if you follow the best practices that are outlined in this tutorial.

Sidebar: Framework Specific Charting Applications vs. Starter kits.

Although both designed to leverage the charting library within a specific framework, Charting applications are different from Starter kits.

  • 'Framework Specific Charting applications' are complete offerings that come with a full featured UI ready to run on React and soon also on Vue, without needing to write any code. They leverage our Web Components and can be requested as an addon to the core API package. Of course, all of the code will be provided, so it is also possible to customize the applications so long as you adequate have web Components development knowledge, in addition the the framework you will be using.

    • Our integration philosophy for our 'Charting applications' is to create reusable 'Custom Elements' that can be plugged into any framework. This allows developers to produce the same look and feel regardless of architecture. To this end, we have created a series of Web components to leverage all key API calls in an advanced UI. Custom Elements allow you to extend HTML and define your own tags. They are the lynchpin in the Web Components specifications. They give developers the ability to define their own HTML elements. When coupled with Shadow DOM, Custom Elements work in any application, including frameworks; which makes them the perfect reusable building block.
    • More details on our WebComponent implementation can be found on the following tutorial: Web Component Interface
  • 'Starter kits', on the other hand, are provided as sample code intended to show how to natively use the charting API within the framework itself, and therefore do not leverage our Web Components at all and instead directly use the API. They only showcase the most popular API calls, but may not include any of the advanced UI functionality available in the 'Charting applications' or advanced templates. Links to these starter kits can be found on the bottom of this document.

The rest of this tutorial is aimed at developers wishing to integrate the library with a particular framework using the starter kits as guidance.

License requirements

All starter kits require a valid charting library package. See the particular starter kits for exact version requirements.

Best Practices

  • Utilize callbacks appropriately to ensure the UI is in sync with the chart.

One of the most common issues when integrating the library with a framework is that the UI and the chart get out of sync after the user changes something. Many frameworks rely on digest loops that often only run under certain circumstances. If you run into this problem, read the documentation for your framework and identify what you can do to manually trigger a digest loop to force the UI to update. Built in callbacks in many ChartIQ library functions are a perfect place to manually trigger a digest loop. You can also use an injection on "draw" in order to ensure that you have the most accurate library state. Please contact our support if you have any trouble!

  • When utilizing data binding features from your framework, bind directly to the library wherever possible.

In other words, try to avoid using an intermediary "store". For instance, bind directly to stx.layout.chartType rather than to your own chartType variable. This removes an often wasteful layer of computation or data reassignment, making your program more efficient. Binding directly to the data in the library will also lessen the chance of your UI getting out of sync.

  • Follow the best practices for your framework.

This is sometimes referred to as programming "idiomatically". Once you choose a framework, you should commit to doing things their way. This will make your code more consistent and readable, much easier to debug, and ensure that you are getting the most out of your framework. For example, different data flow differs among frameworks. Frameworks also often have their own way of looping through collections of data. Whatever way is considered to be most in line with your framework is the way you should do it. Treat the library as a pure JavaScript library (not a UI library) and make calls when needed.

  • Utilize any debugging tools that are specifically for your framework.

Most popular frameworks have debugging tools made specifically for that framework. Some examples of these are chrome extensions for React, Vue.js, and Angular. Consider adding these tools to your development environment to make it easier to view changes within your framework components.

What to know when Minifying, Linting or Packaging the library

If you are:

  • packaging the library into a larger solution using module bundlers such as webpack
  • minifying chartiq.js
  • running the code through a JS linter, typescript linter, and the like

depending on your settings, this may result in errors or warnings.

Here are some suggestions you can try, one at a time, if you do have issues:

  • Read the Working with Module Bundlers Tutorial

  • Don’t 'require' the library:

    One thing that sometimes helps prevent these type of errors is to load the library with a script tag instead of require()ing it. If you load it with a script tag and just access the window globals, then it should not be checked by the tool that is putting out the error. Example:

    <script src="js/chartiq.js"></script>
    
  • Don't 'import' the library:

    Although this may work most of the time, 'import' is not the right approach since our library is currently not packaged as es6 modules. If you must use import, use the following syntax:

    import './chartiq.js'
    

    rather than

    import {CIQ} from './chartiq.js'
    
  • Override default compiler settings:

    Set :

    "allowJs": true
    "checkJs": false
    
  • Instruct your linter to ignore the library files:

    Update your tslint config to ignore imported libraries. Look for a tslint.json file in your project or for a tslint config entry in the package.json.

    It would look something this:

    {
    	"extends": "tslint:latest",
    	"linterOptions": {
    		"exclude": [
    			"chartiq-library-folder/*.js"
    		]
    	}
    }
    

    Adjust it so it will not lint anything in the charting library folder.

  • Our new obfuscation process is very sensitive to file modification. Please do not modify or even remove spaces between characters in chartiq.js, as this may cause syntax errors.

    For example, if spaces are removed form this line:

    case 33: x8m = R8m[1] + +R8m[0]; break;
    

    ​It will become:

    case33: x8m=R8m[1]++R8m[0]; break;
    

    ​The resulting ++ causes a javaScript syntax error.

Next Steps: