Customization Basics

Introduction

Colors and other layout properties are defined in the style sheets. Feel free to make any changes you need to achieve the look and feel you are looking for.

stx-chart.css -- Contains the code CSS that is required for the charts to operate. When integrating as part of a workstation you will probably only need this CSS file.

stx-standard.css -- The default css that accompanies stx-standard.html. This includes all of the CSS required for the UI widgetry. These elements may be customized to meet your needs. Light and Dark themes are included in this css file.

stx-advanced.css -- Contains CSS to support the advanced functionality beyond what is implemented by the standard UI and functionality . Additional Light and Dark theme elements for advanced components are included in this css file.

Styles can also be overwritten programatically at any time using the STXChart#setStyle convenience function:

Example: stx.setStyle("stx_volume_up","color","green"); stx.setStyle("stx_volume_down","color","red");

Dark and Light color schemes are controlled by the CSS.

Depending on your package, you will find the scheme color overrides in stx-standard.css or stx-advanced.css. The advanced css file will contain all of the elements used by the advanced template, which are not already in the standard template. So if the element is present in both standard and advanced, it will be defined in the standard css file 0nly, but if the functionality is only available in advanced, it will be present only in the advanced css file.

Look for the .Dark or .Light prefixes. The library looks for these to use as the scheme color override.

Feel free to add or change any component you want to override for your particular color scheme.

For example, to have a different color on the drop down menus for the dark theme, you would add:

.Dark .menuOutline {
 background: blue;
}

This is an example of a definition for a 'Light' theme.

.Light .stx-footer {
 background:#fdfdfd;
 color:#929292;
 border-color:#ddd;
}

Visual Reference ( candle elements on dark scheme):
colorSchemes

See the following tutorial if you wish to also create custom color themes: Custom Color Themes

On Studies, the StudyLibrary is used to initialize all rendering. Here is where you would override colors or even the entire rendering function. The STX.Studies#studyLibrary can be found in stxLibrary.js (stx.js if version 04-2015 or prior).

The output section defines the colors and other artifacts for the rendering of the study.

The Custom Studies tutorial has more detail on how to define and work with studies.

Here are some examples:

                "W MFI": {
                    "seriesFN": function(stx, sd, quotes){ return STX.Studies.displayMFI(stx, sd, quotes); },        // change rendering function here
                    "calculateFN": function(stx, sd){ return STX.Studies.calculateMFI(stx, sd); },
                    "inputs": {},
                    "outputs": {"Green":"#8bc176", "Fade":"#ab611f", "Fake":"#5f7cb8", "Squat":"#ffd0cf"}            // change colors here
                },
                "ATR Bands": {
                    "overlay": true,
                    "seriesFN": function(stx, sd, quotes){ return STX.Studies.displayChannel(stx, sd, quotes); },    // change rendering function here
                    "calculateFN": function(stx, sd){ return STX.Studies.calculateATRBands(stx, sd); },
                    "inputs": {"Period":5, "Shift": 3, "Field":"field", "Channel Fill":true},
                    "outputs": {"ATR Bands Top":"auto", "ATR Bands Bottom":"auto", "ATR Bands Channel":"auto"}        // change colors here
                }

Branding your chart with a watermark can be done using STXSocial.brandMyChart function. STXSocial.brandMyChart(stxx, "yourlogo.png", [10, -10]); This method should only be called once after you create your STXChart (stx) object. See STXSocial.brandMyChart for more details.

You may also want to add a watermark for the active symbol. There are different ways to do this;

1- You can create a CSS styled div in your chartContainer to overlay semi-transparent text on the chart. Then you would have the newChart callback function change the innerHTML content with the new symbol name as it changes and a new chart is rendered. This is straight forward and simple to implement. The disadvantage is that if you export the chart, since this is just an HTML element, it will not be part of the picture.

2- We do have a watermark function, you can use that as well:

see STXChart#watermark

The watermark will have to be redrawn on every frame of the animation loop, or it will disappear. You can do this with an API injection:

