1Framework fundamentals

You can use the Figaro framework to build trading algos, indicators for charts, and whole new tools within the Figaro platform.

The Figaro framework provides three types of software development:

Widgets. All the built-in tools in Figaro - charts, quote board, trade list etc - are widgets, and any widgets which you create have access to all the same features as built-in widgets.

Scripts. You can create and save scripts using the Run Script widget in Figaro. Scripts can be given icons in the platform's banner, and can be set to start automatically when the platform is loaded. (Scripts can also be given a context, so that they are available in specific places within the Figaro platform.)

User-defined indicators, for charts.

User-defined indicators subdivide into two types:

Standard indicators (UDI), which only have access to the chart on which they run.

Enhanced indicators (UDIX) which also have access to the Figaro framework described here. They can see data such as the trade list, and they can carry out actions such as placing trades.

Creating indicators is described elsewhere, at https://www.fxblue.com/figaro/udi/help. A UDIX is simply an indicator which also has a Framework object, in addition to the indicator features which are described separately. You choose whether to give a UDI access to the Framework, turning it into a UDIX, when you add it to a chart.

In terms of the web browser:

Widgets are iframes (sandboxed). A widget is simply an HTML document which integrates with Figaro by including the framework script and CSS.

Scripts and UDIXes are web workers. They have no user interface of their own, but they can create dialogs and interact with the platform.

Figaro is a web-based platform, and therefore the programming language for creating widgets, scripts, and UDIXes is simply Javascript. You can also write your code in any language such as TypeScript or CoffeeScript which compiles to Javascript.

You can use any development environment, from Notepad to Visual Studio or Eclipse. You can paste HTML/Javascript into the Run Script and External Widget windows in Figaro. You don't have to write your code inside the Figaro platform.

Note: in addition to the facilities described here for extending the Figaro platform, it is also possible to use the Excel RTD widget to write code outside the Figaro platform, in any language of your choice such as Node.js, C#, or Python, communicating with the web browser using HTTP or websockets. It is even possible to download data directly into Excel without any programming. For more information, see the document about the Excel RTD widget:

https://www.fxblue.com/figaro/excel-rtd/help

1.1Examples

The Figaro platform contains examples of scripts, of a widget, and of a UDI (but not specifically a UDIX). You can use these as a starting point in addition to this guide.

The Run Script widget lets users without programming experience nevertheless create scripts from common actions such as placing trades, and then save those scripts for future use, make them accessible as icons in the software's banner etc.

The screen for adding a UDI to a trading chart includes an example UDI.

The External Widget contains a simple HTML example of a widget which displays a configurable market, current prices for that selected market, and a button for opening the platform's standard deal ticket.

The full code of the platform's built-in Market Ranges widget is available, as an example, at the following URL. You can host these files on a server and then load them using the External Widget:

https://www.fxblue.com/figaro/scripting/example-market-ranges-widget.zip

1.2Framework access

All the features of the Figaro framework are provided via a single base object. This is accessed slightly differently in widgets versus scripts and UDIXes.

In a script or UDIX, there is automatically a Framework object which gives you access to Figaro. For example: Framework.SendOrder()

In a widget, you need to do four things in the widget's web page:

Include the framework Javascript and CSS

Create an instance of the framework

Wait for the framework to become available

Don't reload!

1.2.1Linking to the framework's Javascript and CSS in a widget

Scripts and UDIXes have automatic access to the framework. A widget needs to include the following references in its HTML (usually in the <head>):

<script src="https://figaro.fxbluelabs.com/scripts/widget-js"></script>

<link rel="stylesheet" type="text/css" href="https://figaro.fxbluelabs.com/css/widget-css"/>

1.2.2Creating an instance of the framework in a widget

Scripts and UDIXes automatically have a Framework object. A widget needs to declare a new instance of the framework, in its page's Javascript, rather than having one provided for you automatically:

<script>

// Create an instance of the framework

var Framework = new FXB.Framework();

1.2.2.1Alternative, class-based framework access in widgets

For consistency across widgets, scripts, and UDIXes, this document refers to widgets having access to the framework by creating a new FXB.Framework() object: var Framework = new FXB.Framework();

However, there is also class-based syntax which you can use if you prefer. For example:

// Define a class for your widget which inherits from FXB.Framework

class MyWidget extends FXB.Framework

{

OnLoad()

{

…

}

etc.

}

// Create an instance of the class to service the web page

var widget = new MyWidget();

Within the class members, you can then refer to framework properties and methods using this. For example, this.SendOrder() instead of Framework.SendOrder().

1.2.3Waiting for the framework to become available in a widget

As described in more detail below, widgets must not use any features in the framework until it signals that it is ready by calling the OnLoad() function in your Framework object. Scripts and UDIXes can start using their Framework object as soon as they start running.

1.2.4Reloading or navigation in widgets

A widget must not navigate to another page, or reload itself. This will break its communication with the framework.

For example, if your widget submits a form, it must do so using something like Ajax to send the data, rather than doing a full page POST which causes a reload or navigation of your widget page.

1.3Browser environment

Widgets, scripts, and UDIXes have normal access to the browser's Javascript environment. For example, they can use setInterval() or setTimeout() to carry out delayed actions, and they can use XMLHttpRequest to collect external data (though see below).

Scripts and UDIXes run as web workers. Therefore, there is no web page for them to interact with, and web workers also don't have access to some browser features such as localStorage. But, because they are web workers, scripts and UDIXes can use importScripts() to include external code - subject to standard browser security as described below.

Widgets, scripts, and UDIXes can create web workers to offload complex tasks (in the case of scripts and UDIXes, web workers creating other web workers). In other words, the browser environment makes it possible to have fully multi-threaded processing, with time-consuming tasks done in the background.

Nothing in Figaro is allowed (or able) to use browser modals such as alert() and confirm(). Web workers don't have access to these features, and widgets are prevented from using them by the sandboxing of their iframe. The framework provides alternatives such as Ask() which you can use instead of browser modals - but please note that these are asynchronous.

You can use standard features of your browser to inspect and debug your code. For example, you can insert the debugger; keyword in your Javascript to pause your code in the browser's Developer Console.

1.4Asynchronous operation

Most operations in the framework are asynchronous. The most obvious example is placing a trade: you send a trading request and you provide a callback function (or "completion handler", or whatever term you prefer) which the framework later calls when the action completes. For example:

Framework.SendOrder(orderDefinition, function(MsgResult) {

// Function called asynchronously by the framework when the order succeeds or fails

});

Another example would be asking the user a question by displaying the framework's standard Ask() dialog:

Framework.Ask("Are you sure?", function (Msg) {

// Called asynchronously by the framework

});

This example is in fact slightly more complicated than it looks. Your asynchronous callback from Ask() gets called twice, not once. The second call is the result; the user's response. The first call is an update which gives you the ID of the dialog, giving you the ability to cancel the dialog yourself - for example, if the user takes too long to decide.

And some types of asynchronous callback can get called multiple times. For example, if you issue a request for candle data then - unless you specifically say that you don't want streaming - your callback function will get called multiple times: with an initial batch of candles, and then with each update as the price changes and the current candle is modified or a new candle is formed. For example:

Framework.RequestCandles(candleDef, function(Msg) {

// Called repeatedly, until you terminate it with TerminateCandleRequest()

});

1.5Javascript Promises

For every function in the framework which uses an asynchronous callback, there are two versions: one which issues a Promise, and one which takes a more traditional callback function. For example, the code to display a dialog to select an instrument can be written in either of the following ways:

// Traditional version

Framework.SelectInstrument(function(instrumentId) {

// Called asynchronously by the framework when the user selects a market, or cancels

});

// Version using Promise (and optional arrow function)

Framework.pSelectInstrument().then( (instrumentId) => {

// Called asynchronously by the framework when the user selects a market, or cancels

});

The framework uses a simple naming convention where the "standard" version of the function is something like SelectInstrument() and the Promise version has a p prefix such as pSelectInstrument().

Promises in the framework always settle by fulfilling, never by rejecting. For example, a trading request settles by fulfilling regardless of whether it succeeded or failed, with a parameter describing the success or failure result.

There can be subtle differences between the standard and Promise versions of functions. For example - as described in the previous section - RequestCandles() issues multiple, repeated, streaming callbacks as price changes modify the current candle or start a new one. But a Promise can only settle once; it can't have multiple callbacks. Therefore, pRequestCandles() is always treated as a static, non-streaming request.

1.5.1Async functions and await syntax

The existence of Promises also means that it's possible to use Javascript await syntax, instead of the callback functions - or then() - which are used in this document, and generated by the Run Script widget.

Scripts are automatically run inside an async function. Therefore, it's possible to write code such as the following:

var result = await Framework.pSendOrder({"tradingAction": FXB.OrderTypes.FLATTEN});

Framework.EndScript();

It's not necessary to declare an async function and then pass execution into that:

async function MyAsyncFunction()

{

var result = await Framework.pSendOrder({"tradingAction": FXB.OrderTypes.FLATTEN});

Framework.EndScript();

}

MyAsyncFunction();

1.6Component lifecycle

1.6.1Script lifecycle

Scripts run forever until they call Framework.EndScript(), or the user shuts them down. They don't simply run "from top to bottom" of their code and then automatically terminate. This is because most operations in the framework are asynchronous, and the script may be waiting for an action to complete. The script needs to tell the framework when it has finished.

Consider the following example:

Framework.Ask("Are you sure?", function (Msg) {

// Called asynchronously by the framework

});

Framework.EndScript();

This won't work. The script will create the ask dialog, but then immediately terminate (also destroying the dialog) before it has got a response. This script should instead be written as follows:

Framework.Ask("Are you sure?", function (Msg) {

// Called asynchronously by the framework

// … do something based on the user's response

// And, finally, tell the framework that we're done

Framework.EndScript();

});

// When execution gets here, we're waiting for the user's response to the Ask().

// We don't want to terminate.

1.6.2UDIX lifecycle

The lifecycle of a UDIX is simply tied to the chart on which it is running. A UDIX cannot remove itself from its trading chart; only the user can do this.

1.6.3Widget lifecycle

Widget lifecycle is a little more complicated because a widget is a web page and there are two separate events: loading of the HTML page, and loading of the framework.

Widgets should (normally) have an OnLoad() function. This is called by the framework when it has finished loading, and your code should not try to use any part of the framework - retrieving data, carrying out actions such as placing trades - before the framework says it is ready by calling your OnLoad().

For example, the following code is not safe and won't work:

// Create an instance of the framework

var Framework = new FXB.Framework();

// OnLoad handler

Framework.OnLoad = function() { … Called asynchronously. Framework is now ready };

// **WON'T WORK**. This is executed immediately, before the framework has

// had a chance to set itself up, and before it has done a callback into OnLoad().

Framework.Ask(…);

If the user has added your widget into the Figaro page container, then the widget runs until the user switches to another page. You can't "close" your widget in this context (which would leave a blank space in the page).

If the user has loaded your widget as a dialog or floating panel, then you can choose to close the window. The framework's CancelDialog() function will close the window (and will have no effect if your widget has been added into the page container).

1.6.3.1Permanent widgets

By default, widgets in the page container are unloaded when the user navigates to a different page of the app's configuration. (They can save state and later reload it in order to provide a seamless transition between pages.)

However, it is possible for a widget to keep running after a change of the active page. Such widgets are also always reloaded on restart, even if they are not on the active page.

This mechanism is designed for trading algos (and for similar widgets such as the Excel RTD) which need to keep providing services even if they are not on the active page. It should only be used where necessary. Asking to run permanently, rather than saving state and reloading as the user switches between pages, can affect the performance of the whole Figaro app.

A widget specifies that it needs to run permanently by returning mustRemain:truein its state. The widget must implement OnGetState(). For example:

Framework.OnGetState = function()

{

return {

// Keeps the widget open, and reloads it immediately on app startup even if

// not on the active page

mustRemain: true,

// Any other state which the widget wants to store/report

…

};

};

1.7External data and hosting

Widgets, scripts, and UDIXes can use the standard features of the browser environment to collect external data. For example, you can use XMLHttpRequest to collect data from remote servers, or make websocket connections.

Scripts and UDIXes are web workers, and therefore they can use importScripts() to load external code. For example, you can host the Javascript for a script externally, and then run it within Figaro using a single line of code:

importScripts("https://www.myserver.com/myscript.js");

