Configuration

This chapter will guide you through the set of Chart configuration options. It explores both common dhtmlxChart properties actual for all chart types and the config options individual for particular types.

You need to set necessary properties from those listed below within the configuration object passed to the chart constructor function and thus adjust the chart settings to meet your needs.

Main properties

dhtmlxChart includes several configuration options that are mostly common for all chart types. They are:

type - (string) defines the type of a chart to initialize; "bar", "x-bar" (for horizontal Bar chart), "line", "spline", "scatter", "area", "splineArea", "donut", "pie", "pie3D" and "radar"

var chart = new dhx.Chart("chart", {
    type:"bar"
});

scales - (object) defines configuration of chart scales. Check details below.

var chart = new dhx.Chart("chart", {
    scales:{}
});

series - (array) defines configuration of chart series. Check details below.

var chart = new dhx.Chart("chart", {
    series:[]
});

legend - (object) defines the configuration of a chart legend. Check details below.

var chart = new dhx.Chart("chart", {
    legend:{}
});

maxPoints - (number) displays an average number of values in case a data set is too large to show all the values in the chart

var chart = new dhx.Chart("chart", {
    type:"line",
    maxPoints:100
});

Related sample: Chart. Max Points

Scales

There are "left","right","top","bottom" and "radial" (for Radar chart) types of scales. Scales have both common and specific options.

var chart = new dhx.Chart("chart_container",{
    type:"area",
    scales: {
        "bottom" : {
            text: 'month'
        },
        "left" : {
            padding: 10,
            max: 90
        }
    },
    series: [
        {
           value: 'company A',
           strokeWidth: 2
           // more options   
        }
    ]
});

type - (string) the type of a scale: "left","right","top","bottom","radial" (see details below)
title - (string) sets a title for a scale
Related sample: Chart. Scale Title
text - (string) sets a template for labels of data items rendered on a scale
textTemplate - (function) sets a template for scale labels
Related sample: Chart. Text Template For Scale Labels
textPadding - (number) distance between labels of data items and the scale
showText - (boolean) shows/hides labels of data items on the scale
scaleRotate - (number) the degree of rotation of labels of data items on the scale
Related sample: Chart. Scale Rotate
scalePadding - (number) distance between the scale and its title
hidden - (boolean) hides/shows the whole scale
grid - (boolean) shows/hides the grid lines (for x,y, or both scales). true by default for both scales (scales lines are shown). To hide both scales lines, you need to set grid:false in the configs of each scale
Related sample: Chart. Grid
dashed - (boolean) sets the dashed type for a scale. Use the dashed:true option in the configuration of the scale
Related sample: Chart. Dashed Grid
targetLine - (number) shows a threshold line (a target value); looks for the specified value in the data
Related sample: Chart. Target Line
targetValue - (number) allows setting a threshold line at any defined level (any number, not necessarily from the data)
Related sample: Chart. Target Value
max - (number) the maximal value of the Y scale
min - (number) the minimal value of the Y scale
log - (boolean) sets the Y scale as logarithmic
padding - (number) the padding between the values of the Y scale (area)
maxTicks - (number) sets the maximal number of ticks on the Y scale
size - (number) sets the padding between the scale and the chart container
locator - (string) points to the data property, the values of which should be rendered in the chart (used for Scatter chart only)

The radial scale is used for Radar chart and has its own properties, due to peculiarities of configuration:

radial scale
- value - (string) the name of a data set property to take data values from (map to)
- zebra - (boolean) sets a striped scale coloring for the Radar chart (alternation of two colors in a step)
- showAxis - (boolean) renders values of the scale

Series

Series present an array of objects each of which contains a number of properties for rendering a separate data set on a chart.

var chart = new dhx.Chart("chart_container",{
    type:"bar",
    scales: {
        "bottom" : {
            text: "month"
        },
        "left" : {}
    },
    series: [
        {
            id: "A",
            value: "company A",
            fill: "#394E79",
            stacked: stacked,
            color: "none"
        },
        {
            id: "B",
            value:"company B",
            fill: "#5E83BA",
            stacked: stacked,
            color: "none"
        }
    ]
});

The list of config options for series (for charts with scales)

id - (string) the id of a series
gradient - (function) a function that defines a color gradient for bars
Related sample: Chart. Bar Gradient
type - (string) the type of a chart
active - (boolean) defines, whether a series is active/inactive
pointColor - (string) the color of data item points in a series
dashed - (boolean) sets the dashed type for a series line
strokeWidth - (number) the width of the chart outline
value - (string) the name of a data set property to map data values to
pointType - (string) sets the type of the point of the data item. There are the following point types:"circle","rect","triangle","rhombus","simpleRect","simpleCircle","empty"
Related sample: Chart. Point Types
css - (string) adds a style class for a series
color - (string) the color of the series outline
tooltip - (boolean) shows values of data items in tooltips, true by default
tooltipTemplate - (function) a function that defines a template for showing values of data items in tooltip
Related sample: Chart. Tooltip Template

Options specific for Area, Bar and Radar charts

fill - (string) the color of the series filling in Hex format
alpha - (number) transparency of the series filling

Options specific for Bar charts

baseLine - (number) sets a base line for rendering data items (bars)
Related sample: Chart. Base Line
stacked - (boolean) defines whether a stacked chart will be rendered
Related sample: Chart. Stacked Chart
barWidth - (number) sets the width of bars
showText - (boolean) shows/hides values of data items in bars
showTextTemplate - (function) a function that specifies the template for showing values of data items in bars
showTextRotate - (number|string) the degree of rotation of text values of data items in bars
Related sample: Chart. Show Text

The list of config options for series (for charts without scales: Pie, Pie3D, Donut)

id - (string) the id of a series
text - (string) the name of the data set property to map labels of data values to
value - (string) the name of the data set property to map data values to
color - (string) points to the property in a data set that defines the color of a pie/donut sector
useLines - (boolean) shows/hides lines used to "connect" chart sectors with labels
subType - (string|boolean) specifies the subtype of a chart: "basic"|"percentOnly"|"valueOnly" (used for Donut chart only)
stroke - (string) the color of lines between sectors of a chart
strokeWidth - (number) the width of lines between sectors of a chart
monochrome - (boolean|string) colors chart sections in the shades of a color specified as a value of this property (e.g. "blue", "red"). It can be also set as HEX code (#ff00ff), as RGB code (rgb(255, 15, 0)) or as RGBA color code (rgba(255, 15, 0, 0.2)).
paddings - (number) paddings between a chart and its initial position
showText - (boolean) shows/hides values of data items on the chart (Pie, Pie3D)
showTextTemplate - (function) a function that specifies the template for showing values of data items on the chart (Pie, Pie3D)

Legend

The legend object may contain a number of options that define its configuration.

var chart = new dhx.Chart("chart_container",{
    scales: {
        // scales config
    },
    series: [
        // list of series 
    ],
    legend: {
        series: ["A", "B", "C"],
        valign: "top",
        halign: "right"
    }    
});

Related sample: Chart. Enable Legend

Related sample: Chart. Legend Position

The list of config options for legend (for charts with scales)

form - (string) the form of the legend markers ("rect" or "circle")
Related sample: Chart. Legend Form
itemPadding - (number) padding between legend items
halign - (string) the horizontal alignment of the legend block: "left"|"right"|"center"
valign - (string) the vertical alignment of the block: "top"|"bottom"|"middle"
series - (array) the list of series that should be shown in the legend
margin - (number) margin between the scale and the legend

The list of config options for legend (for charts without scales: Pie, Pie3D, Donut)

values - (object) maps attributes of legend items to data set properties. Contains the following properties:
- id - (string,number) the id of the series that will be bound to the legend
- text - (string) the pointer to the data value to take a text for the legend from
- color - (string) the pointer to the data value to take a color for the legend from
- alpha - (number) transparency of a legend item
form - (string) the form of the legend markers ("rect" or "circle")
itemPadding - (number) padding between legend items
halign - (string) the horizontal alignment of the legend block: "left"|"right"|"center"
valign - (string) the vertical alignment of the block: "top"|"bottom"|"middle"
margin - (number) margin between the scale and the legend