Example:

STXChart.prototype.prepend("draw",function(){ 

        // set the color and font
        stxx.setStyle("stx_watermark","font-size","100px");
        stxx.setStyle("stx_watermark","color","red");

       stxx.watermark("chart",{h:"center",v:"middle",text:stxx.chart.symbol}); 

       // restore the color and font
        stxx.setStyle("stx_watermark","font-size","16px");
        stxx.setStyle("stx_watermark","color","rgba(0,0,0,0.5)");
});

The advantage of the watermark over the div is that it is written on the canvas, so if you were exporting the chart, your watermark will be part of the 'picture'. The disadvantage is that it needs to be redrawn on every frame.

Remember that the CSS style (style stx_watermark) is the same to all watermarks; so be careful since we use this all over for error messages. Mainly on study panels

All menu components will be part of your main HTML page (stx-advacned.html, for example). There you can add, remove or redesign menus and buttons sounding or overlapping the charting object. There are several sample layouts (html) included in your package, which you can use to get started.

If you are looking to change default behavior of the chart, rather than look and feel, you can find all configurable settings for the main chart object and associated x and y axis rendering in the following classes:

Feel free to override them as needed to permanently change the defaults, programmatically change on the fly within your code, or send them in as arguments when constructing a new chart for a more dynamic approach.

When sending in a 'config' argument, any field or object within the config will be added to the STXChart object itself or override defaults.

If you wanted to create a new candle chart with corsshairs enabled on initial load, you can do something like this:

var stxx=new STXChart({container:$$("chartContainerSilver"), layout:{crosshair:true, chartType:"candle"}});

This overrides stxx.layout.crosshair with a value of true and stxx.layout.chartType with a value of "candle".

Or if you wanted to change the shape of the y axis price labels, you can choose from the following: "roundRectArrow", "semiRoundRect", "roundRect","tickedRect","rect","noop" as follows:

var stxx=new STXChart({container:$$$(".chartContainer"), yaxisLabelStyle:"rect", layout:{"candleWidth": 16, "crosshair":true}});

Or you can use the following syntax if you want to change it dynamically after the chart object has been created:

var stxx=new STXChart({container: $$("chartContainer")});
// do other things here...
stxx.yaxisLabelStyle="roundRectArrow";

For additional axis manipulations see Custom X-axis and Gridlines and axis labels.

Establish behavior of the UI

The main HTML file in your package (stx-advanced.html, stx-basic.html, etc) will contain a function used to initialize the default behavior of the UI (runSampleUI()). Amongst other things, you will find the initialization logic for the following:

  • Default color schemes (and ability to set the default choice - dark or light)
  • Symbol lookup initialization ( see Symbol Lookup widget for details)
  • Storage management initialization for:
    1. User defined color schemes
    2. User defined watch lists
    3. User defied views

Feel free to modify the components in this function to establish the behavior of your UI.

Popular UI customizations

Disabling Zooming and Panning

Right after your new STXChart() declaration put the following line:

stxx.manageTouchAndMouse = false;

All mouse and touch gestures will be disabled for this chart container.

You can re-enable response by setting stxx.manageTouchAndMouse to true at any time and reinitializing the chart:

Example:

stxx.manageTouchAndMouse = true;
stxx.initializeChart();
stxx.draw();

Note: once the events are enabled, they can't be disabled again. If you wish to alternate settings continuously, then you will need to use an API injection. See 'Disabling/enabling touch and mouse events' in the Popular API injections tutorial.

You may also want to remove the zoom-in and zoom-out buttons by modifying the CSS as follows:

In stx-chart.css add display: none; to the following style:

#chartSize { /* Chart size container */
    display: none;
}

Alternatively, you can also disable and re-enable the zoom controls dynamically by using the following code; preferably in the newChart() callback function:

     if(stxx.controls.chartControls /* && put your condition for enabling/disabling here*/){
        stxx.controls.chartControls.style.display="block";        // use this line to enable the controls
        stxx.controls.chartControls.style.display="none";        // use this line to disable the controls
    }

