Functions in the framework
The External Widget example in Sway Charts Pro and some of the code in this guide assigns extra ad-hoc functions and properties into the Framework object. For instance: Framework.$DisplayPrices and Framework.$currentInstrumentId in the External Widget example.
The example code prefaces such property and function names with $. This is absolutely not compulsory (and nor does it have any special meaning in Javascript). It is done for two reasons:
· It makes it clear which functions are built into the Framework object versus which are private additions by the widget (or script or UDIX).
· It avoids accidental collision with the names of built-in members, which would delete and replace them. For example, choosing to overwrite Framework.Instruments or Framework.SendOrder with your own data or function would be a problem. If you preface names with $ then the only possible overlap is with the framework's own $T() helper function.
As described in the introduction, all functions in the framework which generate asynchronous callbacks exist in two versions: a "standard" version with a callback function as a parameter, and a version which issues a Javascript Promise. This guide mainly describes the standard versions. If you want to use the Promise versions, then apply the following rules to the documentation below:
· The Promise version of the function starts with p, e.g. pRequestCandles() instead of RequestCandles()
· The callback is dropped from the function's parameter list (and replaced by returning a Promise). For example, pRequestCandles() takes a single parameter: the definition of the candle request. Similarly, pSendOrder() takes either one or two parameters: the compulsory description of the trading request, and optional settings regarding how the request is processed.
· Any dialog function which returns both an initial update and a final result is modified in the Promise version so that it only returns the final dialog result.
3.1 Price requests
Prices, in the Framework.Instruments collection, do not automatically update. You do not automatically receive new prices for all available markets in the platform.
You need to request prices which you are interested in, using Framework.RequestPrices(). This function takes an array of the instrumentId values which you want. For example:
// Request EUR/USD
Framework.RequestPrices(["EUR/USD"]);
// Replace with request for EUR/USD and GBP/USD
Framework.RequestPrices(["GBP/USD", "EUR/USD"]);
If you only want the price for a single instrument, you can pass a string as the parameter, rather than an array:
// Single request, as a string rather than an array
Framework.RequestPrices("EUR/USD");
You can receive the prices either by listening for PRICE updates in the main OnMessage handler, or by defining a specific OnPriceChange handler.
You can also make a specific one-off request for the latest price on a market, using GetLatestPrice(). This takes an instrumentId and an asynchronous callback. For example:
Framework.GetLatestPrice("EUR/USD", function (Msg) {
// Same as a PRICE message: contains a quotes[] array with the single, requested market
});
If the framework has already been asked to collect prices for this market from the broker server, the response back to your asynchronous function will be nearly instant because the framework already has the latest price. If not, the framework will request the price from the broker server and then issue a more delayed callback to your function.
Using GetLatestPrice() also sets up a streaming subscription, as well as collecting the latest price.
3.2 Historic candle data
This section describes how to request candle data from the framework. There is a separate section below about features to help you work with that candle data: storing it, adding technical analysis calculations etc.
You can request chart/candle data using Framework.RequestCandles(). The RequestCandles() function takes two parameters:
Parameter
Description
requestDef
Details of the candle request: market, timeframe etc
callback
Callback function which asynchronously receives the requested data (and then further updates depending on the type of request)
For example:
// Request latest candles on EUR/USD H1 (a default number of candles filled in by the framework)
Framework.RequestCandles({
instrumentId: "EUR/USD",
timeframe: 3600
}, function (MsgCandles) {
// Function which asynchronously receives the candle data from the framework
});
There are three types of candle request:
· The most common: a request for the last N candles up to the current time, e.g. in order to display a trading chart.
· A request for the N candles up to a historic point in time, e.g. in order to add further history when a user scrolls back in time on a chart
· A request for the candles between start and end dates.
All requests must include an instrumentId and a timeframe (as in the above example). These are the only compulsory properties in a request.
The list of available timeframes depends on the account and trading back-end which Sway Charts Pro is connected to. This information is provided in the account features.
A request for N candles (up to the current time or a specific historic date) can include a count property specifying how many candles you want. However, we recommend that you omit this unless absolutely necessary, and let the framework pick a value for you. The cost of collecting candle data can vary based on the back-end system. If you omit count, the framework has discretion to make a smaller or larger request depending on how quickly the back-end system processes requests. As a general rule, count should not exceed 1000. If you need more candles than this, request them in separate batches (going backwards in time as each batch is received).
You can specify a start date and/or end date for the candle request using startDate and endDate.
If you make a request for candles up to the current time then, by default, the request will stream: your callback function will get an initial call with the existing candle data, and will then get further calls on each change in the market price – updating the current candle or adding a new candle. If you don't require streaming, you can turn it off by specifying noStreaming:true.
In full, the possible properties of a candle request are therefore as follows:
Property
Description
instrumentId
ID of the Sway.Instrument for which you want data
timeframe
Chart timeframe, such as 3600
count
Number of candles (not applicable if startDate is provided)
startDate
Start date for historic request. If provided, must also set endDate.
endDate
End date for historic request
noStreaming
Optional flag which can be used to turn off streaming on requests. (Automatic if a request has an endDate.)
requestId
Optional ID for the request, repeated back in messages to the callback function. If not provided, the framework will allocate one automatically. If you want to allocate your own ID, you are recommended to use Sway.utils.GenerateGuid().
timezone
Optional time zone settings for the request. See below.
convertTimes
Option to do conversion of UTC times before returning the data. See below.
Note: the Promise version of the function, pRequestCandles(), always sets noStreaming:true because a Promise cannot settle more than once; it cannot receive multiple callbacks with streaming data.