1.1Example UDI code

There are several example UDI files. You can download them from the following URL:

https://www.fxblue.com/figaro/udi/udi-examples.zip

It's possible to learn how to write UDIs just from these example files, without reading this document. The number at the start of each file, e.g. 01-udi-basic-sma.js, is the suggested order for working through the examples.

1.2Adding a UDI to a chart

You add a UDI to a chart - including any of the examples - by clicking on the indicators button in the chart toolbar, choosing Advanced / UDI, and then pasting in the Javascript code.

You can also store your UDI on a web server, and then paste in the URL of the file rather than its contents. Note: your server must be CORS-friendly; your server must set the CORS headers Access-Control-Allow-Origin and Access-Control-Allow-Credentials on its response so that the chart is allowed to make the cross-origin HTTP request.

If you want to share your UDI with other people while protecting how it does its calculation, you can use a code obfuscation service. Examples include javascript-obfuscator (free) and JScrambler (paid).

1.3Lifecycle

The UDI is initialised once, when it is loaded. The UDI.onInit() function is not then called again if there is a change to the chart, such as a switch to a different market or timeframe, nor is it called if there is a change to the user-defined parameters. (This behaviour is different to other platforms such as MT4 and MT5.)

If your UDI needs to react to changes in the choice of market or timeframe (beyond just recalculating all its data, which will happen anyway) then you can watch for these changes by implementing the optional functions UDI.onContextChange() and UDI.onParameterChange()

1.4Alerts

Your UDI automatically participates in the chart's alerting system. The user can set alerts on any of your indicator's plots, unless you set the noAlerts property.

1.5Indicator-on-indicator

Your UDI automatically participates in the chart's ability to apply one indicator to another indicator (unless you turn this off using the noIOI setting).

Another indicator - for example, a moving average - can be applied to any of the plots of your indicator. And, if your indicator has a Source field, then it can receive the values of another indicator rather than candle data such as close prices.

1.6Technical note: web workers

A UDI runs as a web worker, in its own browser thread. It does not have access to the HTML of the chart or the browser DOM. You interact with the chart using the API described in this document and in the example code.

Because it's a web worker, your UDI can use Javascript's importScripts() to include external code libraries.

1.7Technical note: dates

All dates which you need to pass to the chart, such as co-ordinates for creating a drawing or an event marker, should be transmitted as a number of milliseconds (since 1/1/1970, rather than a textual date).

The dates used on the chart depend on the time zone, which is user-configurable. If you need to convert from an external source of dates, e.g. an economic calendar which uses GMT, then you can use the helper functions described below.

2Initialisation: UDI.onInit()

A UDI must have a UDI.onInit() function. This returns a description of your indicator: its name; what it draws (line, histogram etc); and any user-configurable fields it wants such as a number of bars, or a colour.

An example of the UDI.onInit() function is as follows. It returns an object which must contain a name property, a plots[] array, and a settingsFields[] array. There are also other optional properties which can be included.

UDI.onInit = function(data)

{

return {

// Display-name for the indicator

caption: "My SMA",

// Specifies that it should be in the main panel, not its own sub-panel

isOverlay: true,

// List of things which the indicator draws: just a line in this basic example

plots: [

{type: "line", caption: "avg", color: "blue", lineWidth: 2}

],

// Settings fields which the indicator wants.

settingsFields: [

// The "Source" field has special meaning, and the chart automatically

// assigns a caption to this field

{id: "Source"},

// Also require a number of bars for the average

{id: "period", caption: "Period", type: "int", defaultValue: 14, min: 2}

]

};

};

2.1Return value from UDI.onInit()

The return value from UDI.onInit() should be an object, as in the example above, with the following members:

2.2The plots[] array

The plots[] array in the object you return from UDI.onInit() describes the different types of values which your UDI draws: a line, a histogram etc.

Your UDI can draw any number of different plots. For example, to draw something like the standard Bollinger Band indicator, you would use 4 plots: a channel (for the filled high-low range) plus 3 line plots for the centre line, the upper line, and the lower line.

