Renderers

Renderers provide a way to add visualizations for additional data series. In a standard securities chart, there is generally a line or candlestick that represents the price of the security over time. Frequently however we wish to plot additional points of data. The most common situation would be plotting the price for another security, as in a comparison chart. Or you might want to plot any sort of data: banking data, sentiment, etc.

Renderers get their data from "series". A series of data is added to the chart with the STXChart#addSeries method.

Currently there are two types of renderers available (in stxLibrary.js)

1) STX.Renderer.Lines 2) STX.Renderer.Histogram

New renderers can be derived from the STX.Renderer base class by following the pattern used in the existing renderers.

Renderers are permanent in much the same way that overlays are permanent. You only need to add a renderer to the chart once. The renderer will continue to exist between newChart() calls (between symbol changes, periodicity changes, etc). However, as the developer you are responsible for ensuring the existence of the series data. When using a STX.QuoteFeed this will be done automatically but if you are pushing data into the chart be aware that the renderer data will be cleared anytime the masterData is reset (when newChart() is called).

Most frequently a Renderer will not share the same y-axis scale as the underlying security. You can define a separate y-axis for the renderer.

Here is an example of series using a left axis:

Here is an example of multiple series, each one with its own right axis:

Lines

This renderer will draw a line for each series that is attached. This renderer is used by STX.Comparison, which draws comparison charts.

Histogram

This render will draw a histogram (aka "Bar Chart"). If multiple series are attached then it will be a stacked histogram.

Overlays vs. Renderers

An overlay is a study that is displayed on the chart. There is overlap between renderer and overlay functionality but generally you should use an overlay if:

1) The overlay data can be derived from price data 2) The overlay data shares the same y-axis scale as the underlying price data 3) You wish to leverage the studyLibrary, tools and UI for studies

Since renderers are designed specifically to use series data, they are most useful when you need to graphically represent multiple series.

Sample Code

Create a Stacked Histogram

function createRenderer(){
    var axis2=new STXChart.YAxis(); // Define a Y-axis for the renderer
    axis2.position="left";          // Position that axis on the left side of the chart

    // configure the histogram display
    var params={
        yAxis: axis2,
        name:               "My Data",
        type:               "histogram",
        subtype:            "stacked",
        heightPercentage:   .7,  // how high to go. 1 = 100%
        widthFactor:        .8   // to control space between bars. 1 = no space in between
    };

    //legend creation callback
    function histogramLegend(colors){/* your code to draw a legend*/}

    var histRenderer=stxx.setSeriesRenderer(new STX.Renderer.Histogram({params: params, callback: histogramLegend}));


    // add the histogram series, here we use the default QuoteFeed
    stxx.addSeries("EWZ", {display:"Brazil", data:{useDefaultQuoteFeed:true}});
    stxx.addSeries("EWJ", {display:"Japan", data:{useDefaultQuoteFeed:true}});

    histRenderer.removeAllSeries()
            .attachSeries("EWZ","#6B9CF7")
            .attachSeries("EWJ","#95B7F6")
            .ready();  //use ready() to immediately draw the histogram

    // Additional sample code:  

    // remove a single stack from the histogram
    // histRenderer.removeSeries("EWZ").ready();

    // remove all stacks from the histogram
    // histRenderer.removeAllSeries().ready();

    // remove the entire histogram renderer
    // stxx.removeSeriesRenderer(histRenderer);

}

Create a Line Renderer

function createRenderer(){

    var lineRenderer=stxx.setSeriesRenderer(new STX.Renderer.Lines({params: {name:"lines",  type:"line"}}));

    // add the comparison series.

    // Use "gaps" when you have series data that trades on different sessions. For instance a 24x7 forex symbol vs. a US equity

    // Use "permanent" to prevent the user from removing the series by right clicking

    stxx.addSeries("AAPL", {display:newSymbol,isComparison:true,data:{useDefaultQuoteFeed:true}, gaps:{pattern:[3,3]},width:4,permanent:true});
    stxx.addSeries("NOK", {display:"Nokia",isComparison:true,data:{useDefaultQuoteFeed:true}, gaps:{pattern:[3,3]},width:4});


    lineRenderer.removeAllSeries()
            .attachSeries("AAPL", "#FFEE00")
            .attachSeries("NOK", "#FFBE00")
            .ready();             
}

See STXChart#addSeries See STXChart#removeSeries See STXChart#setSeriesRenderer See STXChart#removeSeriesRenderer See STX.Renderer.Histogram See STX.Renderer.Lines See STX.Renderer See STX.Renderer#attachSeries See STX.Renderer#removeSeries See STX.Renderer#removeAllSeries See STX.Renderer#ready

Building Renderers

See STX.Renderer#performCalculations See STX.Renderer#draw