However, all use of external resources is subject to standard browser security restrictions (which it's not possible for Figaro to override, even if wanted to):

For XMLHttpRequest, the remote server must put CORS headers on its response. If it doesn't, the browser will block the response.

All requests must be made over secure connections (https:// or wss://). Figaro is hosted at an https:// address, and standard browser security prevents anything inside it making calls to insecure addresses. You cannot link to resources at http:// addresses or request data from http:// addresses.

Similarly, if you host a widget externally rather than pasting its HTML into the External Widget, then the URL for your widget must be https://, not http:// (and you obviously must not set any X-Frame-Options header on your page).

1.8Account capabilities

The features which the framework can provide depend on the capabilities of the trading back-end/account which Figaro is logged into. For example, some accounts support trailing stops whereas others do not. Some accounts can only provide the historic trades on the account, not the historic credit movements.

Perhaps most importantly, some accounts support "hedging" - a buy order and then a sell order for the same market create two separate open trades in that market rather than cancelling each other out - whereas other accounts are "netting" and only ever report a single net position (or no position) in a market.

You can inspect what the back-end system supports using the features information in the Framework.Account.

1.9Data representations and standards

The framework uses some standard representations of data:

The framework makes widespread use of a standard dictionary/hashtable class, FXB.utils.Dictionary().

All dates/times are UTC and expressed as a number of milliseconds since January 1^st 1970. The framework provides functions for converting between UTC and different time zones.

Time zones are represented as a structure consisting of an offset, in minutes added to UTC, and a dstMode which defines a daylight-savings schedule: 0 = none, 1 = US schedule, 2 = European schedule, 3 = Australian schedule. For example, New York time is defined as {offset: -300, dstMode: 1}.

Regardless of the back-end system which it is logged into, the framework represents all trading volumes, such as the volume of an FXB.Order, as cash/units, such as 10,000, rather than as a figure in lots such as 0.10. You can convert between cash/units and lots using the contractSize of an FXB.Instrument.

All candle data in Figaro is based on bid prices. Volume - where available from the broker's back-end system - may be either real traded volume or tick pseudo-volume (i.e. MT4-style volume where the "volume" is a count of the number of price changes in the period).

All chart timeframes for candle data, such as M1 or H4, are expressed as a number of seconds, e.g. 3600 for H1. Figaro uses 604800 for weekly (W1) and 2592000 for monthly (MN1).

1.10Future additions to the framework

There will be future additions to the framework. The web version of Figaro will automatically update, but the mobile/tablet app will require user intervention.

The framework has a RELEASE property, currently 1. This will be incremented in future versions, and this guide will note where functions/features require a compatibility level greater than 1.

If your code uses new features of the framework it may need to check the RELEASE level and warn if the mobile/tablet app has not been updated - that the feature you are trying to use is not available.

1.10.1Undocumented members of the framework

You may notice - for example, through the browser's Developer Console - that there are objects and properties in the Framework which are not described in this guide. These are not safe to use. Backward compatibility and consistent behaviour are only guaranteed for things which are covered in this guide.

1.11Questions about the framework

You can send queries about this framework to support@fxbluelabs.com.

However, we will strongly prioritise enquiries which appear to relate to a bug in Figaro, or where this documentation is unclear or incomplete. If you ask us something which we think is clearly answered by this document already, you will probably just receive a one-line reply pointing you to the relevant section of this document - and probably after quite a long delay.

We cannot provide support on general Javascript or web development queries which are not specifically related to the Figaro framework. For example, if you ask us "how do I get the EUR/USD price from the framework?", then we'll send you a one-line response pointing you to the section below. But if you ask us something which is about web development generally rather than about the framework specifically, such as "How do I display a table of prices from the framework in a web page?", we may not respond at all. You need to be proficient in Javascript to use the framework (and in HTML/CSS to build widgets). If you are not, the internet is full of excellent learning resources to help you.

2Collections, objects, and properties in the framework

2.1Framework collections

All the collections in the framework are Dictionary objects, though some of them modify or extend the standard dictionary functions and behaviour.

You can listen for changes to prices or in the order list using an OnMessage() handler. You need to make explicit requests for prices which you are interested in. Prices in the Instruments list do not automatically update.

2.2Framework objects

The Framework object contains the following sub-objects describing the current Figaro environment:

There is also a class which is widely used as a response from actions such as trading requests and dialogs:

2.3Framework properties

The framework provides the following properties. All of these are read-only.

2.4Framework.Instruments collection

The framework provides a list of all the markets available on the current trading account. The Framework.Instruments collection is a Dictionary of FXB.Instrument objects keyed by their instrumentId values. For example, you can get a specific market using Instruments.get() or iterate through all markets using Instruments.forEach().

2.4.1Instruments.get(), Instruments.getOrBlank(), and standardisation

Figaro is designed to work with FX/CFD platforms, and they have almost no standardisation of market names and IDs across different brokers, or even between accounts with the same broker. Figaro tries to impose some standardisation of its own: for example, it will try always to give the euro-dollar FX pair the instrumentId "EUR/USD". But there are limits to what is possible.

As a result, Instruments.get() is not a standard dictionary getter. Its behaviour is overridden. If you do a get() for an instrumentId which does not exist, then get() will try a number of other possible matches:

Does your key match an instrument's .caption?

For fx markets, does your key match the base currency + quote currency? For example, if you pass in "EURUSD" (and the instrumentId of the market is "EUR/USD", and doesn't match), is there an instrument where the .baseCurrency is EUR and the .quoteCurrency is USD?

Does your key match any common known aliases? For example, is your key "GOLD" which is known to match against an instrument where the ID is "XAU/USD"?

You also need to bear in mind that a market may exist on one account and not on another, as well as having different IDs. As a result, you need to consider the following possibility:

Your widget/script stores the user's current settings, including a choice of market

The user logs in to a different broker account and your widget/script is re-loaded

The market in your saved settings does not exist on the new account

As a result, it is more common to use getOrBlank() than get(). If the key you ask for does not exist in the current list of markets, this returns a dummy FXB.Instrument with the following properties:

instrumentId: your key for the missing market

caption set to "?"

Addition of missing:true

This potentially stops your code from breaking when the user logs in to an account where your saved settings refer to a market which doesn't exist. Without needing to do an explicit check for missing markets, your code will typically continue relatively gracefully - for example, displaying ? as the market's caption and zero prices.

2.4.2Instruments.GetTradeableInstruments()

Helper function which returns an array of all instruments with tradeable:true, sorted by their caption.

2.4.3Instruments.GetInstrumentCategories()

Helper function which returns an array of available instrument categories. It scans the list of markets, and builds a de-duplicated list from each market's categoryId.

2.5FXB.Instrument object

The FXB.Instrument object describes an available market on the account. As well as providing properties which describe the market, it also has various helper functions.

2.5.1FXB.Instrument properties

The properties of the FXB.Instrument are as follows. Names marked with * are derived properties - using Object.defineProperty() in Javascript - and will not get included if you clone the object.

Prices do not automatically update. You need to request prices which you are interested in.

2.5.2Market categories

Figaro does its own categorisation of markets (again looking to standardise across different platforms). Every FXB.Instrument is assigned a categoryId from the following FXB.InstrumentCategories list. For example, the euro-dollar FX pair (EUR/USD) will have categoryId=FXB.InstrumentCategories.FX_MAJOR.

You can translate these categories into readable text using TranslateInstrumentCategory().

2.5.3Market data on spread-betting accounts

In the FX/CFD world, there are two different types of account:

"Normal", CFD accounts. A trade in EUR/USD is buying or selling a number of euros, and has a profit in US dollars (converted to the account deposit currency, if different).

Spread-bet accounts. All trades are denominated in the account deposit currency, such as GBP or AUD. A trade on EUR/USD is a bet in GBP (or AUD etc) on the EUR/USD price, on a "pound per point" basis. For example, if the EUR/USD price rises by 0.0001 (i.e. 1/100^th of a US cent) then the trade has profit of GBP 1.

On a CFD account, the quoteCurrency of an FX pair will be the same as the underlyingCurrency. For an FX pair AAA/BBB, both the quoteCurrency and the underlyingCurrency will be BBB.

On a spread-bet account, the underlyingCurrency of an FX pair will be the account deposit currency, not the BBB of the AAA/BBB pair. All trades are bets denominated in the deposit currency.

2.5.4FXB.Instrument helper functions

The FXB.Instrument provides some helper functions to assist with common conversion and calculation tasks in relation to a market.

2.6Framework.Orders collection

The Framework.Orders collection is a Dictionary of all the pending/working orders and open trades on the account. The framework uses the same FXB.Order class to represent both pending orders and open trades (and also historic trades and credit movements).

Framework.Orders is then a collection of FXB.Order objects, keyed by their orderId.

To watch for changes in the order list, you can use an OnMessage() handler.

In addition to standard Dictionary functions, the Framework.Orders collection offers, for convenience, the following derived properties:

In other words, Orders.length (inherited from Dictionary) = Orders.openTradeCount + Orders.pendingOrderCount.

2.7FXB.Order object

The framework uses the FXB.Order object to represent all of the following, because of their similarities:

Pending/working orders

Open trades

Historic closed trades

Historic, cancelled orders

Credit movements on the account (such as deposits and withdrawals)

Some properties within the object are only applicable depending on its context (its orderType). For example, credit movements only have an orderId, reference, orderType, openTime, closeTime (same as openTime), profit, and comment (if the platform supports it). Properties such as instrumentId or volume are obviously inapplicable on a credit movement, and not defined.

2.7.1Order types

The orderType of an FXB.Order can be any of the following members of the FXB.OrderTypes enumeration.

These values are numeric. You can reliably test for credit-movement types by looking at orderType >= FXB.OrderTypes.DEPOSIT - though it is more elegant to use the helper FXB.OrderTypes.IsCredit(orderType).

Granularity/accuracy of the subdivision between different types of credit movements depends on the broker platform. Some platforms will report everything as either only a deposit or withdrawal - i.e. a positive or negative movement, with no further detail.

Some platforms report commission and swap against individual orders, using the commission and swap properties, whereas others record these charges as credit movements against the account.

The FXB.OrderTypes enumeration is also used in relation to submitting trading requests, and has additional valid members in that context.

Stop-limit orders are not widely available. The account features indicate whether the account offers them.

2.7.2Order-type helper functions

The framework provides a range of functions for helping to work with orderType values. For example:

var oppositeType = FXB.OrderTypes.Invert(FXB.OrderTypes.BUY_STOP);

2.8Framework.Positions collection

As well as listing all the individual open trades on the account, in Instrument.Orders, the framework also calculates a total net position for each market. The Instrument.Positions collection is a Dictionary of FXB.Position objects keyed by their instrumentId properties.

(If the trading account is singleNetPosition:true, then the Positions collection should simply match the list of open trades because the back-end platform will only report one trade per market.)

The Instrument.Positions collection only contains entries for markets which have pending orders or open trades. If there is no open order/trade on a market, then it will have no entry in the Instrument.Positions collection.

However, the collection provides the following helper function for working with individual markets:

To watch for changes in positions and their profit, you can use an OnMessage() handler.

2.9FXB.Position object

An FXB.Position object represents all the open trades in a market aggregated up into a single net position. It has the following properties:

The positionType is derived from the number of open trades and their directions. It is one of the FXB.PositionTypes enumeration:

2.10Framework.TradeHistory collection

The Framework.TradeHistory collection is a Dictionary of all historic activity on the account: closed trades, cancelled pending orders, and also credit movements (provided that the back-end platform provides this data).

The history must be explicitly requested. It is empty by default.

To watch for the list being filled, and subsequently updated - you can use an OnMessage() handler.

If/once filled, the collection is a Dictionary of FXB.Order objects, keyed by their orderId properties. (As noted above, FXB.Order is used to represent a number of things, including all of trades, pending orders, and credit movements.)

2.11Framework.Account object

The Framework.Account describes the broker trading account which Figaro is currently logged into. It provides static information about the account such as its ID and deposit currency, plus changing metrics such as balance and margin usage.

Different accounts can have different capabilities - for example, availability of trailing stops or market depth. These are described by the Account.features.

2.11.1Framework.Account properties

The Framework.Account has the following properties. To watch for changes in the account metrics - balance, equity etc - you can use an OnMessage() handler.

2.11.2Account features

Different accounts can have different capabilities. The features available on the current account are described by its Account.features block.

2.12Framework.Environment object

The Framework.Environment object contains information about the Figaro environment:

The deviceId uniquely identifies a device such a web browser. The deviceId is "persistent" but not truly "permanent":

It will be different for each web browser - Chrome, Safari etc - on a single computer.

It will be different for an incognito/private browser window versus a normal window (and different each time an incognito session is opened)

If the user uninstalls and reinstalls the mobile app, the deviceId will change

This deviceId in Framework.Environment is (deliberately) not the identifier for the device in the Figaro mail system. The mail ID cannot be discovered programmatically by a widget, script, or UDIX.

2.13Framework.Translation object

The Framework.Translation object contains functions for translating text-variables into the user's selected language for the Figaro platform. Note: the language cannot change while code is running. It requires the user to log out of the software, and log back in.

The Framework.Translation object contains two properties:

The functions in Framework.Translation are as follows:

2.13.1List of available language variables

The reference to the available language variables is simply the list provided by the Figaro platform:

https://figaro.fxbluelabs.com/lexicon/list

This returns a plain-text file listing all the variables and their English equivalents, in the format variable=text. Some variables include placeholders, in the form @1, @2 etc. These are described in relation to TranslateItem().

2.13.2Framework.Translation.TranslateDOM()

The framework supports a mechanism where language variables are included in HTML in curly brackets such as {SetMarket}, and Javascript can then use TranslateDOM() to scan the HTML and replace all these variables with the equivalent text in the user's selected language.

For example, partial HTML:

<div>

<div class="SectionHeader">{MarketList}</div>

<button title="{SetMarket}">{Market}</button>

etc.

Widget code can then automatically translate all these variables using TranslateDOM(), typically in OnLoad():

Framework.OnLoad = function() {

this.Translation.TranslateDOM();

… and other initialisation actions …

};

The TranslateDOM() can be given an optional parameter of the base node to start at. If omitted, it simply scans through the whole document body.

2.13.3Framework.Translation.TranslateItem() and Framework.$T()

TranslateItem() translates a single variable into its equivalent text. For example:

// Will return "% of equity"

var text = Framework.Translation.TranslateItem("VolumePercentOfEquity");

Some of the available variables include placeholders, designed to be replaced by run-time values. For example, MaxSelectMarkets is defined as "Please select a maximum of @1 markets" where @1 is designed to be replaced at run-time by a number.

You can provide values for these placeholders by supplying an array as an optional second parameter to TranslateItem(). For example:

// Create message saying that the user is allowed to select a maximum of 20 markets

var maxAllowedMsg = Framework.Translation.TranslateItem("MaxSelectMarkets", [20]);

Note: because translation is so widely used within Figaro, the framework provides a helper shortcut to stop programmers' fingers wearing down. You can use Framework.$T(…) as an abbreviation of Framework.Translation.TranslateItem(…). For example, the above code can also be written as follows:

var maxAllowedMsg = Framework.$T("MaxSelectMarkets", [20]);

2.13.4Framework.Translation.TranslateError()

The TranslateError() function takes an FXB.Result object describing an error, for example resulting from a failed trading request, and generates the text to display to the user. For example:

Framework.SendOrder(def, function (MsgResult) {

if (MsgResult.result.isOkay) {

// Succeeded

} else {

// Failed. Display error message…

var errorText = Framework.Translation.TranslateError(MsgResult.result);

…

}

});

2.13.5Framework.Translation.TranslateTimeframe()

The TranslateTimeframe() function takes a chart timeframe, such as 3600, and generates the corresponding text such as "H1". For example:

var txt = Framework.Translation.TranslateTimeframe(86400); // = "D1"

2.13.6Framework.Translation.TranslateInstrumentCategory()

The TranslateInstrumentCategory() function takes a market category ID, such as FXB.InstrumentCategories.COMMODITY, and returns the corresponding display text. For example:

var market = Framework.Instruments.getOrBlank(someInstrumentId);

var categoryText = Framework.Translation.TranslateInstrumentCategory(market.categoryId);

2.14Framework.Theme object

(This section is irrelevant to scripts and UDIXes because they have no user interface of their own. It is only applicable to widgets.)

The user can change the graphical theme of Figaro - e.g. from dark to light - while it is running, without a restart. Therefore, the theme can change while your widget is running.

By including the framework's CSS and Javascript, your widget automatically responds to changes in the selected theme - for example, body background and text colour automatically change. However, you can get the ID of the current theme using the Framework.Theme object, and you can watch for user changes by listening to the THEME message.

The framework automatically sets (and changes, when applicable) a CSS class on the widget's <body> which identifies the current theme.

2.15FXB.Result object

Results/responses to actions are widely represented within the framework using the FXB.Result class. For example, the result of trading actions and of dialogs is an FXB.Result.

An FXB.Result has the following properties:

An error FXB.Result such as a failed trade can be translated into equivalent readable text using Framework.Translation.TranslateError().

Depending on the nature of the response, the FXB.Result may contain other properties giving additional information. Commonly used properties include msg, param1, param2, and param3.

For example, in the response from the standard Ask() dialog, the msg property indicates which button the user selected:

Framework.Ask("Are you sure?", function (Msg) {

if (Msg.result) {

if (Msg.result.code == FXB.ErrorCodes.OKAY) {

if (Msg.result.msg == "Yes") {

// User selected the yes button

}

} else {

// User cancelled the dialog without clicking a button

}

} else {

// Message is an interim update from the dialog, not the final result

}

});

However, it's only usually necessary to check for a specific response or do nothing, and so the code above would/could typically be reduced to the following:

Framework.Ask("Are you sure?", function (Msg) {

if (Msg.result && Msg.result.msg == "Yes") {

// User selected the yes button (as opposed to No button, or cancellation without

// response, or an interim update from the dialog rather than a final result)

}

});

3Functions in the framework

The External Widget example in Figaro 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.1Price 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.2Historic 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:

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 Figaro 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:

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.

3.2.1Candle response messages

The framework's response into your callback function will be a message object containing the following properties:

For example:

Framework.RequestCandles(requestDef, function (MsgCandles) {

if (MsgCandles.result.isOkay) {

// MsgCandles will contain a candles[] array

} else {

// Some problem with the request; see MsgCandles.result.code

}

});

Each item in a candle array has the following properties:

The candles[] array is always sorted by time (ts), in descending order - most recent first.

In a streaming request, the following will happen:

Your callback function will receive an initial call with an array of, say, 1000 candles

Each time the price changes, the current candle will update, and your callback function will receive a candles[] array containing a single item: the update to the current candle.

When the price changes and enters a new time period, you will receive a candles[] array containing an item with an i (and ts) which you have not previously received.

3.2.2Terminating streaming requests

You can terminate a streaming candle request using Framework.TerminateCandleRequest(). This takes a single parameter: the ID of the candle request.

The ID of the request is included by the framework in its response messages. You can also specify an ID of your own at outset, rather than having one allocated automatically, using a requestId in your request.

3.2.3Time zones for candle requests

Like all times in the framework, candle ts values are UTC. However, candle timestamps are more complicated than that.

For timeframes above H1, you can set a timezone value defining how you want candles to be aggregated.

For example, rather than requesting daily candles based on UTC days, you can instead say that you want aggregation based on UTC+2. This is extremely common in forex because the markets open at 5pm New York time on Sunday. If you request candles based on UTC, there are then six D1 candles per week, not five: candles for Monday to Friday, plus a stub of candle covering the period from 9pm/10pm UTC (5pm in New York) to midnight on Sunday.

Let's say that you request D1 candles aggregated based on UTC+2 (as illustrated below). Each daily candle will cover 24 hours. But its start time will not be midnight UTC. The ts value of each candle will represent 10pm (or 9pm during periods of daylight savings).

You can specify aggregation in your candle request using a timezone object (see also time conversion). This has two properties:

For example, the most common request for forex analysis looks like this:

Framework.RequestCandles({

instrumentId: "EUR/USD",

timeframe: 86400, // D1,

timezone: {

// 2 hours ahead of UTC, with USA daylight savings.

// Therefore, constant 7 hours ahead of New York time.

// Market open at 17:00 NYC on Sunday is reported as a candle ts of 00:00

offset: 120,

dstMode: FXB.DSTModes.USA

}

}, function (MsgCandles) {

…

});

This requests aggregation based on UTC+2, changing to UTC+3 on the USA daylight savings schedule. In effect, candles are aggregated based on a day running from 5pm-5pm New York time.

The further and very important thing to note is that the user can set a preference in the Figaro platform for how candle data should be aggregated. If you do not explicitly set a timezone in your candle request, you will automatically get the user's preferred settings. And the default settings in Figaro are not UTC; they're UTC+2 with USA daylight savings.

In other words: if you do not set your own timezone in your candle request, what you will get is aggregation based on UTC+2/3, unless the user has changed the standard settings in the Figaro platform. Daily candles will have a ts at 9pm or 10pm UTC, not midnight UTC.

However, in your request you can also optionally specify convertTimes:true. If set, this automatically converts all the candles ts values before returning the data to you (using Framework.AdjustUTCToZone).

3.3Trading

The framework provides two types of trading requests:

Standard requests for an individual order: opening, closing, or modifying it

Aggregated actions on a market or on the whole account. For example, you can issue a request of type FXB.OrderTypes.FLATTEN. This closes all orders and trades on the account, rather than your code having to iterate though the orders in Framework.Orders and issue its own separate requests to close each one.

In addition, you can either send a single request or an array containing a batch of requests. If you issue a batch, then you get a response either after all requests succeed or when the first one fails. (You don't get a response from a batch listing each individual request and whether it succeeded or failed.)

You issue trading requests using Framework.SendOrder(). This has two compulsory parameters and one optional parameter:

For example:

Framework.SendOrder({

// Buy 10K (0.10 lots) EUR/USD

tradingAction: FXB.OrderTypes.BUY,

instrumentId: "EUR/USD",

volume: 10000

}, function (MsgResult) {

// Asynchronously called with the result of the request

});

Or, using a batch of multiple requests, with optional settings specifying forced confirmation by the user before the batch is started:

Framework.SendOrder([

{

// Close all EUR/USD orders and trades

tradingAction: FXB.OrderTypes.CLOSEPOSITION,

instrumentId: "EUR/USD"

},{

// Buy 5K GBP/USD, specifying the volume in lots

tradingAction: FXB.OrderTypes.BUY,

instrumentId: "GBP/USD",

volume: {lots: 0.05}

}

]}, function (Msg) {

// Asynchronously called when the whole batch has succeeded or on the first failure

}, {

// Force confirmation by the user before the batch is processed

confirm: true

});

3.3.1Overview of trading requests

The request definition which you submit as a parameter to SendOrder() always has one compulsory property: tradingAction. It then has other compulsory or optional properties depending on the type of trading action.

Useful note! The Run Script widget in the Figaro platform provides interactive help on constructing the properties for trading requests. If you use Create From > Trading Action it will show you the script and request settings corresponding to a set of options in the deal ticket.

For the purposes of trading requests, the FXB.OrderTypes enumeration has values which are not applicable in the context of an FXB.Order. These extra values are described in the sections below.

Particularly when opening orders and trades, some options can be specified in multiple forms. This saves your code from doing its own calculations, and makes it easier to translate from user interface fields to properties in a trading request. For example, all the following (and others listed below) are valid ways of specifying the volume when opening a new order or trade:

In other words, the framework lets you send a request saying "stop-loss at 50 pips and risking 1% of account equity" without needing to do all the accompanying calculations yourself in your own code:

Framework.SendOrder({

sl: {pips: 50},

volume: {equityPercent: 1},

…

3.3.2New pending orders and trades

To open a new pending order or trade (market order), you set the tradingAction to one of the FXB.OrderTypes: BUY, SELL_LIMIT etc. For example:

var request = {

tradingAction: FXB.OrderTypes.SELL_LIMIT,

openPrice: {offset: 0.0020}, // Offset of 0.0020 from current price (bid, because sell)

instrumentId: "EUR/USD",

volume: {lots: 0.20}

};

However, for pending orders, you can use two additional values: BUY_PENDING and SELL_PENDING. These let you tell the framework to work out whether your specified entry price for the pending order is a limit or a stop. If you only care about the entry price, e.g. "enter at 1.23456", and not its position relative to the current market price, then you can set the entry price and use BUY_PENDING or SELL_PENDING, and the framework will convert that into the correct combination of buy/sell and limit/stop, e.g. turning the SELL_PENDING into a SELL_STOP.

Compulsory and optional request properties when opening a new trade or order are as follows:

3.3.2.1Volume on order and trade requests

The volume can be specified in any of the following ways:

3.3.2.2Open price on pending orders

The openPrice on a pending order, and the triggerPrice on stop-limit orders, can be specified using any of the following. (It is ignored on new trades.)

3.3.2.3Stop-loss on orders and trades

The sl on a pending order or trade can be specified using any of the following:

3.3.2.4Take-profit on orders and trades

The tp on a new order or trade can use all the same options as the sl . However, there is one further option available in relation to the take-profit:

3.3.2.5Trailing stop on orders and trades

Trailing stops are not necessarily supported; this depends on the capabilities of the broker account and its back-end trading platform. The trail property will be ignored if not supported by the back-end platform.

If supported, the trail property can be one of the following:

3.3.2.6Expiry on pending orders

The expiry on a pending order can be specified using any of the following. (It is ignored on new trades.)

3.3.2.7Candle-based prices in order definitions

The definition of the openPrice, sl, and tp in an order or trade can instruct the framework to calculate a price from historic candle data. For example: "open price at the high of yesterday's D1 [daily] candle, plus 1 pip".

Note: this can lead to a significant delay in processing a request unless the framework has already been asked to collect this candle data.

To use candle-based prices, the trading request must include a timeframe. The definitions of the open price, stop-loss, and take-profit must use the same timeframe (or none); you cannot mix definitions from different timeframes within the same request.

The definition of the openPrice, sl, and/or tp can then include the following values. The index and price are compulsory. The offsetPips is optional.

For example, the following request specifies the following:

Buy-limit pending order

Open price at the high of yesterday's D1 candle

Stop-loss at the low of yesterday's D1 candle, minus 5 pips

Take-profit at 30 pips from the current price (not candle-based)

Framework.SendOrder({

tradingAction: FXB.OrderTypes.BUY_LIMIT,

timeframe: 86400, // Timeframe for candle-based open price and stop-loss

openPrice: {bar: {index: 1, price: "h"}},

sl: {bar: {index: 1, price: "l", offsetPips: -5}},

tp: {pips: 30},

…

3.3.3Modifying open trades and pending orders

You can modify a pending order or open trade using FXB.OrderTypes.CHANGE as the tradingAction. You must supply the orderId of an open order or trade in the Framework.Orders list. For example:

// Change the stop-loss on order O12345 to 30 pips from the current market price

// (leaving all other settings unchanged)

Framework.SendOrder({

orderId: "O12345",

tradingAction: FXB.OrderTypes.CHANGE,

sl: {pips: 30}

}, function (MsgResult) {

…

});

The stop-loss (sl) and take-profit (tp) of a trade or order can always be changed. You can alter the openPrice of a pending order but not of an open trade - obviously! Support for trailing stops (trail) is determined by the features of the trading account and its back-end platform. The ability to change the volume of a pending order also depends on the features of the account and back-end platform. A new value for the volume will be ignored if the back-end platform does not support such a change.

When modifying an order or trade, you can use all the same options as when making a new request. For example, you can change an open trade as follows:

Framework.SendOrder({

orderId: "T12345",

tradingAction: FXB.OrderTypes.CHANGE,

timeframe: 3600, // Timeframe for candle-based stop-loss

sl: {bar: {index: 1, price: "l"}}, // Set the stop-loss to the low of the previous H1 bar

tp: {pips: 30} // Set the take-profit to 30 pips from the current market price

}, function (MsgResult) {

…

});

3.3.4Closing individual trades and orders

You can close an open trade or delete a pending order by using FXB.OrderTypes.CLOSE as the tradingAction. For closure/deletion, you must supply the orderId of an open order or trade in the Framework.Orders list.

Deletion of a pending order is simple because it can have no properties other than the tradingAction and orderId:

// Delete pending order O12345

Framework.SendOrder({

tradingAction: FXB.OrderTypes.CLOSE,

orderId: "O12345"

}, function (MsgResult) {

…

});

Closure of an open trade is slightly more complicated because you can optionally do a partial close instead of a complete close.

The definition for a full close of an open trade is the same as deletion of a pending order:

// Close (completely) open trade T12345

Framework.SendOrder({

tradingAction: FXB.OrderTypes.CLOSE,

orderId: "T12345"

}, function (MsgResult) {

…

});

To do a partial close, you specify a volume. This can be one of the following values:

The following request closes 75% of trade T12345. This is subject to the trading minimums and increments for the market. For example, if T12345 is a position of 3000 cash/units, and the minimum/increment volume for orders in this market is 1000, then the following instruction will be interpreted as a complete close. The framework always rounds up when doing a close. It will calculate 75% of 3000 = 2250, and round that up to the nearest permitted increment of 1000… which is a complete close of all 3000 cash/units.

// Close 75% of trade T12345

Framework.SendOrder({

tradingAction: FXB.OrderTypes.CLOSE,

orderId: "T12345",

volume: {percent: 75}

}, function (MsgResult) {

…

});

3.3.5Closing all open trades or pending orders on a single market

The following tradingAction types close all the open trades and/or pending orders on a single market. They simply save your code having to scan the Framework.Orders list and build its own list of individual trading requests. With some types of account/back-end trading platform the framework may be able to use a more optimised trading request than closing each order/trade individually.

For the following actions, an instrumentId for the FXB.Instrument is compulsory. No other values are required or used.

For example, you can close all the loss-making open trades on EUR/USD with the following request:

Framework.SendOrder({

tradingAction: FXB.OrderTypes.CLOSEPOSLOSERS,

instrumentId: "EUR/USD"

}, function (MsgResult) {

…

});

3.3.6Closing all open trades or pending orders on the whole account

The following tradingAction types close all the open trades and/or pending orders across the whole account. Like position actions, they save your code having to scan the Framework.Orders list and build its own list of individual trading requests. With some types of account/back-end trading platform the framework may be able to use a more optimised trading request than closing each order/trade individually.

For example, the following request completely flattens your entire account - closes all open trades and deletes all pending orders:

Framework.SendOrder({

tradingAction: FXB.OrderTypes.FLATTEN

}, function (MsgResult) {

…

});

All the following tradingAction types require no other properties in the request, because they simply operate across the whole account:

3.3.7Asynchronous result callback for SendOrder()

The callback function which you provide as a parameter to SendOrder() receives success or (first) failure of the request. It receives one parameter: a message which contains an FXB.Result object in a property called result. For example:

Framework.SendOrder({

… request definition

}, function (Msg) {

if (Msg.result.isError) {

// Trading request failed

} else {

// Trading request did not fail. However…

}

});

Broadly, there are four possible outcomes from a trading request:

Request fails. The FXB.Result will return isError=true

Request is carried out and succeeds. The FXB.Result will return isOkay=true and code=FXB.ErrorCodes.OKAY

Request requires no action - for example, asking to do a FLATTEN on the account when there are no open orders. The FXB.Result will return isOkay=true and code=FXB.ErrorCodes.NO_ACTION_REQUIRED

Your request is subject to user confirmation, and the user cancels the request before it is started. The FXB.Result will return isOkay=true and code=FXB.ErrorCodes.CANCELLED

In other words, isOkay=true in the FXB.Result does not necessarily mean that any trading action has been carried out. In particular, if you want to look for cancellation by the user, you need to check the code instead of isOkay or isError. User cancellation is not treated as an error condition by an FXB.Result.

3.3.8Optional settings for trading requests

A trading instruction through SendOrder() can have an optional third settings parameter controlling how the request is executed by the framework. This settings block can have the following properties:

3.3.9Forcing confirmation of all subsequent trading

A widget, script, or UDIX can use the function Framework.ConfirmAllTrading() to turn on confirmation of all subsequent trading requests which it submits during the lifetime of that instance. (ConfirmAllTrading() has no effect on other components, only on the caller.) Once set, the effects of ConfirmAllTrading() cannot be turned off.

This function is documented here for completeness, but it not actually designed to be used by a widget, script, or UDIX. It is meant to be a simple safety mechanism for end-users. If someone is given a script - via whatever means - they can ensure that it can't trade automatically just by adding Framework.ConfirmAllTrading() to the start of the script. For example, if a script is loaded into Figaro using its Data Transfer widget, Framework.ConfirmAllTrading() is automatically added to the script.

3.3.10Validating trading requests without execution

You can use Framework.ValidateOrder() to validate trading requests without executing them. As well as checking that a request passes the framework's internal validation, this also does two other things:

It splits a bulk action such as FLATTEN into the individual jobs for closing each open order or trade

It converts variable definitions such as openPrice:{offset:0.0020} or volume:{equityPercent:2} into fixed amounts

ValidateOrder() takes two parameters: the same trading request which you pass to SendOrder(), and an asynchronous callback function. For example:

Framework.ValidateOrder({

tradingAction: FXB.OrderTypes.SELL_LIMIT,

openPrice: {offset: 0.0020},

instrumentId: "EUR/USD",

volume: {lots: 0.20}

}, function (Msg) {

… result of validation

});

The Msg which is passed to the callback function can contain two properties:

For example, after validation of the above request, tradingJobs[] will have a single entry such as the following:

{

instrumentId: "EUR/USD",

tradingAction: FXB.OrderTypes.SELL_LIMIT,

volume: 20000, // conversion of {lots:0.20}

openPrice: 1.23456 // conversion of variable {offset:0.0020} to fixed price

}

3.4Account history

The history on an account - closed trades and credit movements - is potentially (a) very large and (b) time-consuming to collect from the broker's back-end system. The Framework.TradeHistory is empty by default, and must explicitly be filled by using Framework.RequestAccountHistory(). This then sends ACCOUNT_HISTORY updates to your message handler and fills the Framework.TradeHistory collection.

There can be a long delay between using Framework.RequestAccountHistory() and receiving the initial history. You may get an almost immediate response (asynchronous) if another widget has already initiated collection of the history or, at the other extreme, there can be a delay of many seconds while the framework has to make multiple calls to the broker server to collect the initial history.

The contents and detail of the history are slightly variable depending on the capabilities of the account. For example, a couple of broker back-end systems can only provide the historic trades on an account, not the credit movements.

3.5Dialogs

Widgets, scripts, and UDIXes have a wide variety of options for displaying dialogs in order to present information to the user or to ask questions. Note: you cannot use browser modals such as alert() and confirm().

3.5.1Standard dialog behaviour and settings

The many types of dialog offered by the framework share some common behaviour and settings.

By default, dialogs are tied to their creator. If your widget, script, or UDIX terminates, any open dialog(s) from it will be automatically destroyed. You can change this lifecycle by setting keepAfterParent:true in the settings for the dialog.

There are some standard settings which you can apply when creating any type of dialog:

Note: you must set both windowWidth and windowHeight, or neither. If you only set one of the properties, it is ignored.

In some cases, you don't just get a final result from a dialog. You also get an initial callback which gives you the ID of the dialog. This makes it possible for you to destroy the dialog, using Framework.DestroyDialog(), before the user responds. There is an example of this below in relation to a simple Ask() message.

3.5.2Common information/alert/question dialogs

The framework provides a set of standard dialogs for displaying simple messages to the user, or asking yes/no questions.

These are all fundamentally the same dialog, but with different cosmetic styling and default buttons. For example, you can change the error dialog so that it has yes/no buttons, and you can change the confirmation dialog so that it only has a single "okay" button.

The functions provided by the framework in this area are as follows:

Each of these functions takes two parameters: a block of settings, and a callback function which receives the dialog result. For example:

Framework.Ask("Are you sure?", function(Msg) {

…

});

The settings can either be a simple string, as in the above example, or an object with properties. For example:

Framework.Ask({

title: "Really?",

text: "Are you sure you want to do this?",

buttons: [

{text: "Yes, definitely", value: "Yup", className: "btn-red"},

{text: "On second thoughts…", value: "No"}

]

}, function (Msg) {

…

});

3.5.2.1Button styles for common dialogs

As you can see in the above example, you can not only set the title and text of the dialog, but you can also override the buttons. Each button definition can have the following properties:

3.5.2.2Callbacks from common dialogs

Any asynchronous message handler which you specify for a common dialog is called twice, not once. The first call is an update/initialisation. You will generally want to ignore this, but it gives you the ID of the dialog, and makes it possible for you to destroy the dialog before the user makes a selection.

The second call to your asynchronous function is the result from the dialog. You can test for the final result callback by looking for Msg.result. For example:

Framework.Ask(… , function(Msg) {

if (Msg.result) {

// Final result

} else {

// Initial creation/update

}

});

The final result, Msg.result, is an FXB.Result object. The code will be FXB.ErrorCodes.CANCELLED if the user closed the dialog without a response. If the user clicked one of the buttons, then the code will be FXB.ErrorCodes.OKAY and the FXB.Result will have a msg property which is the value of the selected button.

The standard Ask() function - if you do not override it, like the above example - has buttons which return the value/msg "Yes" and "No". Therefore, typical handling of the Ask() function very simply looks like this:

Framework.Ask(…, function(Msg) {

if (Msg.result && Msg.result.msg == "Yes") {

// Do something if this is the final result from the dialog, and the user said "yes".

// Ignore cases - do nothing - if this message is not the final dialog result,

// or if the user clicked no or cancelled the dialog.

}

});

3.5.2.3Manually destroying common dialogs

As described above, the initial update message from the dialog gives you its ID, in Msg.widgetId, and that makes it possible for you to use Framework.DestroyDialog() to close the dialog. For example, the following Ask() cancels itself if the user does not respond within 5 seconds:

Framework.Ask({

title: "Are you sure?",

text: "You have 5 seconds to answer...",

}, function (Msg) {

if (!Msg.result) {

// No .result in message. Therefore, it's the initial creation of the dialog.

// Set a timer which destroys the dialog after 5 seconds if the

// user has not answered.

setTimeout(function() {

Framework.DestroyDialog(Msg.widgetId);

}, 5000);

} else {

// Result from the dialog. Can either be the user clicking the button,

// or termination of the dialog by the above DestroyDialog()

}

});

3.5.2.4Floating, non-modal common dialogs

All the common dialogs can also be made floating instead of modal (so that they are not destroyed by clicking outside them). You do this by setting floating:true in the properties for the dialog. For example:

Framework.InfoMessage({

text: "Must be explicitly closed. Not destroyed if the user clicks outside it",

floating: true

});

3.5.3Selecting a market or timeframe

The framework provides two standard dialogs for selecting a market or timeframe. Note: these functions only give you a final result. You don't get an initial creation message from the dialog which gives you the ability to destroy it. You also can't customise the size or style of these dialogs, or set noCancel on them.

You can ask the user to select a market using Framework.SelectInstrument(). The asynchronous return value is the instrumentId of an FXB.Instrument, or null. For example:

Framework.SelectInstrument(function (instrumentId) {

if (instrumentId) {

var market = Framework.Instruments.get(instrumentId);

…

} else {

// Cancellation of dialog

}

});

You can ask the user to select a timeframe using Framework.SelectTimeframe(). The asynchronous return value is the numeric chart timeframe, or null. For example:

Framework.SelectTimeframe(function (timeframe) {

if (timeframe) {

…

} else {

// Cancellation of dialog

}

});

3.5.4Asking for a text value

You can ask the user for a text value using AskForText(). Note: this function only gives you a final result. You don't get an initial creation message from the dialog which gives you the ability to destroy it.

The simple usage is equivalent to the browser modalprompt(). You supply a string, and the user has the opportunity to change it. For example:

Framework.AskForText("Current value", function (result) {

// Text entered by user, or null if the user cancelled.

});

Instead of simply supplying the pre-populated value for the text field, you can supply a full dialog definition in which you can set a title plus standard dialog options such as noCancel. For example:

Framework.AskForText({

title: "Please enter your name",

heading: "What are you called?",

needValue: true, // User must enter a value, or else Save is disabled

text: "", // Text to prepopulate with

}, function (result) {

// Text entered by user, or null if the dialog is cancelled

});

In addition to standard dialog options, the full set of properties which you can provide is as follows:

3.5.5Selecting from a list

The framework provides a SelectFromList() function to display a standard dialog for selecting from a simple list of options. A couple of notes:

This function only gives you a final result. You don't get an initial creation message from the dialog which gives you the ability to destroy it.

You can display a more complex list, with multiple levels and with additional options such as icons, using Framework.MenuListDialog()

SelectFromList() takes two parameters: the list to display, and an asynchronous callback function which receives the user's selection (or cancellation). For example:

Framework.SelectFromList([

{value: "close", caption: "Close"},

{value: "reverse", caption: "Reverse"},

{value: "double", caption: "Double", someExtraData: "x2"}

], function (selection) {

// Either null, or one of the objects in the array

});

You can pass three types of list as the first parameter:

A simple array of values, such as [1, 2, 3, 4, 5] or ["Red", "Green", "Blue"]. What you get back as the selection is simply the selected item in the array, such as 3 or "Green".

An array of objects, like the example above. Each object must have a caption, which is what is displayed to the user. What you get back is the entire selected object, such as {value: "double", caption: "Double", someExtraData: "x2"}

Full dialog initialisation, including the ability to set standard properties such as noCancel, containing an items[] array which is then like the example above.

As an example of the third type, the following code displays the same list of options as the example above, but customises the title and adds the noCancel style into the dialog which is displayed to the user:

Framework.SelectFromList({

title: "What shall we do?",

noCancel: true,

items: [

{value: "close", caption: "Close"},

{value: "reverse", caption: "Reverse"},

{value: "double", caption: "Double", someExtraPrivateData: "x2"}

]

}, function (selection) {

// Either null, or one of the objects in the array

});

3.5.5.1Checkbox list

SelectFromList() can also be used to display a list of items with checkboxes, where the user can then select multiple items rather than a single item.

There are two requirements in order to use SelectFromList() in this way: the options for SelectFromList() must include checkboxes:true, and the items[] array must contain objects where each one has id and caption members (in addition to any other data which you want to receive back from the dialog). For example:

Framework.SelectFromList({

title: "Which do you want?",

checkboxes: true,

items: [

{id: "item1", caption: "Item 1"},

{id: "item2", caption: "Item 2", checked: true}, // Checked by default

{id: "item3", caption: "Item3", someExtraPrivateData: "x2"}

]

}, function (selection) {

// Either null, or an array of the checked items

});

The return value from SelectFromList() is an array of the checked items (rather than a single selection).

By default, the dialog's Save button is/remains enabled even if no items are checked (and the return value is then an empty array). If you want to prevent this, and to force the user either to cancel the dialog or to select at least one item, then you can specify checkboxesPreventNone: true in the options for SelectFromList().

3.5.6Menu-list dialogs (with icons, sub-menus etc)

On small screens such as mobile phones, the framework modifies pop-up menus in widgets so that they are instead displayed as a list in a dialog. This way of presenting a choice of values is also available as the Framework.MenuListDialog() function, letting you display a list with multiple levels and with options such as icons for each item.

MenuListDialog() takes two parameters: a definition of the dialog, and a callback function which is notified about initial creation of the dialog and the user's selection (or cancellation of the dialog). For example:

Framework.MenuListDialog({

title: "My list",

items: [

{text: "Item 1", actionData: "some value"},

{text: "Item 2", checkbox: true, separator: true, id: 98},

{text: "Disabled item", disabled: true},

{text: "Has a sub-menu", icon: "xf002", items: [

{text: "Sub item 1", color: "red", id: 37},

{text: "Sub item 2", icon: "xf00d", id: 43}

]},

]

}, function (Msg) {

if (Msg.result && Msg.result.itemData) {

// User made a selection. Selected item is in Msg.result.itemData

}

});

The definition of the list can have a title, and the standard dialog settings such as width and height. It should also have an items[] array, as in the example above, defining the options to display to the user.

Each entry in the items[] array can have the following properties.

Each entry in the array can also have any number of other properties for your own reference, such as id, value, action etc. When an item is selected, the full data for the item, including any extra properties such as these, is passed into your asynchronous callback function (as Msg.result.itemData).

Your callback function is called twice: once with initialisation data which gives you the ID of the dialog, and a second time with the result of the dialog: either the user's selection, or cancellation.

The final result callback has a result member, an FXB.Result object, in the Msg. The code of Msg.result will be FXB.ErrorCodes.CANCELLED if the user closed the dialog without a response. If the user selected one of the items then the code will be FXB.ErrorCodes.OKAY and the FXB.Result will have an itemData property which gives you the full data of the selected item from the items[] array. The simplest way to check for a user selection versus cancellation or an initial update from the dialog is therefore like the example above:

if (Msg.result && Msg.result.itemData) {

// User has made a selection

} else {

// Initial update message, or user cancelled the dialog without response

}

3.5.7Displaying a settings dialog

The framework provides an AskSettings() function which lets you display a list of settings such as a combination of numeric and text fields. Note: this function only gives you a final result. You don't get an initial creation message from the dialog which gives you the ability to destroy it.

The settings which you display can potentially be long and complicated, divided up into multiple sections or even multiple pages. A simple example is as follows:

Framework.AskSettings([

{type: "int", caption: "A number field", value: 23},

{type: "text", caption: "A text field", value: "Some text"},

{type: "instrumentId", caption: "A market", value: "GBP/USD"},

{type: "list", caption: "A list of options", value: "value2", options: [

{k: "value1", v: "Option 1"},

{k: "value2", v: "Option 2"}

]}

], function (MsgResult) {

…

});

Each individual field in the settings can have the following properties:

The configuration which you pass into AskSettings() can be any of the following:

An array of fields, as in the example above

An object with a fields[] array

An object with a sections[] array

An object with a pages[] array

If you pass an object rather than a bare array, then you can set a title plus standard dialog options such as noCancel.

Passing an object with a sections[] array lets you break up a large set of fields into multiple sections, to make it easier for the user to understand. For example:

Framework.AskSettings({

sections: [

{

caption: "Section 1",

fields: [

{type: "int", caption: "A number field", value: 17},

]

}, {

caption: "Section 2",

fields: [

{type: "int", caption: "Another number field", value: 46},

]

}

]

}, function (MsgResult) {

…

});

Your settings can even be split up into multiple pages; a pages[] array. Each page must have a caption and a sections[] array.

What you get back in your asynchronous callback function depends on the input you provide. The Msg which is passed to the callback is always an FXB.Result object. The code will be FXB.ErrorCodes.CANCELLED if the user cancelled the dialog.

If the user saves the settings, then you will receive one of the following inside the Msg object, depending on the input your provided for the dialog:

A pages[] array, repeating the pages[] array which you passed in, and filling in the selected values for each field

A sections[] array, repeating the sections[] array which you passed in, and filling in the selected values for each field

Or, just a fields[] array

3.5.8Custom HTML dialogs

You can get the framework to display a completely custom dialog consisting of your own HTML. This mechanism is very flexible, because you can do bi-directional communication between your widget/script and the dialog while it is open, but it is complicated. It involves you having to assemble a string containing HTML and Javascript inside your code (unless you use a web page hosted externally). In a widget, but not a script or UDIX, it may be simpler to have the widget act as its own dialog.

You create an HTML dialog using Framework.CreateHtmlDialog(). This has some fundamental ground rules:

You can send messages from your widget/script/UDIX to the dialog.

The dialog can send messages to your widget/script/UDIX.

The dialog has no access to the framework. You can send messages to the dialog containing framework data, and the dialog can send you messages asking your widget/script/UDIX to carry out framework actions. But the dialog itself cannot access the framework.

The dialog cannot close itself. It needs to send a message to your widget/script/UDIX, and your widget/script/UDIX then uses Framework.DestroyDialog() to close the dialog.

As an example, take the following widget/script/UDIX code which builds a string containing an HTML document, including a <script> block. This will the HTML of our dialog:

var html = "<html><head>";

html += "<script>";

html += "function SendUpdateToParent(txt) {window.parent.postMessage(txt, '*');};"

html += "window.addEventListener('message', function(event) {";

html += "document.getElementById('lblEquity').innerText = event.data;";

html += "});"

html += "</script>";

html += "</head><body>";

html += "<p>Equity: <span id='lblEquity'>...</span></p>"

html += "<p><button onclick='SendUpdateToParent(\"close-me\");'>Close</button></p>";

html += "</body></html>";

Various things are happening here:

The <script> in the HTML defines a SendUpdateToParent() function. This sends messages from the dialog to your widget/script/UDIX, using the standard browser window.parent.postMessage().

There is a button in the page which uses SendUpdateToParent() to send the message "close-me" to your widget/script/UDIX.

The Javascript in the HTML sets up a listener on window.message. This receives updates from your widget/script/UDIX. In this basic example, the handler simply dumps the content of a message into the <span id="lblEquity"> in the page. In a more sophisticated example you might send a message to the HTML by building some JSON and doing JSON.stringify() on it, and the dialog might parse it with JSON.parse(event.data) and then inspect the contents.

You can then create such a dialog as follows:

Framework.CreateHtmlDialog({

title: "My dialog",

html: html

}, function(Msg) {

if (Msg.result) {

// Dialog has been closed/cancelled. Remove the timer which we set up earlier.

clearInterval(Framework.$myTimer);

} else if (Msg.update) {

// Some kind of message from the dialog, via window.parent.postMessage()

if (Msg.update == "close-me") {

// Dialog is asking to be closed

Framework.DestroyDialog(Msg.widgetId);

} else {

// Some other message

}

} else {

// If not a result and not an update, then this is the initial message

// giving us the dialog's ID (in Msg.widgetId).

// As a simple example, we will send the dialog the current account equity

// once per second.

setInterval(function() {

Framework.$myTimer = Framework.SendHtmlDialogUpdate(Msg.widgetId, Framework.Account.equity);

}, 1000);

}

});

Again, a number of things are happening in this widget/script/UDIX code:

The asynchronous callback handler from CreateHtmlDialog() can receive a number of types of message.

If the Msg parameter contains a result, then the dialog has been closed/cancelled.

If the Msg contains an update, then it is a message from the dialog Javascript, issued using window.parent.postMessage() as illustrated above. The example code inspects the text of the message from the dialog. If the dialog is saying "close-me", then the code closes the dialog using DestroyDialog().

If the Msg contains neither an update nor a result, then it is the initial creation message about the dialog. What the code does in this example is to set up a timer which, every second, sends the dialog the current value of account equity using Framework. SendHtmlDialogUpdate(). The dialog receives this in its window.message handler, and puts the value into the <span id="lblEquity"> as described above.

All this is obviously not a very realistic example in itself. But exactly the same principles used here can be extended to create very feature-rich dialogs, all ultimately based on the same message-exchange demonstrated above.

Finally, in addition to the title and html properties used above, there are further settings which you can supply when creating the dialog:

3.5.9Widget displaying itself as its own dialog

This section only applies to widgets. It does not apply to scripts or UDIXes because they have no web page.

A widget can display itself as a dialog. This can be simpler than using CreateHtmlDialog(). For example, your widget can have HTML as follows:

<html>

<head>…</head>

<body>

<div id="NormalContent">

<!-- Normal widget content -->

</div>

<div id="DialogContent">

<!-- Different content when displayed as a dialog -->

</div>

</body>

</html>

On start-up, typically in OnLoad(), you check the mode. If the widget is being displayed as its own dialog then you hide the #NormalContent and show the #DialogContent. For example:

Framework.OnLoad = function() {

// Check the mode. See below…

if (Framework.privateSettings.asDialog) {

// Dialog mode

// Hide the normal content and show the dialog content

document.getElementById("NormalContent").style.display = "none";

document.getElementById("DialogContent").style.display = "block";

// Do initialisation for dialog mode

} else {

// Normal mode

// Show the normal content and hide the dialog content

document.getElementById("NormalContent").style.display = "block";

document.getElementById("DialogContent").style.display = "none";

// Do normal initialisation

}

};

From normal mode, you display the widget as its own dialog using CreateDialog(). For example:

Framework.CreateDialog({

// Use own type as the type for the dialog

type: Framework.type,

// Pass settings to the dialog. These are received as Framework.privateSettings

// The asDialog flag signals to the widget's own code that it is in dialog mode

// rather than normal mode, as illustrated above. The settings:{} block can

// contain any further data which you want to pass into the dialog

settings: {

asDialog: true

}

}, function (Msg) {

// Asynchronously receives a result, plus any updates, from the dialog

// (Behaves just like the built-in dialogs described in the sections above)

});

In other words, the main widget passes settings to the dialog containing asDialog:true (and can include any other initialisation data which it wants). The widget running as a dialog receives these settings in Framework.privateSettings, triggering it to enter dialog mode as in the example above.

The dialog can send a result back to the main widget using Framework.SendDialogResult(). Using SendDialogResult() automatically closes the dialog. The result data, passed as a parameter to SendDialogResult() can be anything, but standard behaviour is for it to be an FXB.Result object. For example:

// Create FXB.Result object

var result = new FXB.Result(0); // Can be initialised with 0 (okay) or any error code

// Add in any proprietary data to the FXB.Result. For example:

result.myData = {

someKey: someValue

};

// Send the result back to the creator. This closes the dialog.

Framework.SendDialogResult(result);

The dialog can cancel itself, rather than sending a result, using Framework.CancelDialog().

The dialog can also send interim updates back to the creator, using Framework.SendDialogUpdate(). Again, the parameter for SendDialogUpdate() can be anything, but standard behaviour is for it to be an FXB.Result.

The main widget receives information from or about the dialog in its asynchronous callback function for CreateDialog(). Like the standard dialog usage described above, it gets an initial message which provides the ID of the dialog and then receives any interim updates followed by a final result. For example:

Framework.CreateDialog({ … }, function (Msg) {

if (Msg.result) {

// If Msg has a .result, then the dialog has now closed (or been dismissed)

} else if (Msg.update) {

// If Msg has an .update, then the dialog is using SendDialogUpdate()

} else {

// If neither .result nor .update, then it's the initial message about creation

}

});

(It's also possible for the main widget and the instance acting as a dialog to exchange other messages, as well as using the standard SendDialogUpdate() and SendDialogResult(). The dialog gets the ID of the main widget as Framework._parentWidget. The main widget gets the ID of the dialog in the first message to the asynchronous callback function. Having each other's IDs allows the main widget and dialog to exchange messages as described below.)

3.5.10Displaying the platform's standard deal ticket

You can display the platform's standard deal ticket, instead of placing an order directly in your own code. Figaro has two related but separate trading dialogs:

The dealticket. This handles placement of new orders, and also has a subsidiary panel for carrying out actions across a whole market (e.g. closing all EUR/USD trades).

The trading-action. This embeds the dealticket, and provides additional options for carrying out actions on the whole account such as flattening all trades and orders.

You can open either window, with no pre-population, using very simple calls to Framework.CreateDialog(). For example:

Framework.CreateDialog({type: "dealticket"});

…

Framework.CreateDialog({type: "trading-action"});

In both cases, CreateDialog() can have an asynchronous callback function which receives an update when the dialog is created, and a final result when the dialog closes itself. For example:

Framework.CreateDialog({type: "dealticket"}, function (Msg) {

if (Msg.result) {

// Final result of the dialog, which is now closed

} else {

// Initial update, providing the ID of the dialog

}

});

Both dialogs can be pre-populated with the following optional settings:

For example:

// Display a suggested trade, with an accompanying message, and get the

// user's selection back from the dealticket rather than having the order

// executed by the dealticket

Framework.CreateDialog({

type: "dealticket",

settings: {

orderDefinition: {

tradingAction: FXB.OrderTypes.SELL,

instrumentId: "AUD/USD",

volume: 30000,

sl: {pips: 20}

},

handleExecution: false,

message: "This is my suggested trade"

}

}, function (Msg) {

if (Msg.result && Msg.result.orderDefinition) {

// Dialog is passing back the user's settings rather than executing them itself

} else {

// Initial update, or cancellation of the dialog

}

});

The dealticket has further settings which can be used to customise it:

3.5.10.1Selecting an order template

You can ask the user to select a saved order template using ChooseOrderTemplate(). The template can then be passed into the deal ticket, as the orderDefinition, pre-populating the deal ticket. For example:

Framework.ChooseOrderTemplate(null, function(template) {

// Asynchronously receives the selected template, or null

if (template) {

// Potentially modify or add to the template

// …

// And then pass the template into the deal ticket

Framework.CreateDialog({

type: "dealticket",

settings: {

orderDefinition: template

}

});

}

});

Alternatively, you can add an instrumentId into the template and then execute the order yourself, without displaying a deal ticket:

Framework.ChooseOrderTemplate(null, function(template) {

// Asynchronously receives the selected template, or null

if (template) {

// Put the required market into the template

template.instrumentId = <some market ID>;

// And then pass the template into the deal ticket

Framework.SendOrder(template, function (MsgResult) {

// … handle asynchronous success or failure

});

}

});

The first parameter for ChooseOrderTemplate() is an optional block of settings which can contain the following properties:

There is no functional difference between showNone and showDefault. Choosing to use the term "Default" is slightly clearer to the user that, if nothing is explicitly pre-populated into the deal ticket, then the deal ticket will automatically select any user-defined default template. For example:

Framework.ChooseOrderTemplate({showDefault: true}, function(template) {

if (template == "default") {

// User clicked the Default button.

// Display the deal ticket. A blank or omitted orderDefinition will mean

// that the deal ticket automatically selects any user-defined default

Framework.CreateDialog({

type: "dealticket"

});

} else if (template) {

// User selected a template

// Pre-populate the selected template into the deal ticket

Framework.CreateDialog({

type: "dealticket",

settings: {

orderDefinition: template

}

});

} else {

// (User cancelled the dialog)

}

});

3.5.11Notifying the user by generating mail

It is not strictly a dialog, because there is no direct user response, but it is worth noting in this section that it is possible to generate alerts and notifications to users by sending internal mail within Figaro.

For example, a widget, script, or UDIX can notify the user of an important event by generating mail with priority 2 or even 3 - as described below.

3.5.12Toast

"Toast" is the common, standard terminology for small notifications which are displayed at the edge of the screen, and which automatically disappear after a few seconds. Toast is used by the Figaro app itself if the user turns on options in the Notifications section of the app's settings.

3.5.12.1Creating toast

A widget, script, or UDIX can create its own toast pop-ups using Framework.CreateToast(). For example:

Framework.CreateToast({

title: "Finished!",

text: "The task has been completed",

icon: "f05a"

});

The standard properties of the toast definition are as follows:

Framework.CreateToast() can have a callback function. This is called if the user clicks on the toast notification and/or when the toast is destroyed. For example:

Framework.CreateToast({

title: "Finished!",

text: "The task has been completed",

icon: "f05a"

}, function (ToastMsg) {

if (ToastMsg.clicked) {

// User has clicked on the toast

} else {

// The toast is being destroyed

}

});

The ToastMsg which is passed to the callback function has the following properties:

By default, a toast notification is destroyed if the user clicks on it. Therefore, unless you modify the standard behaviour using the properties described below, if the user clicks on the toast then there will be two messages: a click message with clicked:true and then a destruction message with clicked:false.

Other properties which you can use to modify the toast are as follows:

3.5.12.2Dialogs from toast clicks

There are two ways of displaying further information in response to toast clicks:

Implement a callback function, as illustrated above, and manually display a dialog in response to a message with clicked:true

Or, provide a dialog definition as part of the toast details. This automatically displays a dialog when the toast is clicked on.

An example of a dialog definition:

Framework.CreateToast({

title: "Something happened",

text: "The text of the toast",

dialog: {

type: "infodialog",

settings: {

text: "More detail to display when the toast is clicked on"

}

}

});

You can use the dialog block to create any of the common dialogs in response to toast clicks. Note: these dialogs are always and automatically made floating rather than modal.

The type for the dialog block is one of the following: infodialog, alertdialog, successdialog, or errordialog.

The settings block is simply the same properties which are passed to a function such as InfoDialog(): text, plus an optional title and button definitions.

3.5.12.3Destroying toast

The normal lifecycle is that a toast notification is destroyed when either of the following happens:

The user clicks on it

The toast reaches its expiry time (either the app's default of a few seconds, or an explicit lifespan provided when creating the toast)

There can be two exceptions to this lifespan:

The toast is given noDestroyOnClick:true in its properties. A click does not destroy the toast, and it survives until its expiry.

And/or, the toast is given a long lifespan, keeping it on screen for a long time.

In either of these circumstances, the caller may want to remove the toast manually, using Framework.DestroyToast(). For example:

// Note: no callback. DestroyToast() is fire-and-forget.

Framework.DestroyToast("1234-5678-abcd");

The ID of the toast, for passing to DestroyToast(), can be obtained in two ways:

By providing an explicit toastId in the call to CreateToast()

Using the toastId in the click callback function

For example, to display a permanent toast until the user clicks on it (replacing the automatic destruction in the event of a click):

Framework.CreateToast({

title: "Permanent…",

text: "Stays on screen until manually destroyed",

noDestroyOnClick: true,

lifespan: 999999999

}, function (ToastClickMsg) {

… some asynchronous process during which the toast remains on screen,

and then …

Framework.DestroyToast(ToastClickMsg.toastId);

});

3.6Settings and state storage

A widget, script, or UDIX can use standard browser features such as indexedDB to store and retrieve data. Remember that scripts and UDIXes are web workers, and therefore the browser does not give them access to localStorage. Only widgets can use that. You can, of course, also store data on external servers, sending and receiving it using something like XMLHttpRequest.

The framework also has its own storage mechanisms which a widget, script, or UDIX can use to store settings - saving and receiving back any JSON data. There are two important things to note about these framework features:

They are designed for storing small amounts of settings information, such as a user's most recent selection of market and timeframe etc. You should not use them to store large amounts of data (e.g. candles). The framework may ignore requests where the stringified size of your data exceeds 4KB.

You should not make rapid repeated calls to the storage functions. The framework has its own internal throttles, but instead of making lots of save-calls in quick succession you should implement a delay/queue yourself, and/or redesign your UI so that changes to settings are more monolithic and occasional.

3.6.1Types of framework storage: private and category

The framework has two types of storage: "private" and "category".

"Category" settings are data which is shared by all copies of your widget, script, or UDIX.

"Private" settings only apply to widgets, not to a script or UDIX, and only apply to widgets which have been loaded into the Figaro page container, not to a widget which has been opened in a temporary floating or pop-up window.

You can think of "private" settings as "instance" settings. If a widget is loaded into the page container then it may be loaded and unloaded as the user switches between pages, or when the user logs out and logs back in again, but it remains the same instance of that widget. Whereas the same type of widget loaded into a new or temporary window is a different instance in each temporary window.

Each time a script or UDIX is loaded, it is treated as a new instance of that script/UDIX. Therefore, scripts and UDIXes don't have private settings.

3.6.2Loading and saving category settings

You can load category settings using Framework.LoadCategorySettings(), passing the function a name which you want to identify your widget/script/UDIX. For example:

Framework.LoadCategorySettings("my-widget", function(settings) {

// Asynchronously receives existing settings, or an empty object {}

// The retrieved settings are also now available thorough Framework.categorySettings

});

As well as being sent to your asynchronous callback function, the settings data is also stored in Framework.categorySettings.

You must use LoadCategorySettings() before trying to save settings, even if you know that there are no stored settings and that it will return an empty object, {}. This is because the parameter which you pass to LoadCategorySettings() also identifies your widget/script/UDIX for later saving of data.

You should regard the ID which you use in LoadCategorySettings() as mildly sensitive. If someone else's code knows the ID which you are using, it can read and overwrite your data - which might, for example, include a password which you have asked the user for, in order to log in to some external service.

You can save category settings by using Framework.SaveCategorySettings(). You simply pass in the block of data which you want to store. For example:

Framework.SaveCategorySettings({

instrumentId: "EUR/USD",

timeframe: 3600,

visualOptions: {

color: "blue"

}

});

If there are multiple running copies of your widget, script, or UDIX, then they all - including the one which makes the change - receive a CATEGORY_SETTINGS_CHANGE message telling them about the update.

For example, let's say that you have some sort of "view" mode in your widget, switchable between mode A and mode B. If the user changes the setting in one widget, you want all other running copies of your widget to update automatically. You can do the following:

In the widget where the user has changed the selection, you use SaveCategorySettings() to store the new settings.

But you don't act on the change immediately.

Instead, you wait for the CATEGORY_SETTINGS_CHANGE message, and both the widget making the change plus any other copies of your widget all have the same single path of execution where they update themselves in response to a change in settings.

However, one final note: you should not use SaveCategorySettings() as a way of communicating between widgets (and scripts and UDIXes) unless you specifically need permanent storage of the data. If you just want to send transient information between widgets, there are better and (even) faster ways of communicating.

3.6.3Loading and saving private settings

As explained above, private settings only apply to widgets, not to a script or UDIX, and they only apply to a widget which has been loaded into the Figaro page container. Other types of component can attempt to save private settings for themselves, but the data will be quietly discarded by the framework.

A widget can save private settings using Framework.SavePrivateSettings(). For example:

Framework.SavePrivateSettings({

instrumentId: "EUR/USD",

timeframe: 3600,

visualOptions: {

color: "blue"

}

});

When this instance of the widget is next reloaded by the page container, any existing saved settings will be present in Framework.privateSettings. (Unlike category settings, private settings are immediately and automatically available, and do not need a separate asynchronous load.)

3.6.4Combining category settings and private settings

A widget may have both private settings and category settings, and it is entirely up to you how you combine them. A typical - but absolutely not compulsory - path of execution would be:

If privateSettings are not empty, use those

Load category settings

If categorySettings are then not empty, use those

Otherwise, use defaults

Note: if your settings involve a selection of market or timeframe, you may want to include an extra step: respecting context from the Figaro page container.

The only extra consideration then is that, even if there are private settings, you may still want to call LoadCategorySettings() anyway, because you need to call LoadCategorySettings() first if you ever want to save category settings.

For example, using FXB.utils.IsEmpty() as a helper to check for empty objects:

Framework.OnLoad = function() {

// Start with a null value

Framework.$myState = null;

// If private settings exist, set the record of the state

if (!FXB.utils.IsEmpty(Framework.privateSettings)) {

Framework.$myState = Framework.privateSettings;

}

// Always do a LoadCategorySettings(), even if we have private settings

Framework.LoadCategorySettings("my-widget", function(categorySettings) {

if (Framework.$myState) {

// If we already have private settings, ignore the category settings

} else {

// Put the category settings - which may be empty - into the state

Framework.$myState = categorySettings;

}

// If myState is still empty, because we have neither private nor category

// settings, then use some defaults

if (FXB.utils.IsEmpty(Framework.$myState)) {

Framework.$myState = { … some defaults … };

}

// And, finally, do UI initialisation based on the settings or defaults

Framework.$UpdateMyUI();

});

};

3.6.5Widget state (for new windows etc)

The user can choose to take any widget in the Figaro page container and pop it out into a new browser window. You can copy the settings from the existing widget into the new window using a mechanism very similar to, and often related to, privateSettings.

You need to handle Framework.OnGetState() which the framework calls in order to ask you, "Do you have any stored settings which you want to pass into the new window?". For example:

Framework.OnGetState = function()

{

return {

instrumentId: "EUR/USD",

timeframe: 3600,

visualOptions: {

color: "blue"

}

};

}

The new pop-up browser window will receive this stored state in its Framework.privateSettings.

As a result, it's very common for a widget's storage of private settings and its handling of OnGetState() to be linked. For example:

The widget uses OnGetState() as a general function for building a representation of its current settings.

When saving private settings as a result of a user change, the widget calls its own OnGetState() function.

For example:

// Build some representation of the widget's state. This is returned both internally

// and to the framework when opening a new window.

Framework.OnGetState = function() {

var settings = { … };

return settings;

};

// Private internal function which our widget calls whenever the user makes a change

// and new settings need to be saved. We simply re-use OnGetState() as a way

// of getting the current state.

Framework.$SaveMySettings = function() {

Framework.SavePrivateSettings(Framework.OnGetState());

}

Note: OnGetState() is also the mechanism which allows a widget to keep running even if the user navigates to a different page of the app.

3.6.6Saving both private and category settings

It is very common for a widget's private and category settings to be the same thing. For example, if you make a change in Figaro's standard quote board such as switching the view between grid and deal tickets then that doesn't alter other open quote boards - they ignore CATEGORY_SETTINGS_CHANGE - but the most recent changes do become the default for all new future instances of the quote board.

In other words, on a change of settings, it's very common for a widget to do the following:

var newState = Framework.OnGetState(); // See example above

Framework.SavePrivateSettings(newState); // Private settings for this instance

Framework.SaveCategorySettings(newState); // Use same settings as defaults for new instances

This can be made slightly more efficient by combining the two saves into a single call to Framework.SaveSettings(). This takes two parameters: private settings first, category settings second. The above example would then become:

var newState = Framework.OnGetState();

Framework.SaveSettings(newState, newState);

3.7Interacting with the Figaro page container and environment

3.7.1Handling context - synchronization in the page container

This section is only applicable to widgets. A script or UDIX cannot (directly) be part of the Figaro page container.

If your widget offers a selection of market or timeframe, you may want to respect "context" where the user can choose to synchronize the markets and/or timeframes on a page. Doing this consists of three parts:

Reading any context when your widget starts up

Handling changes of context while your widget is running

Sending changes of context to the page container if the user changes the market or timeframe selection from inside your widget

Any existing context on start-up is provided by the Framework.context property. If present, this may contain one or both of an instrumentId and a timeframe. The typical way of handling this is to inspect it and, if present, to use it to override any private or category settings which the widget has.

The example above about widget settings has the following code:

... code which examines private and category settings, and builds Framework.$myState …

// And, finally, do UI initialisation based on the settings or defaults

Framework.$UpdateMyUI();

A typical way of handling context would be, as a final stage after loading stored settings or using defaults, to overwrite any market or timeframe selection if the page container is providing context. For example:

... code which examines private and category settings, and builds Framework.$myState …

// The addition:

// If the page container has instrument context, overwrite whatever settings we have built up

if (Framework.context && Framework.context.instrumentId) {

Framework.$myState.instrumentId = Framework.context.instrumentId;

}

// And, finally, do UI initialisation based on the settings or defaults

Framework.$UpdateMyUI();

There may also be changes in context while your widget is running, as a result of the user changing the market and/or timeframe selection in another widget. You receive these changes as a WIDGET_CONTEXT_CHANGE message, and you would typically handle it the same way as the user changing the selection within your own widget.

Finally, if the user changes the market and/or timeframe selection within your own widget, using your own UI, you broadcast that change to any other widgets in the same page as yours. You do this using Framework.ReportContext(). For example:

Framework.ReportContext({

instrumentId: <new market selection>,

timeframe: <new timeframe selection>

});

3.7.2Changing the market or timeframe of the current page

Any widget, script, or even UDIX can change the context of the current page in the Figaro container without being part of the current page, using the functions Framework.SetCurrentPageInstrument() and Framework.SetCurrentPageTimeframe().

For example, the following script sets up a "slideshow", cycling the current page between different markets every 5 seconds until the script is terminated by the user:

var instrumentList = ["EUR/USD", "USD/JPY", "GBP/USD", "USD/CHF"];

var currentIndex = -1;

setInterval(function() {

currentIndex++;

if (currentIndex >= instrumentList.length) currentIndex = 0;

Framework.SetCurrentPageInstrument(instrumentList[currentIndex]);

}, 5000);

3.7.3Changing the current page displayed in Figaro

You can change the current page which is being displayed in Figaro using Framework.NavigateToPage().

The parameter for this function is the user-controlled name of the page, such as "Quote board", or "My new page". There is no mechanism for saying "go to the quote board, whatever the user has called the page", or "go to the first/any page which contains the quote board widget".

3.7.4Chart actions

Figaro provides functions which allow any widget, script, or UDIX to make changes either to all open charts, or just to the active chart (the one which the user last clicked on). This is done using Framework.ChartChange().

The Run Script widget in Figaro serves as a full and interactive guide to the available chart actions. You can get information on how to build chart-change code by using the options in the Run Script widget.

3.7.5Chart widgets

A widget can be loaded as a "chart widget", into the chart's dock area as used by the built-in Market Timer and Notepad indicators. You do this by choosing Add Indicator > External Widget from a chart. Widgets which are loaded in this way have access to some extra features, letting them behave like user-defined indicators (UDIs). They can create drawings, event markers, or bar highlights on the chart.

You can detect whether your widget is loaded as a chart widget by checking privateSettings.isChartWidget. If this is not turned on, the following features will not be available, and attempting to use a function such as ChartWidget_CreateDrawing() will raise an exception.

3.7.5.1Getting and setting the chart instrument and timeframe

Chart widgets receive the chart's selected instrument and timeframe in their Framework.context, and subsequent changes are similarly received as a WIDGET_CONTEXT_CHANGE message. Your widget can also detect the selected instrument and timeframe, together with a list of the chart's candles, using a ChartWidget_OnContextChange() handler.

A chart widget can change its chart's instrument and/or timeframe by using ReportContext().

3.7.5.2Chart widget dock title

Each component in the chart's dock area has a title, and by default the platform will use the <title> from your HTML. Your widget can change its title while it is running by using Framework.ChartWidget_SetTitle().

3.7.5.3Chart widget height

By default, chart widgets take up all available space in the dock. If you instead want to use a fixed height, like the built-in Market Timer indicator, then you can do this by passing a number of pixels to Framework.ChartWidget_SetHeight().

3.7.5.4Chart bar data and events

Chart widgets can receive the chart's bar data by defining a ChartWidget_OnContextChange() handler. The parameter which is passed to this function contains a candles[] array, as well as an instrumentId and timeframe. The handler is called on initial load of your widget, followed by any addition to the list of candles or any re-load following a change of instrument or timeframe.

Changes to the current in-progress candle can be received using a ChartWidget_OnCandleChange() handler. The parameter passed to this function contains a single candle object.

For example:

Framework.ChartWidget_OnContextChange = function(data) {

// Store the list of candles in data.candles[]

}

Framework.ChartWidget_OnCandleChange = function(data) {

// Update the previous stored list from data.candle

}

3.7.5.5Drawings, event markers, and bar highlights

Chart widgets have similar features to user-defined indicators. They can create drawings, event markers, bar highlights, and additional HTML on the chart. For example:

Framework.ChartWidget_CreateDrawing({

type: "horizontalLine",

points: [{value: 1.2345}],

style: {line: {color: "red"}}

});

These functions are described in detail in the UDI documentation at https://www.fxblue.com/figaro/udi/help. Each UDI function has an equivalent framework function, prefaced with ChartWidget_.

A few further notes:

Like the UDI functions, framework functions such as ChartWidget_CreateDrawing() can be given either a single item as a parameter or an array.

Like the UDI functions, you can pass a callback to ChartWidget_CreateDrawing() and ChartWidget_CreateEventMarker() in order to receive the ID(s) of the created drawing(s) or marker(s).

If you set wantClick:true in your definition for an event marker, clicks on the marker are sent to a ChartWidget_OnEventMarkerClick() handler.

Messages sent by HTML which you create are sent to a ChartWidget_OnHTMLMessage() handler.

3.8Communicating between widgets/scripts/UDIXes

Different instances of a widget, script, or UDIX can share saved "category" settings as described above, with notifications when the shared settings change.

It is also possible for different widgets, scripts, and UDIXes to send messages to each other without permanent data storage. This comes in three parts.

Every widget, script, or UDIX has an ID, Framework.id.

A component which is interested in talking to another component sends out a broadcast message.

The other component(s) receive the broadcast message, in OnMessage(), and can see the sender's ID. They can now send a direct message back. On receipt of a direct message (or a broadcast message), the original sender can now see the recipient's ID, and send further direct messages.

You send messages using Framework.PostMessage(). The only compulsory parameter is an FXB.Message object, which you can construct as follows. The initialisation must have a msgType property, and can then contain any other data that you want.

The framework has special message types for widgets to exchange ad hoc data. There are BROADCASTx messages which can be sent without knowing a recipient's ID, and GENERICx messages which can be used for direct, peer-to-peer communication.

For example:

var myMessage = new FXB.Message({

msgType: FXB.MessageTypes.BROADCAST1, // A msgType is compulsory for FXB.Message

myAction: "Want to chat?",

anyOtherData: {

moreData: 231,

},

someProperty: someValue

});

Framework.PostMessage(myMessage);

Broadcast messages are sent to all other widgets, scripts, and UDIXes in the platform. Those can then listen for broadcasts in OnMessage(), and choose to respond. For example:

Framework.OnMessage = function(Msg) {

if (Msg.is(FXB.MessageTypes.BROADCAST1)) {

// Is this a message which we understand?

if (Msg.myAction && Msg.myAction == "Want to chat?") {

// Send a response

var response = new FXB.Message({

msgType: FXB.MessageTypes.GENERIC1,

_to: Msg._from, // The _from of the Msg gives us the sender's ID

myResponse: "Yes, I want to chat"

});

Framework.PostMessage(response);

}

}

};

When a component receives a message, the _from property tells it the sender's ID. This gives it the ability to construct a direct message back to the sender, by setting the _to property in a response message - as in the example above.

The original sender could then listen for acceptance of its original broadcast as follows:

Framework.OnMessage = function(Msg) {

if (Msg.is(FXB.MessageTypes.GENERIC1)) {

// Is this a message we understand?

if (Msg.myResponse && Msg.myResponse == "Yes, I want to chat") {

// The recipient of broadcast knows this sender's ID,

// and this sender now knows the responder's ID because

// it is the _from of this response message

}

}

};

Once a direct connection is established, there is a further mechanism which can simplify the sender/response code. The Framework.PostMessage() function has an optional second parameter: an asynchronous callback which receives responses. This is called if a recipient of a message uses Framework.Respond().

For example, once they have each other's IDs, one component can send a message to another component as follows:

Framework.PostMessage(myNewMessage, function (Msg) {

// Callback triggered by the recipient using Respond().

// The response message also passes through OnMessage(), but handling it "inline"

// like this will often be simpler and cleaner.

});

The recipient triggers the response callback in the sender by using Framework.Respond() instead of Framework.PostMessage(). The Respond() function takes two parameters: the new message to send back, and the message to respond to. For example:

var myResponse = new FXB.Message({

msgType: FXB.MessageTypes.GENERIC1,

myData: "some communication"

});

Framework.Respond(myResponse, someOriginalMessage);

(If you are using Respond(), you don't need to set an explicit _to on the message you are sending. Respond() fills this in for you.)

The one thing to note is that an asynchronous callback for PostMessage() is only called once (or not at all, if nothing responds). If you use an asynchronous callback with a broadcast message, then it will only receive the first response, and be terminated after that. If there are second and subsequent responses from other components, then those will be ignored (unless also separately handled in OnMessage).

In other words: an asynchronous callback on PostMessage() is great for direct, peer-to-peer messages, but generally not suitable for broadcast messages unless you are specifically only expecting a single response.

3.9Time conversion functions

All times in the framework - such as the openTime of an order or the ts of a candle - are UTC. The framework provides a variety of functions for helping with time conversion.

Note: all the parameters and return values for the framework's date functions are numbers (of milliseconds), not Javascript Date objects.

3.9.1Time zone definitions

The framework uses the following properties to define a timezone:

For example, the following defines a base offset 2 hours ahead of UTC, changing into daylight savings (UTC+3) on the USA schedule:

timezone: {

offset: 120,

dstMode: FXB.DSTModes.USA

}

Note: this is a time zone widely used in forex trading, but not a setting you will ever see on a normal clock. It is widely referred to as "central European time" or "Cyprus time" (because many fx brokers are based there), but that is not what it is. It is 2/3 hours ahead of UTC, but it changes on the USA daylight-savings schedule, not the European schedule. It will be the same as Cyprus time for most of the year, but it will be different during the periods when the USA is in daylight-savings but Europe is not.

3.9.2Getting the current time - Framework.Now()

The Framework.Now() function returns current UTC time, in milliseconds, according to the computer clock.

It is therefore almost entirely equivalent to new Date().valueOf(). However, the framework includes a time check with the Figaro server, and watches for computer clocks which are materially wrong (current threshold: >30 seconds wrong). One of the most common issues it picks up is a clock which the user has changed to local time without adjusting the computer's time zone. The result is that the computer clock shows the "correct" local time to the user, but its calculation of UTC is hours out.

If the framework detects a problem with the local clock, Framework.Now() will return an adjusted time, correcting for errors in the local clock.

3.9.2Converting between UTC and a different time zone

The function Framework.AdjustUTCToZone() converts from UTC to a different time zone. It takes two parameters: a UTC time in milliseconds and a timezone description. For example:

var someDate = new Date(Date.UTC(2020, 6, 1, 0, 0, 0)); // July 1^st 2020, midnight UTC

var newYork = Framework.AdjustUTCToZone(someDate.valueOf(), {

offset: -300, /* USA east coast at UTC-5 with daylight savings */

dstMode: FXB.DSTModes.USA

});

This will return 1593547200000. Javascript has no way of specifying that a Date object belongs to a particular zone. What AdjustUTCToZone() has to do is to return a date/time where the UTC functions such as getUTCHours() will give the adjusted time.

To put it another way, 1593547200000 represents June 30^th 8pm UTC - the original time adjusted backwards by 4 hours (not 5 hours, because the USA was in daylight savings on the specified date). For example:

var date = new Date(1593547200000);

var hours = date.getUTCHours(); // Returns 20

var dayOfMonth = date.getUTCDate(); // Returns 30

var month = date.getUTCMonth(); // Returns 5 (June)

You can do the conversion in the opposite direction using Framework.AdjustZoneToUTC(). You pass in a number of milliseconds which represents a date/time in another zone, and the function adjusts that to UTC. For example:

var newYork = 1593547200000;

var utcTime= Framework.AdjustZoneToUTC(newYork, {

offset: -300, /* USA at a UTC-5 with daylight savings */

dstMode: FXB.DSTModes.USA

});

This reverses the process in the example above and returns 1593561600000 - July 1^st 00:00 UTC.

3.9.3The user's time zone preferences

The settings in Figaro let the user set two different default time zones: one for charts, and one for general purposes such as open and close times in the trade list. These will normally be the same value, but don't have to be.

You can get the user's preferences using Framework.GetUserChartTimezone() and Framework.GetUserGeneralTimezone(). These both return timezone definitions, like the examples above.

For example, you can convert a UTC date/time to the user's general time zone using:

var userTime = Framework.AdjustUTCToZone(someUtc, Framework.GetUserGeneralTimezone());

It's up to you whether you respect the user's preferences and convert a date before displaying it - and it may not always be appropriate to do so, if you are dealing with something where the user will expect to see their local time despite their preferred settings for the platform.

3.10Helper functions for formatting values

The framework has a variety of functions for doing standard formatting of numbers, dates, prices etc.

3.10.1Framework.FormatNumber()

FormatNumber() is a general-purpose function for formatting numbers. It has two parameters: the number to convert, and a block of options. For example:

var text = Framework.FormatNumber(1234.5678, {digits: 3, show_plus: true})

// With standard settings, returns "+1,234.568"

3.10.2Framework.FormatCash()

FormatCash() formats a currency amount. It is a simple bare wrapper around FormatNumber(), and accepts the same options as FormatNumber(). It is intended to be used with digits:null rather than a specific number, and then automatically selects a number of digits to use based on the account deposit currency. For example, on a JPY account it will convert the value at 0DP.

3.10.3Framework.FormatPercent()

FormatPercent() formats a percentage, appending a % symbol. It is a simple bare wrapper around FormatNumber(), and accepts the same options as FormatNumber(). The position of the % symbol depends on the user's selected language for the Figaro platform: prepended for Japanese; appended for everything else.

3.10.4Framework.FormatVolume()

FormatVolume() formats a trading volume. By default, it reads the user's preferences in the Figaro settings about whether volumes should be displayed as cash/units or lots. For example, volume of 20000 may be formatted as either "0.20 lots" or "20K".

Because lot-size conversion is market-specific, the FormatVolume() function requires an FXB.Instrument. For example:

var market = Framework.Instruments.get(instrumentId);

var text = Framework.FormatVolume(20000, market, {append_lots:true});

// For example, text = "0.20 lots"

FormatVolume() has three parameters:

FormatVolume() is again a wrapper around FormatNumber(). You can use the full features of FormatNumber(), but typically you will only want to use the following properties in the options:

3.10.5Framework.FormatDate()

FormatDate() formats a date, by default in the format yyyy/mm/dd hh:mm:ss

The possible options for FormatDate() are as follows:

3.10.6Framework.DisplayPrice()

DisplayPrice() formats a price into an HTML element, rather than returning text. This is because it implements Figaro's standard formatting of prices such as 1.23456 which requires HTML representation, with specific CSS classes, rather than plain text. (Therefore, DisplayPrice() is only relevant to a widget, not to a script or UDIX.)

Note: the DOM node which receives the output must be empty on first use of DisplayPrice().

The parameters for DisplayPrice() are as follows.

For example:

<!-- Note: the element which is the target of DisplayPrice() must be empty on the first call -->

<span id="bid"></span>

…

var market = Framework.Instruments.get("EUR/USD");

Framework.DisplayPrice("bid", market, market.bid);

3.10.7Generating a textual description of an order or trading action

Framework.DescribeOrderOrTemplate() turns an FXB.Order or a trading request into a textual description such as "Buy 0.20 lots EUR/USD". Note: the resulting text is automatically run through the Translation system and will be adjusted to the user's selected language.

For example:

// Generate a caption for trade with orderId T12345

var tradeCaption = Framework.DescribeOrderOrTemplate(Framework.Orders.get("T12345"))

// Generate a caption for a trading request to sell 0.20 lots EUR/USD

var requestCaption = Framework.DescribeOrderOrTemplate({

tradingAction: FXB.OrderTypes.SELL,

instrumentId: "EUR/USD",

volume: {lots: 0.2}

});

3.11Trading validators

Trading validators are not - currently - used by any built-in part of the Figaro software itself. They are a service which is provided solely for use by third-party code, to extend the platform.

A trading validator receives notification of all trading requests passing through Figaro, and has the option to block them. The idea is that a trading validator can implement custom checks on trading activity such as the following:

Is the spread on a market too wide?

Is the time too close to a high-impact event in the economic calendar?

Does the open volume on a market mean that we don't want to allow a further trade?

Do we want to prevent pending orders without expiry?

Do we want to block trading entirely?

You register your widget or script (or even UDIX) as a trading validator by calling Framework.AddTradingValidator(). To deregister it, and stop receiving validation messages, you call Framework.RemoveTradingValidator().

Once you have called AddTradingValidator(), all trading requests throughout the platform get submitted for approval to your widget or script. This happens after a request has passed all Figaro's internal validity checks, but before the request is sent to the broker for execution.

Requests are sent to a function called Framework.OnTradeValidation(). This must return a synchronous response, in order not to delay trading unduly. You cannot look up some asynchronous data, such as the economic calendar, and then later send a response to the validation request once you have the data you need. To set up a check such as the economic calendar, you will typically request the calendar (asynchronously) while simultaneously registering as a validator. If you get a validation request before you have the calendar data to verify it, it is up to you whether you accept or reject the validation request.

OnTradeValidation() rejects a request by returning {status: "block"}, or specifies that the user must manually confirm it by returning {status: "confirm"}. Any other return value allows the request to go ahead. For example:

Framework.OnTradeValidation = function(Msg) {

if ( … some condition we don't like … ) {

// Block and reject the request

return {status: "block"};

} else if ( … some condition we're not sure about … ) {

// Show a confirmation dialog to the user (which may

// happen anyway, depending on other settings and controls)

return {status: "confirm"};

} else {

// Allow the trading action to proceed

return null; // or {status: "okay"}, or anything apart from status:"block"/"confirm"

}

};

If you return {status: "block"} then you can also add blockText into your response. This message is added to the standard rejection message to the user. For example:

return {status: "block", blockText: "Are you mad?"};

Similarly, if you return {status:"confirm"} then you can add confirmText to the response.

Your validator receives two pieces of information in the Msg message which is passed into OnTradeValidation():

There are two things to note about the array of tradingJobs[]:

You cannot approve or reject individual requests within the array. You can only approve the whole batch or reject the whole batch.

What you receive in tradingJobs[] is a list of trading actions dis-aggregated into the low-level requests such as opening or closing individual orders. For example, if the user clicks Close > All in the built-in Figaro trade list widget, or a script uses the equivalent FLATTEN trading action, then what you will get in tradingJobs[] is not a single FLATTEN request but instead a separate entry in the array for each individual ticket which is going to be closed/deleted.

3.12Market depth and order book

Availability of market depth and order book data depends on the capabilities of the current logged-in trading account. They are not widely available.

In this context, "market depth" generally refers to institutional liquidity arranged by a broker, showing quotes below the best bid and offer in a market. "Order book" generally refers to traders' orders, on a peer-to-peer basis in an exchange. If the back-end platform provides an order book, it may be an aggregated view rather than all individual orders - e.g. price bands of 0.0010 with a totalled summary of the orders within each band.

3.12.1Market depth

The framework always responds to market depth requests, even if no depth data is available from the back-end system. What it will then send is simply changes in the current bid and ask, with no trading volume.

Where market depth is available, the back-end system may send either of the following:

Multiple quotes at each price (from different liquidity providers)

A single quote at each price

You request market depth using Framework.RequestMarketDepth(). This has one compulsory parameter and two optional parameters:

For example:

// Allow the framework to allocate an ID for the request, reported as the requestId in messages

Framework.RequestMarketDepth("EUR/USD", null, function (Msg) {

// Response containing market depth, also received in/via OnMessage()

// ID of the request, for use in termination, will be in Msg.requestId

});

You should terminate market depth requests when you no longer need them, using Framework.TerminateMarketDepth(). The function takes two parameters: the instrument ID, and the request ID allocated either by you or the framework.

Each market-depth update message has the following properties:

The changes object contains two arrays of changed quotes: asks[] and bids[]. Each item in these arrays can have the following properties:

The depth object contains the current full book following the changes; you don't need to calculate this yourself.

As noted above, the back-end system may have multiple quotes at each price (from different liquidity providers). The depth summary calculates both individual current quotes and also the aggregated volume at each price (which will be the same thing if the back-end system only issues aggregated quotes).

The depth object contains the following properties:

A couple of final notes:

You need to be a little careful with this data. During unusual market conditions, or just very briefly during updates, it is possible for there to be no quotes on the bid side or ask side (or even both). Therefore, you cannot safely assume that aggregated.asks.length or aggregated.bids.length is greater than zero.

Internally within the broker's back-end system, it is possible for there to be different routes for market depth versus "trading" prices. It is not absolutely guaranteed that the bestBid and bestAsk in the market depth will match the current bid and ask of the FXB.Instrument.

3.12.2Order book

Order book - where available - is handled very similarly in the framework to market depth. This section mostly describes the differences rather than repeating identical information.

The key differences are as follows:

The order book may include entries on both sides of the current price - users' stop orders as well as limits - whereas market depth will only have entries at and "below" the current price.

The back-end system may list the order book as any of the following: every individual order, or aggregated totals of the orders at each price, or aggregated totals for bands of prices such as 0.0010. In the two latter cases the order-book messages from the framework will have a granularity property, such as 0.00001 or 0.0010.

The volumes in the order book may not be normal trading volumes; they may be a different kind of value such as percentages of the total open volume. You can only rely on the volume figures having meaning relative to each other; you cannot rely on each one having independent validity in relation to the market's contractSize.

Order book for a market must be requested, using Framework.RequestOrderBook(), and terminated when no longer needed, using Framework.TerminateOrderBook().

The parameters for RequestOrderBook() are the same as RequestMarketDepth(): an instrumentId, an optional request ID, and an optional message handler (instead of processing the messages in OnMessage).

You should terminate requests when you no longer need them, using Framework.TerminateOrderBook(). The function takes two parameters: the instrument ID, and the request ID allocated either by you or the framework.

The ORDER_BOOK response messages, in an asynchronous handler or in OnMessage(), are identical to the MARKET_DEPTH responses described above. The message contains the changes plus the full current book.

ORDER_BOOK responses have one further property, as mentioned above:

3.13Economic calendar

The Figaro framework provides access to an economic calendar - unless the hasCalendar property of Framework.Environment indicates that no calendar is available in the current platform.

Widgets, scripts, and UDIXes can request the calendar using Framework.RequestCalendar(). This responds, asynchronously, with an object containing a calendarItems[] array. There can be further callbacks into the asynchronous handler function when items are added to the calendar, or when existing items are updated with new information. For example:

Framework.RequestCalendar(function (Msg) {

// This function can be called multiple times.

// There will be an initial asynchronous call with the current state of the calendar,

// potentially followed by updates.

// Msg.calendarItems[] is an array of new and/or updated items

});

Each item in the calendar array has the following properties. Note: there can be variation in the data depending on the source of the calendar. Only the ID, title, and timestamp are absolutely guaranteed to be available across all calendar providers.

3.14The Figaro mail system

This section describes Figaro's internal mail system - not email. Widgets, scripts, and UDIXes can send email by using browser XMLHttpRequest to communicate with an email provider such as SendGrid or Amazon SES.

3.14.1Availability of the mail system

Some versions of the Figaro platform may not have a mail system. You can check availability of mail functionality by inspecting the hasMailSystem property of Framework.Environment.

3.14.2Overview of the mail system

Mail in Figaro is sent to devices, not to people or to trading accounts. Each device is identified for mail by an 8-character code such as DMZLXCVG. This ID is shown in the send-mail window in Figaro.

A widget, script, or UDIX can easily send a message to its own device - the current user - without needing to know the device's mail ID. But the following two things are entirely deliberate:

A widget, script, or UDIX cannot programmatically discover the mail ID of its own device

There is no way of discovering the ID of another device without that device's user looking it up, in the mail-sending dialog, and choosing to tell it to you

It is also possible to send mail into Figaro from outside the platform, from any environment which can make HTTP requests.

3.14.3Sending mail

A widget, script, or UDIX can send three types of message:

A local, transient message. These only exist within the running Figaro app, and are destroyed when the user logs out of their current trading account or reloads the app.

A remote message to the current device. These are stored permanently until the user chooses to delete them. The widget, script, or UDIX doesn't need to know the ID of the current device.

A remote message to another device. The widget, script, or UDIX must know the ID of the device it is sending to.

Remote messages are subject to a quota, regardless of whether they are being sent to the current device or another device. Your device's ability to send mail will be temporarily blocked if you try to send too many remote messages. If you are using the mailbox as an alerting mechanism, you should make sure that you don't do something such as entering a loop where you generate the same alert over and over again. (In extreme cases, this can even lead to mail from the device being permanently blocked.)

You send mail using Framework.SendMail(). This takes two parameters: a definition of the mail to send, and an asynchronous callback which receives success or failure. For example:

Framework.SendMail({

subject: "A new message"

}, function (Msg) {

if (Msg.success) {

// Mail successfully sent

} else {

// Mail failed. Error reason will be in Msg.error

}

});

The mail request can have the following properties. The subject is the only compulsory property:

The priority level - only available on messages to the current device - can be one of the following values between 0 and 3:

The optional body of a message can be three things (subject to the 4KB limit):

Plain text

HTML - a full HTML document with <html> and </html> opening and closing nodes

The URL of a web page, subject to the usual browser security restrictions

An HTML document or web page is displayed in a sandboxed iframe, and has no framework access.

3.14.4Receiving mail

A widget, script, or UDIX can read the mailbox by using Framework.RequestMail(). This will issue an immediate (asynchronous) MAILBOX message to OnMessage(), followed by further MAILBOX messages whenever there are changes in the mailbox.

A MAILBOX message has a mail[] array listing all the messages currently in the system. It always lists all messages. On receipt of new mail, the MAILBOX message will contain the entire mailbox, not just the new message.

Widgets, scripts, and UDIXes can only see user-to-user messages. They cannot see messages issued by the broker. This is because those may contain sensitive information such as account passwords.

3.15Miscellaneous functions

This section covers any remaining functions which do not fall into any of the previous categories above.

3.15.1Generating downloads

You can trigger a download of data by using Framework.CreateDownload(). For example, Figaro's built-in Account History widget uses this to do a download of the history in CSV format.

In a web browser, CreateDownload() simply triggers a download of the file. In the mobile/tablet app, it integrates with the device's notification centre, with options for sending the file to another app, saving it in the phone's storage etc.

CreateDownload() takes a single description object as a parameter which must contain the following properties:

For example:

CreateDownload({

fileName: "mydata.csv",

mimeType: "text/csv",

data: "Header1,Header2,Header3\r\nData1,Data2,Data3\r\netc"

});

4Messages and event handlers

You can listen for changes in prices, the order list, account metrics etc using an OnMessage() handler. For example:

Framework.OnMessage = function(Msg) {

if (Msg.is(FXB.MessageTypes.PRICE)) {

… update a quote board

}

};

Some types of message such as changes to account metrics are issued automatically. Other types of message, such as prices or account history, must be specifically requested by your widget/script/UDIX.

By the time that message handlersare called, the framework's objects and collections have already been updated. For example, if you receive an ORDER_OPEN message, the new order(s) will already be present in the Framework.Orders collection.

As well as using the main OnMessage handler, you can also define individual handlers for some types of message. For example, you can define an OnPriceChange function. All price changes are then sent to that function as well as to the main OnMessage handler.

It's possible for your code to have multiple message handlers (each of which receives all messages). You can do the following as well as or instead of using OnMessage().

var handler1 = Framework.AddMessageHandler(function (Msg) { … a handler function});

var handler2 = Framework.AddMessageHandler(function (Msg) { … a second handler });

The return value from AddMessageHandler() is an ID which assists with the common Javascript problem of detaching anonymous functions. If you only need a message handler temporarily, you can store its ID and then later disconnect it using RemoveMessageHandler():

Framework.RemoveMessageHandler(handler1);

Note: you may observe that everything passes through OnMessage: initial load, results of trading actions etc. It's possible to handle the results of something like a trading action by watching OnMessage rather than supplying a callback function to SendOrder(). But there's generally no good reason to do that, and this section of the guide only covers the expected uses of OnMessage.

4.1Multiple updates in a single message

The framework can issue multiple updates in a single message. For example, a single message and a single call to OnMessage can contain changes to multiple prices and also updates to the order list.

Therefore, you should generally process messages along the following lines:

Framework.OnMessage = function(Msg) {

if (Msg.is(FXB.MessageTypes.PRICE)) {

… update a quote board

}

if (Msg.is([FXB.MessageTypes.ORDER_OPEN, FXB.MessageTypes.ORDER_CLOSE])) {

… update a trade list

}

};

The following - else-if instead of if-if - is not safe because a message may be both a price update and an order update, and the order update will be ignored by the code if the message is also a price update:

Framework.OnMessage = function(Msg) {

if (Msg.is(FXB.MessageTypes.PRICE)) {

… update a quote board

// NOT SAFE!

} else if (Msg.is([FXB.MessageTypes.ORDER_OPEN, FXB.MessageTypes.ORDER_CLOSE])) {

… update a trade list

}

};

4.2The FXB.Message object

The parameter which is passed to OnMessage() is an FXB.Message object. This is a Dictionary, because a message can contain multiple types of update.

In addition to the list of message-types in the message, which you can test using the Dictionary's is() or has(), there can be further properties in the object depending on the type(s) of message. For example, a PRICE message will contain a quotes[] array of new prices. These extra properties are described below.

4.3Types of message

The types of message which you can receive via OnMessage() are as follows, from the FXB.MessageTypes enumeration:

4.4FXB.MessageTypes.PRICE and OnPriceChange

You need to request messages for the prices you are interested in. You don't automatically receive notifications about all price changes.

Once you have requested price updates, there are two ways of receiving and processing them:

By using the main OnMessage handler, and listening for the PRICE message

By defining an OnPriceChange handler

There is a subtle difference between these two routes:

PRICE messages may contain other instruments, in addition to those you have requested, in their quotes[] array.

The OnPriceChange handler is guaranteed only to be called in relation to the market(s) you have requested.

4.4.1PRICE messages in OnMessage

Whenever there is a change to a requested price, the main OnMessage handler receives a PRICE message. For example:

Framework.OnMessage = function(Msg) {

if (Msg.is(FXB.MessageTypes.PRICE)) {

Msg.quotes[] contains a list of price changes

}

…

};

The FXB.Message object will contain a quotes[] array listing the changed prices. You may receive notifications for other markets in addition to the one(s) you have requested. For example, if you have only requested prices for a single market, you cannot rely on quotes.length being 1.

Each object in the quotes[] array has the following properties:

You can react to the changed prices either by looking at the quotes[] array, or by looking at the prices in the Framework.Instrumentscollection which will already have been updated.

The updateMarker is a bit-mask of what is changing in a quote. This is designed to help you minimise the work in updating a user interface. For example, if the bit-mask contains FLAG_PRICE_BID but not FLAG_PRICE_ASK, then you know that you only need to update the display of the bid price. You don't need to make the browser to do extra work updating an ask price which hasn't changed.

The possible flags are members of the FXB.UpdateFlags enumeration:

4.4.2OnPriceChange handler

Instead of using the main OnMessage handler, you may find it easier to watch price changes using an OnPriceChange handler. If defined, this is called by the framework with each individual price which is changing:

Framework.OnPriceChange = function(quote) {

// The quote object contains the same time, bid, ask etc properties listed above

};

4.5FXB.MessageTypes.ORDER_x and OnOrderX handlers

There are two ways of tracking changes in the order list (which includes both pending orders and open trades):

By using the main OnMessage handler to listen for the ORDER_OPEN, ORDER_CHANGE, and ORDER_CLOSE messages

By defining any or all of OnOrderOpen, OnOrderChange, and OnOrderClose handlers

4.5.1ORDER_x messages in OnMessage

The ORDER_OPEN, ORDER_CHANGE, and ORDER_CLOSE messages are issued on changes to the order list (which includes both pending orders and open trades).

ORDER_CHANGE is issued for changes in the current price and/or profit on an open trade, as well as trading actions such as moving its stop-loss.

The FXB.Message object will contain arrays listing the new/changed/closed orders:

A single message from the framework can contain multiple updates, and therefore the message may contain all of these arrays. For example:

Framework.OnMessage = function(Msg) {

if (Msg.is(FXB.MessageTypes.ORDER_OPEN)) {

… process changes in Msg.ordersOpened[]

}

if (Msg.is(FXB.MessageTypes.ORDER_CLOSE)) {

… process changes in Msg.ordersClosed[]

}

};

Each item in one of these arrays is simply an FXB.Order object describing the new/changed/closed order or trade.

You can react to the changes either by looking at the arrays of orders, or by looking at the Framework.Orderscollection which will already have been updated.

However, in addition to the standard members of FXB.Order, each item in the arrays also has an updateMarker. This is a bit-mask describing what has changed about the order. Particularly for changes rather than opens and closes, this is designed to help you minimise the work in updating a user interface, avoiding updates to HTML elements which don't need to be changed.

The possible flags are members of the FXB.UpdateFlags enumeration:

4.5.2OnOrderX handlers

Instead of using the main OnMessage handler, you can also track changes in the order list using the functions OnOrderOpen, OnOrderChange, and OnOrderClose. (You don't have to define all three of these. If you are only interested in new opens, then you only need to define OnOrderOpen).

Each of these handlers receives as a parameter the individual order which is being opened, changed, or closed. For example:

Framework.OnOrderOpen = function(newOrder)

{

// newOrder is an FXB.Order describing the new trade or pending order

};

4.6FXB.MessageTypes.POSITION_CHANGE and OnPositionChange

You can listen for changes in the changes in the Framework.Positions list in two ways:

By using the main OnMessage handler to listen for the POSITION_CHANGE message

By defining an OnPositionChange handler

In both cases, position updates are not issued for changes in profit (or current price). They are only issued for changes in the net position caused by an order opening or closing. If you want to update a display of the profit on a net position, then you need to do something such as watching the market's price as a prompt telling you that the profit will have changed.

4.6.1POSITION_CHANGE message in OnMessage

The POSITION_CHANGE message is issued about changes in the Framework.Positions list.

The FXB.Message object will contain a positionsChanged[] array listing the FXB.Position objects which have changed. You can react to the changes either by looking at the positionsChanged[] array, or by looking at the Framework.Positions collection which will already have been updated.