Customizing the X axis

Using a variety of different tools and configurations, you can fully customize the rendering for the X-axis.

First, review the complete list of available parameters to see if you can accomplish your desired customization by adjusting a particular setting. A complete list can be found at CIQ.ChartEngine.XAxis

Colors and fonts

These can be controlled by manipulating the CSS.

You can override the stx_xaxis class in stx-chart.css to change the font. If you also want to control the color, you will need to override the defaults for .Light .stx_xaxis and .Dark .stx_xaxis styles found in stx-standard.css

Fully customized X-Axis

Option 1:

Set CIQ.ChartEngine.XAxis#formatter to a function which override the label text on the x-axis and set it to anything you want for each label with your own logic.

Option 2:

Use an API injection for createXAxis() to totally override all of the default functionality. This is an advanced feature and only recommended for someone very experienced with the library.

CIQ.ChartEngine.prototype.prepend("createXAxis",function(chart){ 
    // add your logic to create your own X-Axis. We can help...
     //return axisRepresentation; // This is your array of CIQ.ChartEngine.XAxisLabel() elements used by CIQ.ChartEngine.drawXAxis()
});

See CIQ.ChartEngine.AdvancedInjectable#createXAxis for function signature and other details.

In the injection, you can build the xaxisRepresentation array that createXAxis() normally creates and drawXAxis() uses to draw the axis. Your injection can put anything you want to see in the X Axis labels (text), the type of label it is (boundary or line) and the location where you want to set it (hz). This is done by pushing CIQ.ChartEngine.XAxisLabel() elements into the axisRepresentation array.

See CIQ.ChartEngine.XAxisLabel for additional details on format and requirements.

You have to push either:

axisRepresentation.push(new CIQ.ChartEngine.XAxisLabel(hz,"boundary",text));  

or

axisRepresentation.push(new CIQ.ChartEngine.XAxisLabel(hz,"line",text));

You also have to create the chart.xaxis array which is used by the HUD (crosshairs) as you slide the mouse trough the chart.

This array takes objects of the following format:

    var obj={
    DT: current date,                    // in js date format
    Date: CIQ.yyyymmddhhmm(dtShifted)     // in string format
};

For each item you add to the xaxisRepresentation array, you add a corresponding one like so:

chart.xaxis.push(obj);

Option 3:

Allow the default axisRepresentation array to be created, but intercept it and adjust it before it is used. For this you can use an API injection similar to this:

CIQ.ChartEngine.prototype.prepend("createXAxis",function(chart){ 
        axisRepresentation = this.createTickXAxisWithDates(chart);
        // add you logic here to adjust the default axisRepresentation array as needed
        // iterate trough each element and adjust labels(text) or horizontal location (hz)
        return axisRepresentation;
});

More granular x-axis

CIQ.ChartEngine#createTickXAxisWithDates is the method called by CIQ.ChartEngine.AdvancedInjectable#createXAxis to do all of the axisRepresentation calculations. It is algorithmically designed to create an x-axis that is responsive to various degrees of user panning, zooming, and periodicity selection. It will print different versions of dates or times depending on those factors, attempting to prevent overlaps and evenly spacing labels. It will do this by finding the closest match in a pre-set map of allowed values. (This algorithm will only be used if timeUnit and timeUnitMultiplier are not set) .

The map will contain an entry for every time unit it can display (second,minute,hour, etc), each containing

                arr: list of possible timeUnit Multipliers
                minTimeUnit: lower range for the interval
                maxTimeUnit: upper range for the interval

The default map is as follows, but you can override this as well:

                stxx.timeIntervalMap={};
                stxx.timeIntervalMap[CIQ.MILLISECOND]={
                    // a label will be attempted to be placed every 
                    // 1,2,5,10,20,50,100,250 or 500 MILLISECONDS
                    // as space permits.
                    arr: [1,2,5,10,20,50,100,250,500],        
                    minTimeUnit:0,
                    maxTimeUnit:1000
                };
                stxx.timeIntervalMap[CIQ.SECOND]={
                    arr: [1, 2, 5, 10,15,30],
                    minTimeUnit: 0,
                    maxTimeUnit: 60
                };
                stxx.timeIntervalMap[CIQ.MINUTE]={
                    arr: [1,2,5,10,15,30],
                    minTimeUnit: 0,
                    maxTimeUnit: 60
                };
                stxx.timeIntervalMap[CIQ.HOUR]={
                    arr: [1, 2, 3, 4,6,12],
                    minTimeUnit: 0,
                    maxTimeUnit: 24
                };
                stxx.timeIntervalMap[CIQ.DAY]={
                    arr: [1,2,7,14],
                    minTimeUnit: 1,
                    maxTimeUnit: 32
                };
                stxx.timeIntervalMap[CIQ.MONTH]={
                    arr: [1,2,3,6],
                    minTimeUnit:1,
                    maxTimeUnit:13
                };
                stxx.timeIntervalMap[CIQ.YEAR]={
                    arr: [1,2,3,5],
                    minTimeUnit:1,
                    maxTimeUnit:20000000
                };
                stxx.timeIntervalMap[CIQ.DECADE]={
                    arr: [10],
                    minTimeUnit: 0,
                    maxTimeUnit: 2000000
                };
            }

The timeUnit multipliers will be used in the order in which they appear as long as the resulting label date is within the minTimeUnit and maxTimeUnit range.

For example, if the chart is currently displaying a zoom level where day labels should be displayed as determined by time differential and distance between bars, the following entry on the map will be activated:

                stxx.timeIntervalMap[CIQ.DAY]={
                    arr: [1,2,7,14],
                    minTimeUnit: 1,
                    maxTimeUnit: 32
                };

The algorithm will attempt to add a label first every 1 day. If there is not enough room to fit it, it will attempt every 2 days and so on. Once the right multiplier is found, it will be used until maxTimeUnit is reached. So if there is only room to have daily labels every 7 days, you will see them on dates that are multiples of 7. So there will be a label on :

  • 7th of the month
  • 14th or the month
  • 21st of the month
  • 28st of the month Assuming those dates match existing bars. Otherwise they will be skipped.

Example for overriding the default algorithm with hard coded values:

stxx.chart.xAxis.timeUnit = CIQ.DAY;
stxx.chart.xAxis.timeUnitMultiplier = 7;

This will generate labels on dates that are multiples of 7. So there will be a label on :

  • 7th of the month
  • 14th or the month
  • 21st of the month
  • 28st of the month Assuming those dates match existing bars. Otherwise they will be skipped.

Of course, you will have to adjust your override as your periodicity changes to maintain a reasonable interval between tags.

Rendering

Once the spacing has been calculated, the rendering process will begin. Just because a specific spacing has been set, it doesn't mean there will be enough space to use it. When in tick periodicity, for example, since it is not a constant interval, sometimes there won't be a minimum number of ticks required to create enough space for a label to display, so it will be skipped at rendering time. To address this, you can try changing with the zoom level by setting a smaller span and thereby creating more space between the ticks ( see CIQ.ChartEngine#setSpan and Managing Chart Zoom and Range. You can also try to change the xaxis label width settings to allow less white space between the labels. That is done with CIQ.ChartEngine.XAxis#minimumLabelWidth

Example:

stxx.chart.xAxis.minimumLabelWidth=20;