Sway Charts Pro Scripts Documentation
  • Sway Charts Pro User-Defined Indicators
    • Introduction
      • 1.1 Access to the Sway Charts scripting framework (UDI vs UDIX)
      • 1.2 Example UDI code
      • 1.3 Adding a UDI to a chart
      • 1.4 Lifecycle
      • 1.5 Alerts
      • 1.6 Indicator-on-indicator
      • 1.7 Technical note: web workers
      • 1.8 Technical note: dates
    • Initialisation: UDI.onInit()
      • 2.1 Return value from UDI.onInit()
      • 2.2 The plots[] array
      • 2.3 The settingsFields[] array
      • 2.4 Context data passed to UDI.onInit()
    • Calculating data: UDI.onCalculate()
      • 3.1 Reading settings fields
      • 3.2 Input data for the UDI
      • 3.3 Updates of the current bar only
      • 3.4 Calculating output data
      • 3.5 Requesting out-of-band updates
      • 3.6 Technical analysis: moving averages, ATR etc
    • Changes to the chart or parameters
      • 4.1 UDI.onContextChange()
      • 4.2 UDI.onParameterChange()
    • Creating drawings, event markers, and bar highlights
      • 5.1 Creating drawings
      • 5.1.1 Drawing properties
      • 5.2 Creating event markers
      • 5.2.1 Click notifications from event markers
      • 5.3 Creating bar highlights
    • Notifying the user
      • 6.1 Creating toast
      • 6.2 Changing the panel background colour
    • Adding HTML to the chart
      • 7.1 Adding HTML
      • 7.2 Positioning the HTML
      • 7.3 Sending messages from the HTML to the UDI
      • 7.4 Sending messages from the UDI to the HTML
    • Recommended trade
      • 8.0 Recommended trade
    • Other indicator topics
      • 9.1 Collecting external data
      • 9.2 Converting dates to chart time
      • 9.3 Multi-timeframe (MTF) indicators
  • Sway Charts Pro Framework
    • Examples
    • Collections, objects, and properties in the framework
    • Functions in the framework
    • Messages and event handlers
    • Working with candle data
    • Widget HTML and CSS reference
    • Sway.utils and other helper functions
    • Framework error codes
    • Script contexts
    • Sending mail into Sway Charts Pro from outside the platform
    • language variables
Powered by GitBook
On this page
  • 3.1 Price requests
  • 3.2 Historic candle data
  • 3.3 Trading
  • 3.4 Account history
  • 3.5 Dialogs
  • 3.6 Settings and state storage
  • 3.7 Interacting with the Sway Charts Pro page container and environment
  • 3.8 Communicating between widgets/scripts/UDIXes
  • 3.9 Time conversion functions
  • 3.10 Helper functions for formatting values
  • 3.11 Trading validators
  • 3.12 Market depth and order book
  • 3.13 Economic calendar
  • 3.14 The Sway Charts Pro mail system
  • 3.15 Miscellaneous functions
  1. Sway Charts Pro Framework

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.