Each plot in the array must have a caption, and a type. The type of plot determines how many values you need to pass back from UDI.onCalculate(). If you are drawing a channel plus a line, then you will need to pass back 3 arrays of values in UDI.onCalculate(): 2 for the channel plus 1 for the line.

The full details of each plot are as follows. The only compulsory properties which you must provide are caption and type. All the other properties have defaults. Some members of the plot definition only apply to particular types of plot.

2.3The settingsFields[] array

The settingsFields[] array in the object you return from UDI.onInit() describes the configurable fields which people should be able to modify for your indicator.

There is one special field which fundamentally affects the type and behaviour of your UDI. If your indicator has a Source field then it receives, in UDI.onCalculate(), a single data series such as the close prices or the high prices - or the values from another indicator. If your indicator does not have a Source field then it receives the full data for each bar - open, high, low, close, and volume - and your UDI cannot be applied to another indicator.

The Source field is defined in the settingsFields[] array as follows. (It is normal, but not compulsory, for it to be the first field.)

settingsFields: [

{id: "Source"}

…

]

All other fields in the settingsFields[] array should have an id, a caption, and a type. They can also optionally have other properties depending on the type of field. For example:

settingsFields: [

{id: "Source"},

{id: "threshold", caption: "Threshold", type: "float", defaultValue: 1, min: 1, step: 0.1},

{id: "highlightcolor", caption: "Color", type: "color", defaultValue: "rgba(0,0,255,0.5)"},

{id: "options", caption: "Display type", type: "select", options: [

{k: "line", v: "Display as line"},

{k: "marker", v: "Display as histogram"}

]}

]

The types of field which you can use are as follows:

The full set of properties which can be defined for each field is as follows:

2.4Context data passed to UDI.onInit()

The UDI.onInit() function receives one parameter, data, which contains a single member, context, describing the current settings for the chart as a whole.

The same context data is also passed to all other UDI functions, including UDI.onCalculate().

The properties in data.context are as follows:

3Calculating data: UDI.onCalculate()

Your UDI must have a UDI.onCalculate() function. This is called whenever there is new data and, therefore, your indicator needs (or may need) to update its output values.

A simple example of the UDI.onCalculate() function is as follows:

UDI.onCalculate = function(data, output)

{

// Get the user-selected value of the "period" parameter

var period = data.parameters["period"];

// The data to be worked on is in the array data.valueData.

// We then put our output - the average - in output.values, which

// is an array of arrays, with entries depending on the number of plots

for (var i = period - 1; i < data.valueCount; i++) {

var sum = 0;

for (var j = 0; j < period; j++) sum += data.valueData[i - j];

output.values[0][i] = sum / period;

}

};

The UDI.onCalculate() function receives two parameters: data and output. The data tells the UDI about the chart's data values, and also about things such as the current value of the UDI's settings. The UDI then does its calculations and puts the results into output.

There are two types of UDI:

If your UDI has a Source field, then it receives a single series of input values, such as close prices or high prices, in data.valueData

If your UDI does not have a Source field, then it receives the full bar data for the chart, in data.barData

3.1Reading settings fields

Your UDI can have settings fields, such as the number of bars for a moving average, and the current value of each of these settings is then available in the data.parameters which are passed to UDI.onCalculate().

Within data.parameters there will be a property for each settings field, using the id you defined in the settingsFields[] array, and the value of the property is the field's current value.

For example:

settingsFields: [

// Number of bars for the average

{id: "period", caption: "Period", type: "int", defaultValue: 14, min: 2}

]

…

UDI.onCalculate = function(data, output)

{

// Get the user-selected value of the "period" parameter

var period = data.parameters["period"];

…

}

3.2Input data for the UDI

As explained above, your UDI receives either a single array of input values, in data.valueData, or the complete bar data for the chart, in data.barData, depending on whether the UDI has a Source field.

The data.valueData is a single array of input values, such as close prices or the values from another indicator.

The data.barData contains sub-arrays for date, open, high, low, close, and volume: data.barData.date, data.barData.open, data.barData.high etc

The data.valueCount property defines the number of input data points. It will be same as the length of the data.valueData array, or of each array inside data.barData.

