5.1.2Loading data into the candle store

There are three ways of loading data into an FXB.CandleStore. Firstly, you can take the asynchronous response from RequestCandles() and pass the candles[] array from the response message into the LoadCandles() function in the FXB.CandleStore. For example:

Framework.$myCandleStore = new FXB.CandleStore();

var candleRequest = { … some candle request … };

Framework.RequestCandles(requestDef, function (Msg) {

if (Msg.candles) {

// Process both an initial response to the candle request

// and also streaming updates with changes and additions

Framework.$myCandleStore.LoadCandles(Msg.candles);

} else {

// No candles[] array. Some problem with the request.

}

});

LoadCandles() can be used both with the initial response to a candle request and also any subsequent streaming updates which contain modified or new candles.

In addition to setting up event handlers, you can detect changes in the store by looking at the return value from LoadCandles(). This can be one of the following values:

Return value	Description
-1	Load failed. Invalid candle data.
0	No change
1	Only the current, in-progress candle has changed
2	A new, latest candle has been added to the store. (As with the OnNewCandle() event, there may also have been a final update to what was previously the current candle.)
4	Initial load
6	Load of new candle data which both modifies the history and also adds new current or later candles

The second way of loading data into the store is to assign the candle store as the second parameter to RequestCandles(), instead of providing a callback function. For example:

// Create a candle store

Framework.$myCandleStore = new FXB.CandleStore();

var candleRequest = { … some candle request … };

// Pass the response(s) from RequestCandles() directly into the FXB.CandleStore,

// without using an asynchronous callback function or needing to process the messages manually:

Framework.RequestCandles(requestDef, Framework.$myCandleStore);

There are two special considerations here, resulting from the fact that you don't receive the response messages from RequestCandles().

The framework puts the ID of the candle request into the FXB.CandleStore as a candleRequestId property. If you need to terminate a streaming request, you can do so using Framework.TerminateCandleRequest(store.candleRequestId)

If the candle request fails, the framework fires an OnLoadError() event in the candle store.

The third way of loading candles into a store is to provide a candles[] array in the initialisation of the store. For example:

// Note: this method will only normally be suitable for static candle requests,

// not streaming requests where there are multiple callbacks

var candleRequest = { … some candle request … };

Framework.RequestCandles(requestDef, function (Msg) {

if (Msg.candles) {

// Create a store, populating it with the candles[] array

Framework.$myCandleStore = new FXB.CandleStore({

candles: Msg.candles,

… any other properties you want to assign

});

} else {

// No candles[] array. Some problem with the request.

}

});

You can load candle data of your own into an FXB.CandleStore as well as passing in candle data from the framework. To do this, you provide an array of candle objects, each of which - like the framework's own candle data - must contain ts, o, h, l, and c values (plus, optionally, v).

Finally, the FXB.CandleStore also has special support for User-Defined Indicators, which receive bar data as separate arrays, in data.barData.open[], data.barData.close[] etc, rather than as an array of candle objects. In the UDI.onCalculate() function you can pass the data parameter into a candle store, and that will combine the separate arrays into a list of candles. For example:

UDI.onCalculate = function(data, output) {

var cs = new FXB.CandleStore({candles: data}); // Can also use LoadCandles(data)

};

It's then possible to do things such as extracting derived prices from the store, such as GetValueArray("median"), or to pass the candle array into a bar-based technical analysis calculation.