Candlestick Graph

A small library for displaying OANDA's rate history data in a candlestick chart with a line chart control that allows filtering the candlesticks.

##Browser Compatibility This library has only been testing in Google Chrome v28+.

##Setup Edit demo.html, and set Auth Token and Account ID.

###JavaScript Dependencies Before including the OCandlestickChart file, both oandajs and Google's JavaScript API have to be loaded.

<script src="https://rawgithub.com/mrpoulin/oandajs/update/oanda.js"></script>
<script src="https://www.google.com/jsapi"></script>

Then you can include the library file:

<script src="./OCandlestickChart.js"></script>

###Initialization Google requires that it's API be initialized before using any functions. You must load the corechart and the controls package, along with any other modules your application uses:

<script>
    google.load("visualization", "1.1", {packages:["corechart, controls"]});
</script>

Note: The unstable version (1.1) of both modules is required to stop candlesticks from being cut off at the edges of the graph.

You can also configure oandajs to add a auth token or change the API endpoint URL:

<script>
    OANDA.baseURL = "http://api-sandbox.oanda.com"
</script>

###HTML Structure The candlestick chart requires three DOM elements: one for the candlestick chart, one for the line chart, which must both be wrapped in the same parent container, and an error message container which can go anywhere.

A typical setup may look like this:

<div id="error">
    <!-- Error messages will be displayed here -->
</div>
<div id="parent">
    <div id="chart">
        <!-- Candlestick chart will be displayed here -->
    </div>
    <div id="control">
        <!-- Line chart control will be dispalyed here -->
    </div>
</div>

The parent div holds the 'dashboard', which holds the candlestick chart and the control chart. Feel free to be as creative as you want with the placements, as the two charts will work together as long as they are part of the same parent element.

##Use

###Creating a Chart

After your HTML is set up, you can initialize an OCandleStickChart instance. The constructor is as follows:

function OCandlestickChart(dashElement, chartElement, controlElement, candleOpts, dimensionOpts)

The first 3 arguments are DOM objects where the dashboard, chart and chart control will be rendered, respectively. The candleOpts argument allows you to configure the candlesticks that will be displayed. Finally, the dimensionOpts arguments lets you control the width & height of both the chart and control elements. The format of the candleOpts and dimensionOpts arguments will follow. If not specified, default values will be assumed:

####candleOpts

####dimensionOpts

Note: dimension can be entered as percentiles (strings) or as pixels (numbers).

###Rendering a Chart Once your chart is initialized, you will want to set the chart's render method as Google's onLoadCallback. The proper way of doing is:

var chart = OCandleStickChart(/*...*/);
google.setOnLoadCallback( function() { chart.render(); } );

You can call the render method any time to re-render the chart if necessary.

###Changing Chart Data Currently, the OCandlestickChart class allows you to change the granularity, start time, and instrument of an already created chart. Doing so will cause the chart to re-render with new data.

Note: No error checking is done on any of the values passed to these functions.

###Custom Errors

To display a custom error in the error container, you can call myChart.timedError("Oops", 3000) which will display the error on screen for 3 seconds.

###Enabling Streaming To have the chart update automatically with the latest candlesticks, the streamingEnabled flag can be set to true.

##Utility Functions

Utility functions can be accessed through OCandlestickChart.util.

##Known Issues

• Candlesticks are cut off at the edges of the graph. FIX: Load version 1.1 (unstable) of the visualization library.

• Dragging sliders too close together sometimes causes the x-axis to change to a 10 year scale.

##License The MIT License (MIT)

Copyright (c) 2013 OANDA Corporation

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.