NavyJS API (Overlays)

Core functions and environments for building overlay / indicators.

Life Cycle

init()

Called when overlay is created. Should contain a code that runs once, for example adding event listeners:

init() {
    // Add event listener, which should use an unique component id
    $events.on(`rsi-${core.uuid}:some-event`, e => {
        console.log(e)
    })
}

destroy()

Called when overlay is destroyed. Should contain a code that runs once, for example removing event listeners:

destroy() {
    // Remove all event listeners of this overlay
    $events.off(`rsi-${core.uuid}`)
}

Drawing Functions

draw(ctx)

• Arguments:
  • ctx: Context Renderer context

Main drawing call handler. Provides a context of the overlay's renderer. This function will be called every time a chart data or view is updated.

TIP

This handler should be optimized if you want to get a great chart performance. Keep in mind, that in a real charting app it will be called at least 200-300 times per second. There are some tips how to make it faster:

• Use for (var i = 0; ...) loop instead of for (var x of ...) or arr.forEach(...) when iterating through big arrays.
• Limit number of ctx.beginPath() calls by combining several primitives into one path
• Draw primitives with the same color together. This tip alone increased performance of Candles overlay 2X.

// Example of drawing call
draw(ctx) {
    const layout = $core.layout // Grid layout
    ctx.fillStyle = $props.color
    ctx.fillRect(0, 0, layout.width, layout.height)
}

drawSidebar(ctx, side, scale)

• Arguments:
  • ctx: Context Sidebar canvas context
  • side: string left | right
  • scale: Scale Scale object of this sidebar

Drawing call of sidebar. The same as draw(), but ctx is a CanvasJS context of a sidebar.

// Example of value tracker drawing call
drawSidebar(ctx, side, scale) {
    for (var tracker of this.trackers || []) {
        sidebar.tracker(
            this.props, this.layout, scale, side, ctx, tracker
        )
    }
}

drawBotbar(ctx)

Drawing call of botbar. [Not implemented yet]

Samplers / transforms

yRange(?hi, ?lo)

• Arguments:
  • ?hi: number Pre-calculated max-value of the data view
  • ?lo: number Pre-calculated min-value of the data view
• Returns array Should return an array containing a new range: [<high>, <low>]. Optionally can disable the default range expansion: [<high>, <low>, false]

TIP

If you write this function without arguments, the library will skip the default min-max detection algo:

// Spends CPU:
yRange(hi, lo) => [1, 0]
// Doesn't:
yRange() => [1, 0]

Redefines y-range of overlay. See this for more info.

preSampler(x)

• Arguments:
  • x: object A data point form the overlay's data.
• Returns array Array of numbers for sampling.

Defines a sampler for the precision detection algo. See more information here

// Code from Candles.navy
preSampler(x) => [x[1], x[4]]

ohlc(x)

• Arguments:
  • x: object A data point form the overlay's data.
• Returns array Array of OHLC values.

Mapping data point to OHLC value for candle magnets. For example, if you have Spline overlay which doesn't have all 4 values, you can emulate them:

// Code from Spline.navy
ohlc(x) => Array(4).fill(x[$props.dataIndex])

If you defined ohlc() function for your main overlay, you can use this values in other overlays:

// Code from ArrowTrades.navy
for (var i = view.i1, n = view.i2; i <= n; i++) {
    let p = data[i]
    let ohlc = layout.ohlc(p[0]) // Getting OHLC from the data-point
    if (!ohlc) continue
    var y = layout.value2y(ohlc[1]) // High
    // ...
}

UI functions

legend(x, prec)

• Arguments:
  • x: object Data point selected by cursor, e.g. [<timestamp>, <x1>, <x2>]
  • prec: number Pre-calculated data precision
• Returns array Array of [value, color] pairs.

Defines legend as [value, color] pairs. More Info. To hide the legend line return null.

legendHtml(x, prec, formatter)

• Arguments:
  • x: object Data point selected by cursor, e.g. [<timestamp>, <x1>, <x2>]
  • prec: number Pre-calculated data precision
  • formatter: function Default number formatter