If all you want to do is to remove the touch and mouse zooming and panning but allow the zoom buttons to work, use the API injections outlined in the 'Disabling/enabling touch and mouse events' on the Popular API injections tutorial.

Tip: You may override controls like "zoom", "home" and "more" if you wish to provide your own navigational components. Place your own divs with the same id tags into the chart div container. The chart will use those instead of making its own. Or, simply modify the css to change the look of the existing components. Finally, to hide any of these objects, set the corresponding entry to null in the stx object before creating a chart. The complete list of these objects is outlined in STXChart.htmlControls.

Decimal place precision

The default is to set display precision to the maximum that is found in the data set. This can be overridden however by setting stxx.chart.panel.yAxis.decimalPlaces=<your value>. Note that by default, the current price label will continue to display the higher level of precision. To limit the price label set stxx.chart.label.yAxis.maxDecimalPlaces=<your value>.

Overriding default y-axis rendering

The y-axis rendering can take in a function to override the default formatting. This function will be called before rendering each tag on the y-axis.

For example, you may want to display prices in fractions instead of decimals. You would set it up as flows in the newChart callback:

stxx.chart.panel.yAxis.priceFormatter=function(stx, pannel, price){
    var convertedPrice;
    // add our logic here to convert 'price' to 'convertedPrice'
      return convertedPrice; 
}

to remove it you would do this:

stxx.chart.panel.yAxis.priceFormatter=null;

Advanced customization -- API injections

Every module can be overwritten with an API injection if necessary (append/prepend). We can assist you in creating the necessary code injections if you find there are things you want to change beyond what is made available trough the configurable settings.

The charting engine is essentially an animation engine. When a user scrolls or pans a chart, it is redrawn at animation speeds, providing the appearance of a smoothly moving chart in much the same way that a video game does. STXChart#draw is the rendering function that is called to animate the chart and therefore the most common method for extending chart functionality is to extend the draw() function itself. This can be done easily with the Injection API (see below for more details on the Injection API).

There are two ways to visually extend the draw() function:

  1. By drawing on the canvas
  2. By displaying HTML components

For instance, as a developer you may wish to display an arrow somewhere on the screen. This could be accomplished either by physically drawing an arrow using the canvas, or by creating an HTML arrow object and superimposing it on the canvas. The choice of which technique to use depends on your "use case". Drawing on the canvas takes more programming effort, but if you are sharing charts then you must use this approach because HTML elements will not render on a shared chart image. However, complex interactive graphics are easier to create as plain HTML and so might be the better approach for complex interfaces. For example, Trade From Chart is primarily implemented using HTML elements that are superimposed on the chart.

Your first step to customization is to append your own code to the end of the draw() function. You can do this with the following statement:

STXChart.prototype.append("draw", function(){

  // my custom code here

});

This code will now get called whenever the chart is redrawn (possibly hundreds of times per second if the user is scrolling the chart).

You can do anything you want in this code, such as custom drawing. Logically, placing customized drawings or objects on the chart requires finding the appropriate positioning along the x and y axis in pixels. The charting engine however provides functions that allow you to determine the physical X and Y coordinates given dates and prices using functions such as STXChart#pixelFromPrice and STXChart#pixelFromDate.

The charting display is subdivided into panels. Each study is drawn in a panel. The chart itself is also a panel. Each panel has its own y-axis. The stx.panels object contains all of the panels on the chart. Drawing on the chart panel is the simplest and most common task. You can get the chart panel easily:

STXChart.prototype.append("draw", function(){
  var panel=this.chart.panel; // "this" is your stxx object
});