The input data (and also your output data) is indexed with the oldest item in [0], and the latest, current value in [length-1]. (If you are used to the MT4 or MT5 platforms, this is the opposite way round to what you may be familiar with.)

3.3Updates of the current bar only

To make calculations faster and more efficient, the chart tells your UDI whether only the current bar has changed since the last calculation, using the data.currentBarUpdateOnly property.

Typically, if data.currentBarUpdateOnly is set, then you only need to re-calculate the final, most recent item in your output. If it is not set, then you need to re-calculate the whole series of output values from your indicator, because any part of the historic data may have changed.

The example code contains two versions of an SMA indicator: one which always re-calculates all values, and a more efficient one which uses data.currentBarUpdateOnly to update only the current average value if only the current bar is changing.

3.4Calculating output data

You put the results of your UDI's calculations into the output object which is passed to your UDI.onCalculate().

The output has a values member which is an array of arrays. The length, and order, of output.values depends on the plots defined for your indicator. For example:

plots: [

{type: "channel", …}, // Requires 2 output series

{type: "line", …}, // Requires 1 output series

{type: "candles", …} // Requires 4 output series

]

In this example, output.values will contain 7 sub-arrays. Items [0] and [1] will be for the channel plot; item [2] will be for the line plot; and items [3] to [6] will be for the candle plot.

Each sub-array inside output.values will already have been initialised so that it contains the required number of elements (matching the number of bars on the chart). In other words, the length of each sub-array, such as output.values[0].length, will be the same as data.valueCount. You assign values into the sub-arrays rather than using push() to add data.

If UDI.onCalculate() is being called for an update of the current bar only, with data.currentBarUpdateOnly set, then the contents of output.values will be the last results you passed back. Typically, you only then need to re-calculate the final value in each sub-array.

If the update is not just for the current bar only, then the contents of each sub-array in output.values will have been initialised with null values.

3.5Requesting out-of-band updates

There are circumstances where your indicator may need to re-plot its values without a new market price. For example, you may request external data, and then need to update your indicator's output when that data is received.

You can use the function UDI.requestUpdate() to force an immediate recalculation of your indicator. This will generate an asynchronous but immediate call to UDI.onCalculate().

3.6Calculating moving averages

Many indicators involve calculating moving averages in order to prepare the indicator's final values. For example, a MACD indicator is based around the calculation of two moving averages, for its "fast" and "slow" periods.

The chart provides a helper function, UDI.movingAverage(), which you can use instead of calculating moving averages yourself. The example code includes Hull and MACD indicators which demonstrate how to use this function.

The UDI.movingAverage() function takes three parameters:

The output you get back is an array with the same number of elements as the inputData array. For example, if you pass in an array of 1000 items, and 20 as the number of bars, then a Simple Moving Average will return an array which also has 1000 items, and where the first 19 values in the output array are null (because averages can only be calculated from the 20^th value onwards).

The available types of moving average, for the maType parameter, are as follows:

If you want to make the type of average user-configurable, rather than hard-coded into your UDI, then you can include in your settingsFields[] an entry with its type set to maType. For example:

settingsFields: [

…

{id: "ma", caption: "Moving Average Type", type: "maType"}

]

…

UDI.onCalculate = function(data, output)

{

// 20-bar average of chosen type

var arrAvg = UDI.movingAverage(data.parameters["ma"], 20, data.valueData);

…

}

4Changes to the chart or parameters

If there is a change to the chart, such as a switch of timeframe, or a change in your user-defined settings, then the chart will always make your UDI recalculate all its data by issuing a call to UDI.onCalculate().

However, if you need to take special, extra action when these values/settings change, then you can implement the optional functions UDI.onContextChange() and UDI.onParameterChange()

4.1UDI.onContextChange()

UDI.onContextChange() is called whenever there is a change to the chart such as a switch of market or timeframe. The function receives a data parameter which contains the same context information which is passed to UDI.onInit().

For example:

UDI.onContextChange = function(data)

{

// Get current chart timeframe

var tf = data.context.instrument.timeframe;

};

4.2UDI.onParameterChange()

