900_090_Advanced_Legend
Previous Chapter Previous Page Next Page Table of content
In the core module of ChartNew.js, a "standard" legend with very limited possibilites to format it can be drawn. With this "Add-ins", you get lot of possibilities to format the legend.
Example :
In the core of ChartNew.js, two functions have been defined and are used to draw the legend : drawLegend and measureLegend. In order to use this "Add-ins", you have to include it AFTER the ChartNew.js. This Add-ins, will replace those two functions by two new ones with more possibilites.
<SCRIPT src='../ChartNew.js'></script>
<SCRIPT src='../Add-ins/drawLegend.js'></script>
If no additional specifications are defined in the code of your program, the new drawLegend and measureLegend functions will behave similar to the functions included in the core of ChartNew.js : the same legend will be drawn.
If you want to use the extended possibilities given by the add-ins, you have to specify a legend section in your data.
Example :
var mydata = {
labels : ["January","February","March","April","May","June","July"],
datasets : [
{
fillColor : "green",
data : [0.30,0.44,0.42,0.19,0.90,0.37,1.20],
title : "Bar 1"
},
{
fillColor : "red",
data : [0.30,0.42,0.35,0.19,0.96,0.27,1.00],
title : "Bar 2"
}
],
legend : [
{
element:"CR",
nextLineAlign : "center",
},
{
element : "shapeText",
text : "title of the legend",
elementWidth: "titre1",
elementHeight : "titre1",
fontSize : 20,
fontStyle : "bold italic",
fontColor: "black"
},
{
element:"CR"
},
{
element : "shapeText",
text : "First Element",
fontStyle : "bold",
fontColor: "black",
textVPos : 2,
textHPos : 2,
elementWidth: "width1",
elementHeight : "height1",
shapeWidth : "widthShape1",
shape : "rectangle",
shapeFillColor : "green"
},
{
element : "shapeText",
text : "Second Element",
fontStyle : "bold",
fontColor: "black",
textVPos : 2,
textHPos : 2,
elementWidth: "width1",
elementHeight : "height1",
shapeWidth : "widthShape1",
shape : "rectangle",
shapeFillColor : "red"
}
]
}
We will now explain what you have to specify in the legend section !
A legend is a collection of elements; An element is composed of a shape and/or a text.
In previous example, there are 3 elements : "Title of the legend" is the first one (this element has no shape associated), "First Element" and the green rectangle around is the second element; "Second element" and the red rectangle around is the third one. For each of those elements, there is a specification in the legend section in the data.
Those 3 elements have to be positionned in the legend. In the example, two additionnal specifications are necessary to set their position : one to specify that the title has to be centered and one after the title to force the display of the 2 other elements on another line.
So for the example, the legend section is composed of five specifications : one for each of the 3 elements and 2 for the positionning of those elements.
The legend is described through a table composed of two types of elements : "shape and/or text" elements and "positionning" elements.
var mydata = {
labels : [...],
datasets : [...],
legend : [<element 1>,<element 2>,...,<element n>]
}
Each element in the legend section is a group of variable. One of these variable is "element" which describe the type of the element. The value of element has to be "shapeText" for an element associated to a "shape and/or text" element; "CR" for a positionning element.
var mydata = {
labels : [...],
datasets : [...],
legend : [
{
element : "CR",
...
},
{
element : "shapeText",
...
}
]
}
If the variable "element" is not specificed, the default value for it is "shapeText".
In the next sections, we will explain the other variables.
Each time you want to force the positionning of an element on the next line, you have to insert a "CR" element. Each time that a "CR" element is specified, the "shape and/or text" elements that follows will be drawn on another line.
By default, (1) "shapeText" element are left aligned; (2) between two lines, there is a space of 5 points; (3) on a same line, each element are vertically centered on the line; (4) the maximum number of element on a line is the value of config.maxLegendCols (if not defined, the limit is the width of the chart).
When you want to change one of those default values, you have to add a variable in the "CR" element.
Example :
{
element : "CR",
CRSpace : 10,
maxLegendCols : 2,
nextLineAlign : "center",
nextLineBaseline : "bottom"
}
To change the space between two lines, you have to specify the space in the variable "CRSpace". The new value will be applied for the subsequent part of the legend.
Allowed value for variable CRSpace : any positive integer.
If the CRSpace variable is not specified in the "CR" element, the space between two lines remain unchanged.
To change the maximum number of element that may be drawn on the subsequent lines, specify the maximum number of elements through variable maxLegendCols. The new value will be applied for the subsequent part of the legend.
Allowed value for variable maxLegendCols : any positive integer.
If the maxLegendCols variable is not specified in the "CR" element, the value remain unchanged.
To change the alignment of the "shapeText" elements, you have to specify the alignment in the variable "nextLineAlign". The new alignment will be applied for the "shapeText" elements specified after the change.
Allowed value for variable nextLineAlign : "left", "center", "right".
If the nextLineAlign variable is not specified in a "CR" element, the alignment remains unchanged.
To change the vertical alignment of the "shapeText", you have to specify the vertical alignment in the variable "nextLineBaseline". The new vertical alignment will be applied for the "shapeText" elements specified after the change.
Allowed value for variable nextLineBaseline : "top", "center", "bottom".
If the nextLineBaseline variable is not specified in a "CR" element, the vertical alignment remains unchanged.
The "shapeText" elements has 4 kinds of variables : (1) variables that describe the text, (2) variables that describe the shape, (3) variables that describe the relative position of text and the shape and (4) some other variables.
Example :
{
element : "shapeText",
text : "Text to be printed",
textPaddingX : -10,
textPaddingY : 5,
fontFamily : "'Arial'",
fontSize: config.legendFontSize,
fontStyle: "bold italic",
fontColor: "black"
}
The most important variable is "text". In this variable, you specify the text that is to be associated to the "shapeText" element.
Allowed value : any character string.
If the text variable is not specified (or is an empty string), only the shape associated to the "shapeText" will be drawn.
The text will be positioned at a specific place (see textPosX and textPosY later on). With textPaddingX and textPaddingY, you can adjust the position of the text. textPaddingX to move horizontally the text; textPaddingY to move vertically the text.
If not specified, both variable are initialized with 0.
Allowed value : any positive or negative integer.
Through the variables fontFamily, fontSize, fontStyle and fontColor, you can specify the characteristic of the font.
If not specified, the font will be the value defined in the options "config.legendFontFamily", "config.legendFontSize", "config.legendFontStyle" and "config.legendFontColorArial.
Example :
{
shape : "line",
shapeHeight : 12,
shapeWidth : 50,
markerShape : "square",
markerCount : 3, // number of marker to draw
markerRadius : 2,
markerStrokeStyle : "solid",
markerFillColor : "green",
markerLineWidth : 1,
shapeBorders : true,
shapeBordersRadius : 3,
shapeBordersSelection : 15,
shapeBordersWidth : c1,
shapeBordersStyle : "dashed",
shapeBordersColor : "black",
shapeFillColor : "green",
shapePaddingX : 3,
shapePaddingY : -2,
(...)
}
The most important variable is "shape". In this variable, you specify the shape that is to be associated to the "shapeText" element.
In the current version, the allowed values are "rectangle", "line" or "ellipse" if you want to draw one of those 3 shape; Specify "none" if you only want to draw a text in the "shapeText" element.
With the shapeHeight and shapeWidth variables, you specify the size of the shape. For those variable you can specify a positive integer or ... a string variable.
If you specify a positive integer and if the element has no text associated or a text displayed outside the shape (*), the shape will have the width/height specified.
If you specify a positive integer and if the element has a text associated (variable "text" not empty) and if the text is inside the shape (*), the shape will have the maximum value between the specified width/height and the text width/height.
Example :
legend : [
{ // element 1
shape : "rectangle",
shapeHeight : "height1",
shapeWidth : "width1",
(...)
},
{ // element 2
shape : "rectangle",
shapeHeight : "height1",
shapeWidth : "width2",
(...)
},
{ // element 3
shape : "rectangle",
shapeHeight : "height2",
shapeWidth : "width1",
(...)
},
{ // element 4
shape : "rectangle",
shapeHeight : "height2",
shapeWidth : "width2",
(...)
}
]
If you specify a string value for shapeHeight/shapeWidth, all legend elements of type "shapeText" having a shapeHeight/shapeWidth with the same string value, will have the same width/height.
In our sample, the shape of elements 1 and 2 will have the same height; the shape of elements 3 and 4 will have the same height; the shape of elements 1 and 3 will have the same width; the shape of elements 2 and 4 will have the same width.
What will be the width / height
If the element has a text associated (variable "text" not empty) and if the text is inside the shape (*), the shape will have at least the width/height of the text.
If the element has no text associated or if the text is ouside the shape, the shape will have at least the value of config.legendBlockSize as width / config.legendFontSize as height.
The purpose of specifying a string as value is to have a legend that is well structured where all shapes have the same width/height.
The default value for shapeWidth is the value of option config.legendBlockSize; The default value for shapeWidth is the value of option config.legendFontSize.
(*) the text is inside the shape if the variables textHPos and textVPos have a value of 1, 2 or 3.
Those variables applies only if the shape is "line".
If the shape is a line, you can draw one or more markers on it. With the variable markerCount, you specify the number of markers that have to be drawn on the legend line.The other variables describes the marker him self. If markerShape is empty (default value), no markers are drawn on the line. See https://github.com/FVANCOP/ChartNew.js/wiki/100_070_Charts_Layout#markershape for more informations about markers.
Specify the fill color of the shape through the variable shapeFillColor.If not specified, the default value is specified by option config.defaultFillColor. shapeFillColor does not apply for lines. The color of the line is defined through the variable shapeBordersColor.
shapeBorders, shapeBordersRadius, shapeBordersSelection, shapeBordersWidth, shapeBordersStyle, shapeBordersColor
If you want to draw a border around the shape (does not apply for shape="line"), you have to set the variable shapeBorders to true ("true" is the default value for shapeBorders). Through shapeBordersWidth, shapeBordersStyle, shapeBordersStyle, shapeBordersColor and shapeBordersSelection, you can specify the specifications of the border.
Allowed values :
shapeBorders : true or false; shapeBordersWidth : any positive integer; shapeBordersStyle : see https://github.com/FVANCOP/ChartNew.js/wiki/190_Stroke_Styles shapeBordersSelection : see [textType]BordersSelection in https://github.com/FVANCOP/ChartNew.js/wiki/100_130_Border_and_Background_Color-for-text shapeBordersColor : any valid color.
Default value when not specified:
shapeBorders : true ; shapeBordersWidth : value defined in option config.datasetStrokeWidth; shapeBordersStyle : value defined in option config.datasetStrokeStyle; shapeBordersSelection : 15; shapeBordersColor : value defined in option config.legendBordersColors.
The shape will be positioned at a specific place (see textPosX and textPosY later on). With shapePaddingX and shapePaddingY, you can adjust the position of the shape. shapePaddingX to move horizontally the shape; shapePaddingY to move vertically the shape.
In the standard legend (delivered with the code of ChartNew.js), the text is always displayed at the right of a rectangle. With the drawLegend.js add-ins, you can set the text at another position.
With textHPos, you specify the horizontal position of the text : 0 : the text will be drawn at the left of the shape; 1 : the text will be drawn in the shape and aligned at the left of the shape; 2 : the text will be horizontally centered to the shape; 3 : the text will be drawn in the shape and aligned at the right of the shape; 4 : the text will be drawn at the right of the shape (this is the default value for textHPos)
With textVPos, you specify the vertical position of the text : 0 : the text will be drawn under the shape; 1 : the text will be drawn in the shape and aligned at the left of the shape; 2 : the text will be vertically centered to the shape (this is the default value for textVPos); 3 : the text will be drawn in the shape and aligned at the right of the shape; 4 : the text will be drawn over the shape
Between the text and the shape, you can specify the space (in point) through the variable HspaceBetweenShapeAndText for the horizontal space and the variable VspaceBetweenShapeAndText for the vertical space.
Allowed value : any positive integer
The default value for HspaceBetweenShapeAndText is the value of option config.legendSpaceBetweenBoxAndText; For : For VspaceBetweenShapeAndText, the default value is 5.
The space between two "shapeText" element is defined through the variable spaceBefore on the second element.
Such as what you did for the shape through the variable shapeWidth and shapeHeight, you can specify the width and height of the "shapeText" element.
Similary, you can define a positive integer or a string.
If you specify a positive integer, the element will have at least this size in point. If the shape and text of the element do not fit in this width/height, the width/height will be increased to fit at least the shape and text.
Example :
legend : [
{ // element 1
elementHeight : "height1",
elementWidth : "width1",
(...)
},
{ // element 2
elementHeight : "height1",
elementWidth : "width2",
(...)
},
{ // element 3
elementHeight : "height2",
elementWidth : "width1",
(...)
},
{ // element 4
elementHeight : "height2",
elementWidth : "width2",
(...)
}
]
If you specify a string value for elementHeight/elementWidth, all legend elements of type "shapeText" having a elementHeight/elementWidth with the same string value, will have the same width/height.
In our sample, the element 1 and 2 will have the same height; the elements 3 and 4 will have the same height; the elements 1 and 3 will have the same width; the elements 2 and 4 will have the same width.
What will be the width / height
For each element, we compute the minimum width/height necessary to draw the text and/or shape element it contains; The width/height will be the maximum of those computed width/height.
The purpose of specifying a string as value is to have a legend that is well structured where all elements have the same width/height.
The default value for elementWidth is the string "maxwidth" and for elementHeight, it is "maxheight".
If you want to put a title in your legend, it is possible to underline it !
How to define an underlined title ?
Put following as first element of your legend :
legend : [
{
element:"CR",
nextLineAlign : "center",
},
{
textHPos : 2,
textVPos : 2,
text : "title of the legend",
elementWidth: "titre1",
elementHeight : "titre1",
element : "shapeText",
shape : "rectangle",
shapeBorders : true,
shapeBordersSelection : 1,
shapeFillColor : "rgba(0,0,0,0)",
fontSize : 20,
fontStyle : "bold italic",
fontColor: "black"
},
{
element:"CR",
CRSpace : 10
},
(...)
]