Once you have access to a panel you can determine the X and Y coordinates on the canvas given a price and date (or dateTime:

STXChart.prototype.append("draw", function(){
  var panel=this.chart.panel;
  var dt=yyyymmddhhss(myDate);
  var x=this.pixelFromDate(dt, panel.chart);
  var y=this.pixelFromPrice(myPrice, panel);
});

Note that pixelFromPrice() can take a value rather than a price if you are dealing with a study panel (for instance a stochastics panel would require a value between 1 and 100)

Now you might want to draw using HTML5 canvas commands:

STXChart.prototype.append("draw", function(){

  var panel=this.chart.panel;
  var dt=yyyymmddhhss(myDate);
  var x=this.pixelFromDate(dt, panel.chart);
  var y=this.pixelFromPrice(myPrice, panel);

  this.chart.context.fillRect(x,y,x+10,y+10);

});

Placement of HTML objects depends on how they are created. If objects are added to the chart container then positioning is quite simple:

// in your html page

var myHTMLObject=document.createElement("DIV");
myHTMLObject.style.position="absolute";
stxx.chart.container.appendChild(myHTMLObject);

STXChart.prototype.append("draw", function(){

  var panel=this.chart.panel;
  var dt=yyyymmddhhss(myDate);
  var x=this.pixelFromDate(dt, panel.chart);
  var y=this.pixelFromPrice(myPrice, panel);

  myHTMLObject.style.left=x+"px";
  myHTMLObject.style.top=y+"px";

});

If objects are absolutely positioned at the document level you can use STXChart#resolveX and STXChart#resolveY to convert to absolute screen coordinates

// in your html page

var myHTMLObject=document.createElement("DIV");

myHTMLObject.style.position="absolute";
document.body.appendChild(myHTMLObject);

STXChart.prototype.append("draw", function(){

  var panel=this.chart.panel;
  var dt=yyyymmddhhss(myDate);
  var x=this.pixelFromDate(dt, panel.chart);
  var y=this.pixelFromPrice(myPrice, panel);

  myHTMLObject.style.left=this.resolveX(x)+"px";
  myHTMLObject.style.top=this.resolveY(y)+"px";

});

Management of HTML objects is up to you as the developer so you'll need to build logic into your draw() extension to determine when to display or not display the objects.

You can use panel.top, panel.bottom, chart.left and chart.right to determine the boundaries of a panel.

It is also possible to work with "bars". A bar is a candle location on the screen. The number of ticks displayed on the screen is chart.maxTicks.

For instance if you wanted to draw a line between bars 5 and 10 on the screen:

STXChart.prototype.append("draw", function(){

  var panel=this.chart.panel;
  var x0=this.pixelFromBar(5);
  var x1=this.pixelFromBar(10);

// draw line between x0 and x1

});

Note: If using transformations (such comparison charts that transform a price to a percentage) then pixelFromPriceTransform() will return a Y value based on the transformation. For instance, to get the Y location of a closing price in a comparison chart you would use pixelFromPriceTransform(someBar.Close). Whereas if you wanted to get the pixel for the Y axis location of 10% you would use pixelFromPrice(10). If no transformation is in effect then the two functions are equivalent.

Where do I put my injection code?

It is recommended to put the API injections on the main HTML file you have customized to render the chart. In this way, when a new release is available, you won't have to worry about merging you customized code into the core library files. Anywhere within the tags will work.

Here is an example of what your code may look like:

<!doctype html>
<html>
<head>
</head>
<body onLoad="displayChart()">
<script>

// API injection 
STXChart.prototype.prepend("someFunction", function(){
    // injection code here;
});

// Declare a STXChart object. This is the main object for drawing charts
var stxx=new STXChart({container:$$("chartContainer"), layout:{"candleWidth": 16, "crosshair":true}});

// more js here

</script>
</body>
</html>

Can I disable the inetia scroll effect?

By default, the chart will use a rolling effect to continue to scroll the cart as you swipe it; depending on your gesture velocity. The faster you swipe the more it will continue to 'roll' and decrementally slow down until it comes to a full stop. If you want to disable this rolling effect, add the following code to your override file:

    STXChart.prototype.autoscroll=function(){};
    stxx.originalHome=STX.clone(STXChart.prototype.home);
    STXChart.prototype.home=function(params){
        if( params ) params.animate=false;
        stxx.originalHome(params);
    };