Before starting, 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
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 template
The ChartIQ SDK (zip file) contains two templates: template-basic.html and template-advanced.html. These are built using W3 WebComponents. They require JQuery.
template-advanced.html is a fully functional chart and user interface. Use template-advanced.html if you don't want to build your own user interface. Cut and paste the code into your app. Then, customize the look and feel with CSS. Remove any html that you don't want.
template-basic.html is a stripped down example. It is easier to understand how ChartIQ uses Web Components in this simplified example.
2) Clone a ChartIQ "Seed Project"
If you're programming in Angular, React or iOS, you will probably want to start with a ChartIQ seed project. 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!
Note: Android, Java, .Net? 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.
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)
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 create a chart.
- You must provide a for the chart. We call thisthe "container". The chart will automatically fill up the container.
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!
- The chart engine will create some html elements (canvas, crosshairs, zoom buttons, icons, etc) and add them to thethat you provided. You can control these with css. Your container must have
position:absoluteotherwise these elements won't show up correctly.
stxx.newChart("IBM")is how you programatically change the symbol for a chart. 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>
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 displayed 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.