First, install the ChartIQ library
Now that you have the library installed, here are a few pieces of information that will help you understand how best to use the ChartIQ SDK and why the library works the way it does.
The SDK's focus is on highly interactive charts
An interactive chart is one that can be panned and zoomed quickly and easily by the end user. The end user can add content to the chart (studies, comparison symbols). The user can quickly flip between symbols. The user can change chart type, range, interval, etc. The libraries API, data model, layout are all based on this underlying requirement. This may differ from other charting tools that are focused primarily on static charts.
The SDK's focus is on charting market data (aka "stock charts")
Many choices in API design and interactivity defaults have been made with a preference towards traders. In particular, the charts are optimized for technical analysis (the use of charts for trading securities). For instance, the data model assumes Open, High, Low and Close values. Other charting tools are typically focused on generic "time series" charting (for instance, charting temperature over the past century). ChartIQ can be used for generic time series charting (analytics for instance) but the API is intended to make stock charting the easiest.
You host the library. You provide the [market] data.
You will receive the ChartIQ SDK as a zip file which contains the library (chartiq.js), UI templates, examples and support files. You host the the library on your own servers, as part of your application. You must provide a source of data. Typically, the source of data is a "market data server".
An "event based" data model is recommended for highly interactive stock charts
Highly interactive charts require fetching data in response to user activity - changing symbol, adding a comparison, changing interval, paginating, streaming. Managing the "state" of a chart can quickly become difficult, so we've designed the library to manage its own state. Instead of feeding data into the chart, the chart will ask you for the data it needs (you write code called a "quotefeed" to do this). This is very different than most charting tools. It requires a little bit more effort and understanding at the beginning but saves a lot of work.
ChartIQ makes a distinction between "the chart" and the "UI" that controls the chart
The charting library creates a chart inside of a
div tag. The chart can be controlled either by a user interface (menus, dialogs, symbol entry) or it can be controlled with the API (calling functions). The UI is optional. This is different than many stock charting tools that come with a hard coded user interface (which probably would look terrible in your app!)
There are three (3) UI methodologies. Pick the right starting point for your application!
Note: All of these methodologies use the same data model. This is a decision on (1) how you want your app to look and (2) how you wish to architect your app.
1) Cut & Paste a sample HTML template
The ChartIQ SDK (zip file) contains two main sample templates:
sample-template-advanced.html, a fully functional chart and user interface. Use sample-template-advanced.html if you don't want to build your own user interface.
sample-template-basic.html, a stripped down example. It is easier to understand how ChartIQ uses Web Components in this simplified example.
They are built using W3 Web Components and require JQuery.
Before you start working with the Web Components, please review the Web Component Interface tutorial.
We also have the following additional templates to further illustrate other integration approaches:
sample-template-instant-chart.html, is an example of how to use ChartIQ's "instant-chart" web component. An instant-chart is a fully functional chart, with user interface, that can be dropped onto a web page with a single tag.
sample-template-multi-charts.html, is an example of how to use ChartIQ's "instant-chart" web component in a milti-chart environment. Alternatively, you can also implement multi-charts using individual Web Components or your own UI for each chart engine.
Above two templates require
instant-chart.html, also provided.
sample-template-instant-chart.htmlis configured to run within
sample-template-multi-charts.html, so final initialization of advanced functionality is done once in
sample-template-multi-charts.htmlonly. If running
instant-dialogs.htmlas a standalone template, please be sure to initialize this advanced Functionality directly on the page in the same way it is done in
The templates are provided as sample code to illustrate how the raw library API can be used to create web components for your UI. These examples are fully functional and can be used unchanged as provided. You can also just use them as reference to write other interfaces, or modified them as needed to meet your needs. We can provide all the code in plain text for you to review. Just ask!
So cut and paste the code into your app and customize the look and feel with CSS and by adding, removing or modifying any Web Components functionality.
More details on the sample Web Components provided with your library package can be found here: WebComponents
Customization guidelines and instructions can be found here: Customization Basics
If you're programming in Angular, React, Java or developing a mobile application, you will probably want to review a ChartIQ starter kit. These are public Github repos that you can clone or fork. Each project contains examples that demonstrate ChartIQ's recommended approach for the framework. We've also built components for all the hard stuff!
Before you start working with these tips, please review the Integrating with Frameworks tutorial.
For the mobile kits, the library package also includes helper files and templates to help you get going:
js nativeSdkAccessibility.js: an add-on for nativeSdkBridge.js that will help hook into the voice accessibility mode in both Android and iOS and allow for custom announcements of quotes.
sample-template-native-sdk.html: is nearly identical to
Note: Java, .Net, Electron, CEF, other ways to encapsulate the library? We got you covered! See Webviews and Containers.
3) Use the raw API
With code, you can control the chart any way that you desire. It is easy to retrofit an existing UI to use ChartIQ, or to build your own UI from scratch. This might be the best path if you have a complicated application (for instance an app that simultaneously display multiple interactive charts).
helloworld.html demonstrates how to create a chart with just a few lines of code.
See the Implementing UI tutorial for more information.
Important: sample templates use simulated data !!!
The sample templates provided the library package are shipped with certain default settings that allows them to immediately run with sample data right out of the box. You will need to create new interfaces and adjust defaults to ensure proper use of your own data.
####Here is an outline of the settings you should review and adjust:
- Market Data source. By default the sample templates are connected to a quote feed simulator. You must create a quoteFeed interface to load your data.
- Timezones. Make sure your data matches the desired timezone for the charts.
- Market Hours/Definitions. By default, the sample templates will try to set market hours for each symbol newly loaded using CIQ.ChartEngine#setMarketFactory and leverage default Symbology Rules which also need to be adjusted to comply with your symbol format. Alternatively, remove CIQ.ChartEngine#setMarketFactory to always render a 24/7 chart.
- Symbol lookup data source. By default the sample template links to a sample lookup server which delivers instruments that will match the quote simulator. You need to create a lookup driver that will deliver a list of symbols compatible with your quote feed.
ChartIQ's documentation includes a full API reference and numerous tutorials. We also have a huge collection of jsfiddles. Before you dig in, here are some basic facts and recommendations to get you started:
js\chartiq.jsis the core library. You can include this with a script tag or using AMD (require.js). Never make any changes to this file.
css\stx-chart.cssis required by the library. The charting library uses the css from this file to determine colors and styles for the chart (candle colors, line colors, crosshair styles, etc). You should include this in your application. We recommend not changing this css file. If you wish to change a chart style, simply override the css style with your own css.
CIQis the ChartIQ namespace.
CIQ.ChartEngineis what you will use to instantiate a chart engine.
- You must provide a
<div>for each chart engine. We call this
- The chart engine will create some html elements (canvas, crosshairs, zoom buttons, icons, etc) and add them to the container that you provided. You can control these with css. Your container must have
position:absoluteotherwise these elements won't show up correctly.
stxxis the variable name that we use in our examples for a chart instance. You'll see this everywhere in our tutorials and code examples!
stxx.newChart("IBM")is how you programmatically load a chart for a particular symbol. Usually your "quotefeed" will fetch the data. CIQ.ChartEngine#newChart
$$$is a shortcut for
document.querySelectorthat is included with the library. You can of course use jquery but be sure to return the actual element
Here is a basic example:
<link rel="stylesheet" type="text/css" href="css/stx-chart.css"> <div id="myContainer" style="position:relative;width:600px;height:480px;"> <script src="chartiq.js"></script> <script> var stxx=new CIQ.ChartEngine($$$("#myContainer")); stxx.attachQuoteFeed(quoteFeedSimulator); stxx.newChart("IBM"); </script>
See it working and experiment with it here
Throughout the documentation, we make use of terminology that is related to charting. You can refer back to this glossary as you encounter new terms while you read through the documentation.
OHLC- Open, High, Low, Close are the typical values displayed on stock charts.
data point- A horizontal location on the chart. Each "bar" represents activity across a timeframe we call "periodicity".
interval- The timeframe represented by each "bar" that is sent by your data server (for instance "1 minute bars", "5 minute bars", "daily bars")
periodicity- The timeframe represented by each bar/candle/datapoint on a chart. Usually this is the same as interval, but bars can be "rolled up". For instance, the chart can display "monthly" bars from daily data.
range- The visible date range across the entire chart. For instance, from January 1st through January 31st.
span- The amount of time displayed across the entire chart. For instance, a chart that displays January 1st to January 31st has a span of "1 month".
symbol- The string that represents a stock symbol. This is passed to stxx.newChart(). Most firms have their own "symbology". Often symbols will combine different pieces, for instance "AAPL.LSE" might represent Apple on the London Stock Exchange. Another firm might represent this as "AAPL LON". If you need more than one field, you can use a
symbolObjectinstead of a symbol. See: symbolObject.
data server- A source for market data. For instance, a remote server that delivers an array of OHLC bars over a network connection( i.e. Ajax or a WebSocket).
quotefeed- An object you build as a developer to integrate your server's data into the charting engine. See Next Steps below.
masterData- The OHLC data array underlying the chart.
series- Additional data, such as comparison symbols, that is added to the masterData
indicator- A formula that is applied to the masterData which produces an additional visual on the chart. These can be
overlayswhich are superimposed on the chart or they can be
panel studiesthat display in individual panels stacked below the chart.
dataSet- A copy of the masterData array that has been supplemented with the results of study formulas and series.
dataSegment- The portion of a dataSet that is rendered on the screen. This will move as the user navigates the chart.
streaming- Adding more data to the end of a chart as time progresses.
pagination- Prepending data to the beginning of a chart as a user scrolls back in time.
callbacks- Functions that the chart can call when certain events occur (i.e. click, move, new symbol)
injections- Custom code that you can write to modify the libraries behavior, using
drawings- Drawings that a user makes on a chart, such as line, annotation (text) or Fibonacci.
markers- DOM elements that can be attached to the chart so that they move as a user navigates the chart.
TFC- Trade From Chart plugin (module) that can be enabled for "visual trading".
- Connect your data - Your first step is to integrate your market data into the charting library. Start by reading Integrating Data into Charts.