• Returns string HMTL code

Defines legend as a custom HTML. More Info.

valueTracker(x)

• Arguments:
  • x: object The last data point
• Returns object Descriptor

Sets price label + price line parameters.

// Code from Candles.navy
valueTracker(x) => {
    show: $props.showValueTracker, // Show the tracker, boolean
    symbol: $props.scaleSymbol, // Symbol label [Not implemented]
    line: $props.priceLine, // Show price line, boolean
    color: $lib.candleColor($props, $core.data[$core.data.length - 1]),
    value: x[4] // Tracker value (candle close)
}

Mouse listeners

mousemove(event)

• Arguments:
  • event: Event Mouse Event

Called when 'mousemove' event is triggered on the grid.

mousemove(event) {
    console.log(event)
}

mouseout(event)

• Arguments:
  • event: Event Mouse Event

Called when 'mouseout' event is triggered on the grid.

mouseup(event)

• Arguments:
  • event: Event Mouse Event

Called when 'mouseup' event is triggered on the grid.

mousedown(event)

• Arguments:
  • event: Event Mouse Event

Called when 'mousedown' event is triggered on the grid.

click(event)

• Arguments:
  • event: Event Mouse Event

Called when 'click' event is triggered on the grid.

Keyboard listeners

keyup(event)

• Arguments:
  • event: Event Keyboard Event

Called when 'keyup' event is triggered on the grid.

keydown(event)

• Arguments:
  • event: Event Keyboard Event

Called when 'keydown' event is triggered on the grid.

keypress(event)

• Arguments:
  • event: Event Keyboard Event

Called when 'keypress' event is triggered on the grid.

Overlay Environment

$core

Collection of all core elements and other variables.

// Code from Band.navy
draw() {
    // ...
    const data = $core.data
    const view = $core.view
    const layout = $core.layout
    // ...
}

$core.layout Layout - Grid Layout

$core.dataSubset array - Visible data subset

$core.data array - All overlay data

$core.view object - Current data view

$core.id number - Overlay sequential id

$core.paneId number - Pane sequential id

$core.uuid string - Overlay unique id

$core.range array - Overlay unique id

$core.colors object - Chart colors, Defaults

$core.cursor object - Chart Cursor

$core.src object - Overlay Object

$core.props object - General Chart Props

$core.indexOffset number - Index Offset of overlay (in index-based mode)

$props

• Type: object

Overlay props (props field of OverlayObject). Read More

$events

• Type: object

Events component.

$lib

Collection of primitives & helper functions.

$lib.Candle - Draws candle src

$lib.Volbar - Draws volume bar src

$lib.layoutCnv - Calculates candle & volume layout src

$lib.formatCash - Formats number in the following format, e.g.: 1.2M src

$lib.candleBody - Draws candle body fast src

$lib.candleWick - Draws candle wick fast src

$lib.volumeBar - Draws volume bar fast src

$lib.fastSma - Calculates SMA fast scr

$lib.avgVolume - Draws average volume fast src

$lib.candleColor - Detects candle color src

NavyJS API (Indicators)

Indicator Std Functions

See Script Engine Std Library

Indicator Environment

Variables available in all sections of a script.

self

Script Environment of the script: src.

ohlcv

Main OHLCV dataset.

shared

Shared data. You can use it to communicate between scripts:

// First script
[INDICATOR name=Ind1]
[UPDATE]
shared.ts = ema(close, 200)

// Second script
[INDICATOR name=Ind2]
[UPDATE]
Spline(shared.ts)

To make sure that script are executed in the right order, set an incremental execOrder.

settings

Script settings.

tf

Time-frame of the main dataset. Calculated by DataScan, or provided by user.

range

Current chart range. The same as this.

se

Script Engine reference. src

Variables available in the [UPDATE] section of a script.

iter

Current value of OHLCV data iterator. Starting from 0, ending at ohlcv.length - 1.

t

Current value of OHLCV data timestamp. Value equals to ohclv[iter][0].