J4L-CHART for Ruby

Copyright 2011, J4L Components (http://www.java4less.com)
Go bak to contents

Axis configuration / parameters

• The label
• The ticks
• The scale's labels
• The grid
• Cero position axis
• Closed axis
• Dates
• Second Y axis
• Look of the axis
• X axis on top
• Additional (secondary) axis
• Axis target zones
• Axis label templates

J4L-Chart supports 3 axis, a horizontal axis (X) at the bottom of the chart, and 2 vertical axis to the left (Y) and to the right (Y2) of the chart.

The label

Each Axis can have an associate label. The label of the following example is "Million $":

The properties of the label are:

• Text: text of the label.
• Font: font used to paint the label.
• Color: color of the label.
• Vertical: if true, the text will be painted vertically (rotated).

The following example paints a blue vertical label with "Serif" font:

The ticks

J4L-Chart supports 2 kind of ticks:

• small ticks: these are ticks between big ticks, they do not have any label.
• big ticks: these ticks are always displayed with a label.

There are 2 ways you can control the number and position of the ticks in the scale:

Manual: You can use the following parameters to define the spacing between ticks:

• TICK_INTERVALY: distance between small ticks (in axis units).
• BIG_TICK_INTERVALY: Number of small tick between big ticks. Note that these are not axis units, these are number of small ticks.

 

the default values are:

an example is:

Automatic: you can also let J4L-Chart calculate the value for the tick interval using the following parameters:

• YAXIS_AUTO_TICKS: if not 0 , J4L-Chart will calculate the tick interval for the Y axis. This parameter is used to define the number of desired ticks.
  
• YAXIS_PREF_TICK_INTERVAL: Only used if AXIS_AUTO_TICKS is true. J4L-Chart will use the interval in this list which is more appropiate to get the desired amount of ticks. The default is:

VALUE="0.1|0.5|1|5|10|25|50|100|250|500|1000|5000|10000|50000|100000|500000|1000000"

For example, if your values range from 0 till 300 and the desired number of ticks is 10. J4L-Chart will select tick_interval=25 which will result in 12 ticks. See screenshot.

Other ticks parameters

If you don't want to have small ticks you can set BIG_TICK_INTERVALY=1. For example:

Ticks at irregular interval

The tick interval parameters allows you to define the position of the ticks. These are displayed at fixed intervals only. You can also use the BIG_TICK_INTERVAL_LISTY parameter to define the positions where the big ticks should appear. For example:

The following parameters allow you to control the length of the ticks. For example, you can remove the small ticks by making its length=0:

The scale labels

Labels are always displayed at the big ticks positions. The following parameters allow you to modify the labels.

XAXIS_LABEL_FORMAT. If XAXIS_INTEGER is false, this format will be used to draw the label. For example "%.2d" will always display 2 decimal digits. The format uses the following format:

%[width][.precision]specifier

where

• width is the fixed number of digits
• precision is the fixed number of decimal digits
• specifier is "d" for decimal

See documentation of the ruby sprintf function for a complete list of format options.

The following parameter will remove the digits right of the decimal separator:

• You can specify your own text for the labels using:

You can split your labels in sereval lines by using "\n".

or paint labels vertically (or with any rotation angle):

The grid

J4L-Chart will by default no display a grid:

however you can add the grid with the following parameters:

which let you define the style of the line used for the grid lines.

If you want to get a finer grid you can display the grid at the small tick positions with:

You can of course display lines for 1 axis only, for example:

You can also set an alternate filling for the grid. In the example you see the background alternates white and grey.

Cero position axis

If your scale's minimum value is less than cero, you might want to paint a line at the cero possition to be used as reference by the user.

You can also define the cero axis to include the ticks (the labels are still painted at the bottom of the chart).

Closed axis

The following parameters allows you create a "frame" around the chart.

Dates

You can use dates as labels for the ticks with the following parameters:

• XAXIS_DATE_FORMAT (default is %d-%m%y): format of the label. The format is the same as used by the Ruby method strftime. Some useful values are: %a (week of the day), %b (month name), %H (hour of day), %M (minute of hour), % m (month in year), %d (day of month), %y (year), %Y (year with century) and %S (second) 
• XAXIS_DATE_STEP: scale unit. The default is "d" which means 1 unit is 1 day. Other values are "m" (months), "w" (week) , "y" (year), "h" (hours) and "n" (minutes). You can also use "d3" ( 3 days), "m2" (2 months) ....
• XAXIS_INITIAL_DATE: this date will be used as base (first tick) if you want to calculate dates for the tick labels. Incompatible with logarithmic scales.
  

will result in the following secuence of ticks/labels

- big tick, label "01-Jan-01"
- small tick, no label
- big tick, label "03-Jan-01"
- small tick, no label
- big tick, label "05-Jan-01"
- .....

Example 1:

Example 2:

Example 3:

Second Y Axis

In order to activate the second Y axis you must use:

Y2AXIS =true

then you can define which data serie will use the scale of the second axis (serie 2 is the blue line)

Look of the axis

The following three parameters define the color and style of the axis

Axis can be painted as a bar (see screenshot below) using the following parameters:

• ?AXIS_BAR_STYLE: style of the axis REGULAR or BAR
• ?AXIS_BAR_WIDTH: width of the bar (the default is 12)
• ?AXIS_FILLING: fill style of the bar

where ? is X, Y , Y2 , X_1 ... and so on

X Axis on top

If you want to place the x scale on the top of the chart, instead of on the bottom you can use the following parameters:

Note that this is not supported for 3D charts.

Additional (secondary) axis

In addition to the main axis (Y , X and Y2 axis) you can define additional (or secondary) axis which are displayed parallel to the main axis. There is no limit in the number of axis you define other than the space available in your chart. If you create secondary axis you will normally also need to increase the margin reserved for the axis (left , bottom or right margin).

Secondary axis can be enabled with the ?_AXIS parameter where ? can be X_1, X_2 ... for the X axis, Y1_, Y_2 ... for the Y axis and Y2_1, Y2_2 ... for the Y2 axis ( right hand side Y axis).

The following screenshot displays a chart with a secondary Y axis (the blue one):

The parameters SERIE_SECONDARY_XAXIS_* and SERIE_SECONDARY_YAXIS_* are used to specify that a given data serie must be plotted using a secondary axis.

The axis can also be stacked as in the screenshot below using the parameter ?AXIS_STACK_ADDITIONAL=TRUE. As a result the chart gets splitted in 2 areas which can be used to plot 2 charts one on the top of the other:

If you also create a secondary axis for the X axis and stack them, you will get 4 subcharts as in the screenshot:

Axis Target zones

Axis Target zones are used to remark a range of values in the axis. The following screenshot shows an axis with 2 target areas:

As you can see target zones can be lines or areas (with start and end positions). The ?AXIS_TARGET_ZONE_* parameters are used to add target zones to the charts. The syntax of the parameter is:

?AXIS_TARGET_ZONE_*=<start value>;<end value>;<line style>;<fill style>;<label>

where:

• ? can be X , Y , Y2 , X_1 , X_2 , Y_1, Y_2 and so on.
• * is a counter 1,2,3,4 and so on.
• <start value>: position of the target zone.
• <end value>: (optional) end position of the zone
• <line style>: style of the line for the borders of the zone
• <fill style>: (optional) style for filling the zone
• <label>: (optional) text to be displayed as label

The 2 zones in the example above are defined as:

Axis label templates

The ?AXIS_TEMPLATE parameter allows you to define a template which will be applied to the labels which must be painted next to the axis ticks. The template must contain the string #value# which will be replaced by the actual value of the tick to be painted.

The following screenshot and table shows an example of use of this parameter: