Chart shapes

chart namespace contains a set of shapes for creating various types of charts. You can learn about charts here.

Elements

Knob

Knob shape is a descendant of Pie element and is used to create a knob chart.

constructor

The chart.Knob constructor the following additional attributes besides the standard dia.Element attributes:

fill

[optional] A color or an array of colors (in case of multiple series) representing the color of the knob. If multiple series are used, the number of items in the value array and fill array should match. If they don't match, the first color from the fill array will be taken wherever a color on the index matching the current serie value is missing.

max

[optional] A maximum value of the knob. The same logic for multiple series as described for fill applies.

min

[optional] A minimum value of the knob. min together with max specify the range for the value. The same logic for multiple series as described for fill applies.

serieDefaults

An object with various properties specifying how series should be rendered. As Knob inherits from Pie chart, all of the properties described in Pie serie object applies here as well.

sliceDefaults

An object with various properties specifying how slices should be rendered. As Knob inherits from Pie chart, all of the properties described in Pie slice object applies here as well.

value

A number or an array of numbers (in case of multiple series) representing the value of the knob.

Methods

See the chart.Pie API methods for the list of methods available for the chart.Knob element.

Events

See the chart.Pie events for the list of events available for the chart.Knob element.

SVG structure

As chart.Knob inherits from chart.Pie, the SVG structure described in chart.Pie SVG structure applies here as well.

KnobView

Empty extension of dia.ElementView with no additional methods or properties.

Matrix

constructor

The chart.Matrix constructor the following additional attributes besides the standard dia.Element attributes:

cells

An array of cells each being an object that can contain SVG attributes for the cell rectangle. If a cell is undefined, it is not rendered. If the matrix is sparse, setting empty cells to an undefined value significantly improves performance when rendering large matrices.

labels

[optional] An object containing rows and columns arrays. These arrays contain objects defining the text for the labels on the respective axis. The most important ones are text (the actual label), font-size, font-family and fill but you can use any other SVG attribute for styling the labels.

MatrixView

Empty extension of dia.ElementView with no additional methods or properties.

Pie

constructor

The chart.Pie constructor the following additional attributes besides the standard dia.Element attributes:

pieHole

[optional] The size of the hole in the center of the pie. If the number is in the 0..1 interval, it is considered to be proportional to the pie radius. If it is bigger than 1, it is considered to by the absolute radius in pixels.

serieDefaults

[optional] An object with constious properties specifying how series should be rendered. All properties of this object are overruled by properties of the same names in the serie object.

series

An array of series.

sliceDefaults

[optional] An object with constious properties specifying how slices should be rendered. All properties of this object are overruled by properties of the same names in the slice object.

Types

Serie

These are items of the series array.

name - the name of the serie. This name is added as a CSS class to the serie SVG element. You can take advantage of this CSS class for further styling.
label - the serie label (used in the auto-generated legend)
data - an array of slices
startAngle - the angle in degrees the serie slices start to draw.
degree - the total degre of the serie in the pie.
showLegend - true if the legend for the serie should be shown, false otherwise.
labelLineHeight - the line height of the serie label in the auto-generated legend

When the above properties are defined in the serieDefaults options object, they will be applied to all the series unless overruled by properties in the serie object.

Slice

These are items of the data array of the serie object.

value - a number specifying the value for the slice data point.
label - the label for the slice. This lable is used in the legend.
fill - the fill color (or gradient) of the slice.
innerLabel - the template for the label rendered inside the slice. The format for the template is derived from the Python format() function. Properties are enclosed in curly brackets and formats can be specified using the Python Format Specification Mini-Language. For example:

'{label}: {value:.2f}'  // 'My Slice: 2.26', i.e. value is rounded to two decimal numbers.

See the API reference for more examples on number formatting. You can use the following properties in your template: value, label, percentage, angle, startAngle and endAngle.

innerLabelMargin - the gap between the middle of the text label and the serie border in the pie. If value between 0...1 is used, it is considered to be proportional to the outer radius. If the number is bigger than 1, it is considered to be an absolute distance in pixels.
legendLabel - the template for the label for the slice used in the legend. Uses the same formatting as innerLabel.
legendLabelLineHeight - the line height of the slice label in the legend.
legendLabelMargin - the gap between the circle representing the slice color and the slice label in the legend.
offset - the offset of the slice. This option is useful for exploding slices and makes sense only for the outermost slices of the pie. If offset is between 0...1 is used, it is considered to be proportional to the outer radius. If the number is bigger than 1, it is considered to be an absolute distance in pixels.
onClickEffect - the effect applied when the user clicks on the slice. This is an object with the property type that can be either 'enlarge' or 'offset'. If 'enlarge' type is used, the object can have an additional property scale which is the scaling factor for the slice enlargement. If 'offset' type is used, the object can have an additional property offset which is the offset of the slice.
onHoverEffect - the effect applied when the user hovers with his mouse cursor over the slice. This is an object with the property type that can be either 'enlarge' or 'offset'. If 'enlarge' type is used, the object can have an additional property scale which is the scaling factor for the slice enlargement. If 'offset' type is used, the object can have an additional property offset which is the offset of the slice.

