RChart, User Guide

J4L-CHART for Ruby

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

Configuration objects

Label markup language
Target zones
Notes
Format of the values

Label markup language

J4L-Chart provides several properties and parameters to define the text to be used as title, labels for the axis , labels for the values and other. It also provides a way to select the color and font to be used in each case.

Starting with version 2.1 you can also use the label markup language to define the appearance of the labels. The language allows you to:

modify the font and color of parts of the label
rotate the label
define the aligment
add images to the label
add a border to the label
modify the position of the label
and more

The language is made of tags which are inserted in the label's text and processed by J4L-Chart before rendering the text. The format of the tags is:

@tagname attributename1='value' attributename2='value' ....@

Tags start with the character @, followed by the tagname and one or more attributes. Each attribute is made of the attribute name followed by the equal (=) sign and the value enclosed in single quotes ( ' ). Most tags have only 1 attribute , called value. Tags must end with the character @.

There are 2 kind of tags:

global tags: these tags should appear only once in the text and will be applied to the whole label. For example, the rotation and alignment tags are global tags.
local tags: these tags can appear several times in the text and will change the current value of a given property. For example the color and the font are local tags, which can be changed as many times as needed.

The following table shows all available tags

*Tag name (and type)*	Attributes	Description and example
name (global)	value	Name of the label (optional). The name can be used in java code to identify which label has been clicked. You can use chart.selectedLabel.getName() to read the name of the clicked label.
tip (global)	value	Tip of the label (optional)
background (global)	value	Background color of the label. Example: @background value='RED'@
border (global)	value	Line style of the border. Example: @border value='1\|BLACK\|NORMAL'@
clickinfo (global)	value	Additional information. It is normally used to hold a html link which will be opened when the user clicks on the label. You can use chart.selectedLabel.getClickInfo() to read the value of the property in your java code.
rotation (global)	value	Use this tag to rotate the label. Valid values are: 0,45,90,180 and 270. For example: @rotation value='90'@
position (global)	value	Use this tag to change the default position of the label. You can define the position using axis units, pixels or percentages. For example: @position value='10px,20px'@ will paint the label at pixel (10,20). @position value='10%,20%'@ and the size of the chart is 200x200, it will paint the label at pixel (20,40). @position value='10,20'@ will paint at position 10 according to the X axis and at position 20 according to the Y axis. You can also use the signs + / - to defined a relative position. For example: @position value='+10px,+0px'@ will paint the label ten pixels to the right of the default position.
align (global)	value	Use this tag to change the alignment of the text and images in the label. Valid values are LEFT, CENTER and RIGHT.
size (global)	value	Use this tag to change the size of the label (see also position tag)
anchor (global)	value line	The tag allows you to paint a line from the label to an "anchor" point. The value attribute contains the position of the point and the line attibute the style of the line. For example: @ANCHOR value='1,2' line='1\|GREY\|DOTS'@
margin (global)	value	The margin allows to increase the distance between the text in the label and the border. A margin of 3 pixels is defined as: @margin value='3'@
color (local)	value	Use this tag to select the current font color. The new color will be applied to the text after the font tag only. For example: @color value='RED'@
font (local)	value	The font is used to change the current font. The new font will be applied to the text after the font tag only. For example: @font value="arial\|PLAIN\|10'@
image (local)	value	Adds an image to the label. For example: @image value='myImage.gif'@
\n		You can use the string \n (in java code defined as "\\n" ) to create a new line in your text.

The following table includes some examples and the resulting image:

*Name*	Code	Result
Changes of fonts in the label.	@align value='CENTER'@Survey Results\n@Font value='Arial\|PLAIN\|9'@Coffee machine Customer Satisfaction survey\nconducted by two independent consultants
Changes of colors in the label.	@position value='15%,12%'@@font value='Arial\|BOLD\|12'@@color value='RED'@London @color value='BLACK'@/ @color value='BLUE'@Paris
Rotation of the text	@position value='72%,20%'@@rotation value='90'@@font value='Arial\|BOLD\|14'@Weather statistics
Border and background	@position value='30%,90%'@@size value='0px,22px'@@border value='1\|BLACK\|NORMAL'@@background value='WHITE'@@font value='Arial\|BOLD\|12'@ Last year
Adding line to anchor point	@position value='0px,94%'@@size value='100%,6%'@ @background value='0x33ccff'@Copyright J4L Examples
Adding an image	@image value='rain.gif'@\n\nRainy
Setting size and position	@position value='0px,94%'@@size value='100%,6%'@ @background value='0x33ccff'@Copyright J4L Examples

Note: there are two parameters; SERIE_LABEL_TEMPLATE_* and *AXIS_TEMPLATE which are used to define the label of the value in the chart and the axis. These label must contain the literal #value# which will be replace at runtime with the value to be plotted.

Target zones

Target zones are used in line and bar charts to remark a range of values in the plotter area. The follwing screenshot shows a chart with 2 target zones:

a vertical target zone which expand from the third value to the fifth value of the X Axis (Saturday till Monday). The target zone is used to remark a weekend.
a horizontal target zone which marks the "Profitability threshold" at position 30 of the Y axis.

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

CHART_TARGET_ZONE_*=<start value>;<end value>;<line style>;<fill style>;<label>;<orientation>

where:

<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
<orientation>: TRUE (for vertical) and FALSE (for horizontal).

The 2 zones in the example above are defined as:

Parameters

Equivalent Ruby class/property

CHART_TARGET_ZONE_2=30;;2|RED|NORMAL;;@Position value='15%,-25px'@@font value='ARIAL|ITALIC|12'@Profitability threshold;FALSE

Note: you can also use % instead of absolute values:

CHART_TARGET_ZONE_2=30%;;2|RED|NORMAL .....

will create a target zone at position 30% of the Y axis (if vertical, or x axis if horizontal).

value="3;5;1|BLACK|NORMAL;LIGHTBLUE|0.5;@........"
chart.addTargetZone( J4LChart::TargetZone.createFromString(value))

zone= J4LChart::TargetZone.new(3,5, J4LChart::UNIT_USER, J4LChart::UNIT_USER)
zone.style= J4LChart::LineStyle.new(1,J4LChart::GraphicsProvider.getcolor( J4LChart::BLACK), J4LChart::LINE_NORMAL)
zone.fillStyle= J4LChart::FillStyle.new( J4LChart::GraphicsProvider.getcolor( J4LChart::LIGHTBLUE),0.5)
zone.label="@font value='ARIAL|PLAIN|12'@@Position value=',-25px'@Weekend":
zone.vertical= true

if you have no end position you use:

zone= J4LChart::TargetZone.new( 3, J4LChart::DISABLED, J4LChart::UNIT_USER, J4LChart::UNIT_USER)

Notes

Notes are chart labels which you define using the label markup language. The label includes always the position tag since notes have no default position and you must specify it.

The following example shows a chart note:

Notes are created using the CHART_NOTE* parameter(where * is a counter starting at 1).

*Parameters*	*Equivalent Ruby class/property*
CHART_NOTE1=@image value='warning.PNG'@ @ANCHOR value='1,2' line='1\|GREY\|DOTS'@ @position value='15%,15%'@Manual tunning\n performed at 6:00	note="=@image value='warning.P......" chart.addNote(note)

Format of the values

When you create a linechart or barchart you will normally display the values next to the bar , point or line.

The format of the values can be configured using several parameters:

SERIE_FORMAT_*: indicates the format of the numeric values in the chart. The default is: "#####.##". (use 0 to indicate a digit, # to indicate a digit or empty and . for the decimal separator)
SERIE_DATA_LABELS_*: is a list ( | separated) of user defined labels which will be painted instead of the value itself. For example, if you are plotting the values "SERIE_DATA_1=1|2|3" you could use as labels "SERIE_LABEL_TEMPLATE_1=one|two|three".
SERIE_LABEL_TEMPLATE_*: the template allows you so add markup language tags to the value. The string #value# will be replaced by the value to be plotted. For example, the following parameter:

SERIE_LABEL_TEMPLATE_1=@background value='WHITE'@@border value='1|BLACK|NORMAL'@ #value#

will produce the labels as seen in the screenshot below.

where * is the number of the serie

The following table shows the equivalent java properties for the parameters:

Parameters

Equivalent Ruby class/property

SERIE_FORMAT_1=####

SERIE_DATA_LABELS_1=one|two|three

SERIE_LABEL_TEMPLATE_1=@background value='WHITE'@@border value='1|BLACK|NORMAL'@ #value#

dataSerie.valueFormat="####"

dataSerie.dataLabels=["one","two","three"]

dataSerie.labelTemplate="@background value='WHITE'@@border value='1|BLACK|NORMAL'@ #value#"