UDI.onParameterChange() is called whenever there is a change to the user-defined settings for your UDI. The function receives a data parameter which contains the new settings, as a parameters object. It also receives the same context information which is passed to UDI.onInit(), in data.context.

For example:

settingsFields: [

// Number of bars for the average

{id: "period", caption: "Period", type: "int", defaultValue: 14, min: 2}

]

…

UDI.onParameterChange = function(data)

{

// Get the latest user-selected value of the "period" parameter

var period = data.parameters["period"];

…

}

5Creating drawings, event markers, and bar highlights

In addition to plotting values, using the plots[] array and UDI.onCalculate(), your UDI can also create objects on the chart:

Drawings, such as rectangles, lines, bar markers, trend channels etc

Event markers. These are markers against a specific date/time, displayed at the bottom of the chart, and automatically stacked if there are multiple markers to be displayed against the same bar.

Bar highlights. These change the colour of a specific bar on the chart in order to highlight it.

Note: you cannot create these objects from UDI.onInit(). If you want to create objects on start-up, do so from the first call to UDI.onCalculate() which is always issued immediately after an indicator is loaded.

For examples of the event markers and bar highlights, see the built-in Inside Bars or Outside Bars indicators.

When you create one of these objects, it stays on the chart (until your UDI is removed). You do not need to re-create the object in each call to UDI.onCalculate().

Objects are not removed if the user changes the market or timeframe of a chart. You will often want to remove and re-create objects after this sort of change, which you can detect using UDI.onContextChange().

Objects can be created from any function in your UDI, not just in response to UDI.onCalculate(). For example, you can use XMLHttpRequest to get external data, and then display that data on the chart as drawings:

UDI.onInit = function(data)

{

// Make a data request

var xmlr = new XMLHttpRequest();

xmlr.addEventListener("load", onMyDataLoad);

xmlr.open("GET", "http://www.example.org/mydata");

xmlr.send();

// Return indicator definition

return { … };

}

function onMyDataLoad()

{

// Parse this.responseText and create objects…

UDI.createDrawing(…);

}

Your UDI cannot see or manipulate objects which do not belong to it. You cannot modify or remove drawings, event markers, or bar highlights which were created by the user or by another indicator.

5.1Creating drawings

You create drawings using UDI.createDrawing(). The parameter for this function is either a single drawing definition, or an array of definitions. For example:

UDI.createDrawing([

{type: "horizontalLine", points: [{value: 1.2345}], style: {line: {color: "red"}}},

{type: "horizontalLine", points: [{value: 1.3456}], style: {line: {color: "blue"}}}

]);

By default, the user can select a drawing and change its properties, but the user cannot move or delete the drawing. You can change this behaviour using the drawing's properties.

You can remove all your drawings from the chart using UDI.removeAllDrawings().

You can also remove individual drawings, or you can reposition a drawing without deleting and recreating it. In order to do this, you need to get the ID of the drawing. These are provided via an optional asynchronous callback function which you can pass to UDI.createDrawing(). For example:

UDI.createDrawing([

{type: "horizontalLine", points: [{value: 1.2345}], style: {line: {color: "red"}}},

{type: "horizontalLine", points: [{value: 1.3456}], style: {line: {color: "blue"}}}

], function (response) {

// The ID of each drawing will be contained in the array response.drawingId[]

UDI.myLine1 = response.drawingId[0];

UDI.myLine2 = response.drawingId[1];

});

Once you have the ID of a drawing, you can delete it by passing the ID to UDI.removeDrawing().

A drawing can be moved by passing an object containing the ID and a new array of points to UDI.moveDrawing(). For example:

UDI.moveDrawing({

drawingId: …,

points[{date: data.barData.date[0]}, value: data.barData.high[0]}]

});

The properties of a drawing - text, colour etc - can be changed using UDI.changeDrawing(). You pass an object containing the ID and any properties you want to change. For example:

// Change drawing text and its colour

UDI.changeDrawing({

drawingId: …,

text: "New text",

style: {text: {color: "red"}}

});

UDI.removeDrawing(), UDI.moveDrawing(), and UDI.changeDrawing() can be given an array as their parameter, rather than a single item.