When the above properties are defined in the sliceDefaults options object, they will be applied to all the slices unless overruled by properties in the slice object.

Methods

addSlice(slice, serieIndex [, opt])	Append a slice `slice` to the serie identified by `serieIndex`. `opt` can be an arbitrary object that is passed to the `onchange` handlers of the JointJS element.
editSlice(slice, sliceIndex, serieIndex [, opt])	Replace a slice in the pie by a new `slice`. The serie is identified by `serieIndex` in which the slice at index `sliceIndex` will be replaced. `opt` can be an arbitrary object that is passed to the `onchange` handlers of the JointJS element.

PieView

To access the view for a pie chart, use: paper.findViewByModel(chart).

clickSlice(sliceIndex, serieIndex)	Simulate a click on the slice. Note that this triggers the effects that you defined in the `onClickEffect` in the slice object.
mouseOverSlice(sliceIndex, serieIndex)	Simulate a mouse over on the slice. Note that this triggers the effects that you defined in the `onHoverEffect` in the slice object.

Events

To set a listener for the pie view events, use: paper.findViewByModel(chart).on('mousemove', myFunction).

mousemove	Continuously triggered when the user hovers over a slice. The handler is passed `slice` and `event` objects.
mouseover	Triggered when the user hovers over a slice. The handler is passed `slice` and `event` objects.
mouseout	Triggered when the user leaves a slice. The handler is passed `slice` and `event` objects.
click	Triggered when the user clicks a slice. The handler is passed `slice` and `event` objects.

SVG structure

The following is the chart SVG structure that you can take as a reference when styling chart elements.

<g class="background">
    <rect/>
    <text/>
</g>
<g class="data">
    <g class="slice serie-[index of the serie] slice-[index of the slice] [serie name?] [slice name?] [outer?] [hover?] [clicked?]" data-serie="[index of the serie]" data-slice="[index of the slice]" data-value="[value of the slice]">
        <path class="slice-fill"/>
        <path class="slice-border"/>
        <text class="slice-inner-label"/>
    </g>
    <!-- ... possibly more slices -->
</g>
<g class="foreground">
    <rect/>
    <text class="caption"/>
    <text class="subcaption"/>
    <g class="legend">
        <g class="legend-items">
            <g class="legend-serie [serie name?]" data-serie="[index of the associated serie]">
                <text/>
            </g>
            <g class="legend-slice [slice name?]" data-serie="[index of the associated serie]" data-slice="[index of the associated slice]">
                <circle/>
                <text/>
            </g>
            <!-- ... possibly more legend items  -->
        </g>
    </g>
</g>

Selector examples:

chart.attr('.legend-slice text/text-decoration' , 'underline')  // Underline a legend label.
chart.attr('.legend-slice text/font-size' , 13)  // Set a font size of all the legend texts for slices.
chart.attr('.slice-fill/stroke' , 'gray')  // Set a stroke color of a slice.
chart.attr('.slice-fill/stroke-width' , 1)  // Set a stroke width of a slice.
chart.attr('.slice-3 .slice-fill/filter', { name: 'dropShadow', args: { dx: 2, dy: 2, blur: 3 } })

Plot

constructor

The chart.Plot constructor the following additional attributes besides the standard dia.Element attributes:

axis

[optional] Axis definition. Currently, the object can contain only 'x-axis' and 'y-axis' properties representing the two axes of the chart.

markings

[optional] An array of markings. Markings can be both vertical or horizontal lines or rectangles with optional label text.

padding

[optional] An object with top, bottom, left, and right attributes that specify the paddings between the chart contents and the chart boundaries.

series

An array of series of data points.

Methods

legendPosition(position [, opt])	Set position of the legend. `position` is a string that can be one of `'n'`, `'nw'`, `'w'`, `'sw'`, `'s'`, `'se'`, `'e'`, `'ne'`, `'nne'`, `'nn'`, `'nnw'`, `'nnww'`, `'nww'`, `'ww'`, `'sww'`, `'ssww'`, `'ssw'`, `'ss'`, `'sse'`, `'ssee'`, `'see'`, `'ee'`, `'nee'`, `'nnee'`. `opt.padding` can be used to set the distance between the legend and the chart edges. Default is `10` px.
addPoint(p, serieName [, opt])	Append point `p` to the serie identified by `serieName`. If `opt.maxLen` is set and the number of points in the serie is higher than `maxLen`, shift the data in the serie.
lastPoint(serieName)	Return the last point in the serie identified by `serieName`.
firstPoint(serieName)	Return the first point in the serie identified by `serieName`.

Types

Series

These are items of the series array.

name - the name of the serie. This name is added as a CSS class to the serie container (the SVG group element).
label - the serie label (used in the auto-generated legend)
data - an array of data points of the form { x: [number], y: [number] }
interpolate - (line charts) the interpolation method. The interpolation method can be one of:
- 'linear' - the default interpolation.
- 'bezier' - interpolation with a bezier curve.
- 'step' - step function
- 'stepBefore' - step function
- 'stepAfter' - step function
bars - (bar charts) if set to true, the series will be rendered as a bar serie using default options. You can override the default options by instead setting bars to an object with the following properties (all are optional):
- align - the alignment of the bars with respect to the x data point values. Possible values are 'middle' (default), 'left' and 'right'.
- barWidth - controls the width of the bars. If the value is a floating point number between 0 and 1, it is used to set the final width of each bar proportionally to the calculated width. The calculated width is computed such as, for a consecutive x values on the axis, the sum of the widths of all the bars equals the width of the chart area. If the value is an integer higher than 1, it is considered to be an absolute width in pixels.
- 'top-rx' - the top x radius of the bars. Together with the top-ry value, this allows you to define border radius for the bars.
- 'top-ry' - the top y radius of the bars.
showLegend - controls whether a legend item for the serie should be shown or not. If false, the legend item will be skipped. If it is a function, it should return true if the legend item should be shown, false otherwise. The function has the following signature: function(serie, stats), where serie is the serie object and stats is an object that holds some interesting statistics for the serie useful for deciding whether to show the legend item or not. The statistics are: decreasingX, decreasingY, maxX, maxY, minX, minY, nonDecreasingX and nonDecreasingY.
legendLabelLineHeight - controls the legend label line height. It defaults to 16.
hideFillBoundaries - (line charts) option to hide both fill boundaries. Default is false. Improves the look of line charts, but note that fill boundaries are necessary for the '.data .mySeries path/fill' attribute to correctly support area charts.
showRightFillBoundary - (area charts) option to show the right fill boundary. Default is false.
fillPadding - (area charts) an object whose attributes (left, right and bottom) determine the offsets of fill boundaries from the respective extreme data points (or the x-axis - for bottom). Default is { left: 0, right: 0, bottom: 10 }.

Markings

These are items of the markings array.

name - the name of the marking. This name is added as a CSS class to the marking container (the SVG group element). This makes it easier to style it.
label - the marking label. This is an auto-positioned text element.
start - the start coordinate of the marking. An object of the form { x: [number], y: [number] }. If only x is given, a vertical marking is rendered at that x-coordinate. If only y is given, a horizontal marking is rendered at that y coordinate.
end - the end coordinate of the marking. An object of the form { x: [number], y: [number] }. If only x is given, a vertical marking is rendered at that x-coordinate. If only y is given, a horizontal marking is rendered at that y coordinate. If both start and end objects are defined, a rectangular marking starting at start coordinates ending at end coordinates is rendered. (TIP: if you style your marking with high rx and ry values, you can make the marking look like a circle.)
attrs - additional SVG attributes that will be set on the marking container SVG element. This is sometimes useful if you want to store additional data associated with the marking in its DOM element. For example, when using tooltips.

Axis

These are properties of the axis object.

min - the precise minimum value for the scale. Specifying min and max values for an axis prevents the chart plugin from automatically choosing the minimum and maximum values, which is the default behavior. Note that for the y-axis, the bottom chart padding is considered as well - to ensure that the desired min value is actually shown at the bottom of the axis, set bottom padding to 0. See the Fixed axis section for more information.
max - the precise maximum value for the axis. Note that for the y-axis, the top chart padding is considered as well - to ensure that the desired min value is actually shown at the top of the axis, set top padding to 0. See the Fixed axis section for more information.

tickFormat - a format of the tick labels. This can be either a string in the Python Format Specification Mini-Language or a function that takes the tick value and returns the label for that tick. Example:

axis: {
    'x-axis': { // floating point value with one digit after the decimal point
        tickFormat: '.1f'
    },
    'y-axis': { // currency
        tickFormat: function(v) {
            return '$' + util.format.number('.2f', v)
        }
    }
}

tickSuffix - a string or a function that will be used as a suffix of the resulting formatted tick label. If it is a function, it is passed the tick value as an argument.
ticks - the number of ticks on the axis. On the y-axis, the default is 10. On the x-axis, the default is the number of discrete x-values in the data set.
tickStep - (x-axis) the modulus for tick display. Default is 1 (all ticks are displayed). Set this value to a higher number to filter out ticks. For example, setting this number to 10 makes the axis render only every 10th x-value encountered in the data set. Note that this option only works for the x-axis. This option is ignored if the axis has a ticks attribute.

PlotView

To access the view for a plot chart, use: paper.findViewByModel(chart).

renderPoint(p, serie)	Render a point at the coordinates defined in `p`. `serie` is the object from the `chart.Plot` `series` array and defines the serie for which the point should be rendered. Return the SVG DOM element for the point.
getSerieColor(serieName)	Return the color used to draw the serie identified by `serieName`.
hideSerie(serieName)	Hide serie identified by `serieName`.
showSerie(serieName)	Show serie identified by `serieName`.
closestPoints(x)	Return an array of the closest points from all the series in the chart for a given `x` coordinate.

SVG structure

<g class="background">
    <rect/>
    <text/>
</g>
<g class="data">
    <g class="slice serie-[index of the serie] slice-[index of the slice] [serie name?] [slice name?] [outer?] [hover?] [clicked?]" data-serie="[index of the serie]" data-slice="[index of the slice]" data-value="[value of the slice]">
        <path class="slice-fill"/>
        <path class="slice-border"/>
        <text class="slice-inner-label"/>
    </g>
    <!-- ... possibly more slices -->
</g>
<g class="foreground">
    <rect/>
    <text class="caption"/>
    <text class="subcaption"/>
    <g class="legend">
        <g class="legend-items">
            <g class="legend-serie [serie name?]" data-serie="[index of the associated serie]">
                <text/>
            </g>
            <g class="legend-slice [slice name?]" data-serie="[index of the associated serie]" data-slice="[index of the associated slice]">
                <circle/>
                <text/>
            </g>
            <!-- ... possibly more legend items  -->
        </g>
    </g>
</g>

Selector examples:

chart.attr('.caption/text', 'My Chart') // Set chart caption.
chart.attr('.subcaption/text', '2014') // Set chart sub caption.
chart.attr('.caption/fill', 'red') // Set chart caption text color.
chart.attr('.caption/font-size', 20) // Set chart caption font size.
chart.attr('.caption/ref-x', 10) // Move chart caption 10px from the left edge of the chart.
chart.attr('.guideline/display', 'block') // Display guidelines.
chart.attr('.x-axis .tick line/stroke', 'green') // Set the color of the ticks on the x axis.
chart.attr('.y-axis .tick text/fill', 'blue') // Set the color of the tick labels on the y axis.
chart.attr('.legend-item[data-serie="myserie"]/text-decoration', 'underline') // Underline a legend label.
chart.attr('.point/display', 'none') // Hide the data points.
chart.attr('.data .myserie .bar[data-x="5"]/fill', 'blue') // Set blue fill color for only the bar with x value 5.

Chart shapes

Elements​

Knob​

constructor​

fill​

max​

min​

serieDefaults​

sliceDefaults​

value​

Methods​

Events​

SVG structure​

KnobView​

Matrix​

constructor​

cells​

labels​

MatrixView​

Pie​

constructor​

pieHole​

serieDefaults​

series​

sliceDefaults​

Types​

Serie​

Slice​

Methods​

PieView​

Events​

SVG structure​

Plot​

constructor​

axis​

markings​

padding​

series​

Methods​

Types​

Series​

Markings​

Axis​

PlotView​

SVG structure​

Stay in the know

Elements

Knob

constructor

fill

max

min

serieDefaults

sliceDefaults

value

Methods

Events

SVG structure

KnobView

Matrix

constructor

cells

labels

MatrixView

Pie

constructor

pieHole

serieDefaults

series

sliceDefaults

Types

Serie

Slice

Methods

PieView

Events

SVG structure

Plot

constructor

axis

markings

padding

series

Methods

Types

Series

Markings

Axis

PlotView

SVG structure