Skip to content

dimple.chart

Jump to bottom Edit New page
John Kiernander edited this page Nov 15, 2013 · 10 revisions

This is the fundamental object in dimple. If you have a dimple implementation which doesn't include it, you're doing something wrong - but don't worry, you came to the right place!

#####Constructor#####

#####Properties#####

#####Methods#####

Constructor

dimple.chart(svg, data) [code] - Initialise the chart with some data and an svg in which to render.

  • svg (Required): The svg in which to render. The object passed will be assigned to the svg property and used to render the chart. The bounds of the chart will also be initialised to fit inside this svg at the point at which the constructor is called. Bounds can be overridden manually via the individual x, y, width and height properties, the setBounds method or the setMargins methods.

  • data (Required): The data on which this chart will be based. The object passed will be assigned to the data property. This must be a flat JSON table in which the rows are consistent and each field is a simple type. It does not currently support nested objects. The best way to get data in this format is using the d3 data request methods.

Example:

// Get data from an external location and generate the chart when it returns
d3.json("MyAwesomeDataSource.json", function (data) {
	// Add an svg object to the body element
	var svg = dimple.newSvg("body", 1200, 800);
	// Create a new chart object based on this data and svg
	var myChart = new dimple.chart(svg, data);
	...
});

Properties

dimple.chart.axes [code] - A collection of dimple.axis objects assigned to this chart. This collection may contain as many axes as you wish, the first x axis will be rendered at the bottom of the chart, the second x axis at the top. The first y axis at the left and the second y axis on the right. Any further x or y axes will be hidden but may still be attached to series for positioning. The best way to add axes to the collection is via one of the add axis methods such as addCategoryAxis, addMeasureAxis, addPctAxis, addColorAxis or addLogAxis. This property is intended for accessing axes already added (however in most cases it is easier to assign the axis returned by the relevant add method to a variable).

Example:

// Check the number of axes added before and after adding
console.log(myChart.axes.length); // Logs 0
myChart.addMeasureAxis("x", "Sales Volume");
console.log(myChart.axes.length); // Logs 1

dimple.chart.data [code] - The data on which this chart will be based. This will be set by the constructor but can be changed via this property, for example when filtering and redrawing the chart. It must be a flat JSON table in which the rows are consistent and each field is a simple type. It does not currently support nested objects. The best way to get data in this format is using the d3 data request methods but it can be hard-coded JSON if you are just playing.

Example:

// Overwrite the initialised data with 4 rows of data.
myChart.data = [
	{ "Brand":"Coolio", "Region":"Hipsville", "Sales Volume":1000 },
	{ "Brand":"Uncoolio", "Region":"Hipsville", "Sales Volume":500 },
	{ "Brand":"Coolio", "Region":"Dullsville", "Sales Volume":100 },
	{ "Brand":"Uncoolio", "Region":"Dullsville", "Sales Volume":2000 }
];

dimple.chart.defaultColors [code] - A collection of dimple.color objects. These colors will be arbitrarily assigned to data values during the chart drawing. Once all colors have been used, the first will be used again. Once the chart has assigned a color to a particular data value, that value will receive the same color across all series. More details on this are available here. This collection is exposed to allow users to assign their own funky color schemes and override the defaults.

Example:

// 5.0 shades of grey
myChart.defaultColors = [
	new dimple.color("#333333"),
	new dimple.color("#666666"),
	new dimple.color("#999999"),
	new dimple.color("#BBBBBB"),
	new dimple.color("#EEEEEE")
];

dimple.chart.height [code] - The height of the chart's plot area within the SVG object in pixels. This should be a positive number. By default this is initialised at 80% of the SVG height. Please note, this is the bounds of the plot area, not all chart components. Some chart elements (such as axis text) will surround the plot area. This can be set directly, or via the setBounds method.

Example:

// Set the plot height to 800 pixels
myChart.height = 800;

dimple.chart.legends [code] - An array of dimple.legend objects to be rendered along with this chart when drawing. It may be preferable to use the addLegend method to add elements into this array, it is provided to allow you to reference previously created legends in your calling code. Manipulating this array before the chart draw method is called will affect the legend display.

Example:

// Lets add a couple of legends
myChart.addLegend(10, 10, 500, 30, "left", myFirstSeries);
myChart.addLegend(10, 10, 500, 30, "right", mySecondSeries);
// On second thought I don't want that last one
myChart.legends.pop();

dimple.chart.noFormats [code] - A boolean property which must be set to either true or false. By default this is set as false. To simplify your code dimple makes some decisions about style and applies these directly to the svg elements. This allows it to do things like dynamic coloring or font sizing. These can still be overridden in CSS using the !Important attribute, however if you want to use standard CSS to style your chart you can set noFormats to true and no style elements will be added. Be warned, this will look pretty ugly if you don't add the CSS.

Example:

// No formats please, CSS has got this covered.
myChart.noFormats = true;

dimple.chart.series [code] - A collection of dimple.series objects assigned to this chart. This collection may contain as many series as you wish using as many different plot types as required. The series are drawn in the order defined in this array, so the first series elements may be overlapped by the second series elements. This collection is provided for viewing series which have been added with the addSeries method. However it may be modified directly to remove or move a series.

Example:

// Add three series and remove the middle one using a standard JavaScript array operation
myChart.addSeries("Brand", dimple.plot.bar);
myChart.addSeries("Brand", dimple.plot.bubble);
myChart.addSeries("Brand", dimple.plot.line);
myChart.series.splice(1, 1);

dimple.chart.storyboard [code] - A dimple.storyboard object which will automatically animate the chart across the values in a given dimension. This can be set either directly with the storyboard constructor or using the setStoryboard method. The recommended approach is to use setStoryboard.

Example using setStoryboard:

// Construct and assign a storyboard using helper method
myChart.setStoryboard("Date");

Example using constructor:

// Construct and assign a storyboard directly
myChart.storyboard = new dimple.storyboard(myChart, "Date");

dimple.chart.svg [code] - The svg in which to render. This can be created using standard d3 methods or created with the dimple helper method dimple.newSvg.

Example with standard d3:

// Adding the SVG element using standard d3
myChart.svg = d3.select("body")
				.append("svg")
					.attr("width", 1200)
					.attr("height", 800);

Example with dimple:

// Adding the SVG element using dimple
myChart.svg = dimple.newSvg("body", 1200, 800);

dimple.chart.width [code] - The width of the chart's plot area within the SVG object in pixels. This should be a positive number. By default this is initialised at 80% of the SVG width. Please note, this is the bounds of the plot area, not all chart components, some chart elements (such as axis text) will surround the plot area. This can be set directly, or via the setBounds method.

Example:

// Set the plot width to 1200 pixels
myChart.width = 1200;

dimple.chart.x [code] - The horizontal position of the chart's plot area within the SVG object in pixels. By default this is initialised at 10% of the SVG width. This should be a positive number. Please note, this is the bounds of the plot area, not all chart components. Some chart elements (such as axis text) will surround the plot area. This can be set directly, or via the setBounds method.

Example:

// Set the horizontal position of the plot 100 pixels from left of SVG
myChart.x = 100;

dimple.chart.y [code] - The vertical position of the chart's plot area within the SVG object in pixels. This should be a positive number. By default this is initialised at 10% of the SVG height. Please note, this is the bounds of the plot area, not all chart components. Some chart elements (such as axis text) will surround the plot area. This can be set directly, or via the setBounds method.

Example:

// Set vertical position of the plot 100 pixels from top of SVG
myChart.y = 100;

Methods

dimple.chart.addAxis(position, categoryFields, measure, timeField) [code] - Add an axis to the chart. This will insert a new axis object in the axes property. It may be more simple to work with the helper methods addMeasureAxis, addPctAxis, addCategoryAxis, addColorAxis or addColorAxis.

  • position (Required): A string value indicating the positioning of the axis. It must be one of the following values:

    • "x": Creates an axis for determining horizontal positioning. The first x axis created will cross the first y axis at zero. The second will be positioned at the top of the chart. Any further x axes will be hidden but can still be used for positioning.

    • "y": Creates an axis for determining vertical positioning. The first y axis created will cross the first x axis at zero. The second will be positioned at the right of the chart. Any further y axes will be hidden but can still be used for positioning.

    • "z": Creates an axis for determining scale of elements. This axis does not render any visual elements and currently only affects bubble plots.

    • "c": This provides an axis for dynamically coloring a series based on a measure value. This requires at least a measure to be set, and will often require the axis colors property to be set. Adding a color axis is easier via the addColorAxis helper method.

  • categoryFields (Optional): Although the categoryFields and measure parameters are optional at least 1 must be provided. Either a single string value or an array of string values will be accepted for categoryFields. The following options are accepted values for categoryFields:

    • Single string value: e.g. .addAxis("x", "Brand", null). This string value must be a field name from the data and its distinct values will be used to create an ordinal axis. E.g. "Brand 1", "Brand 2"...

    • Array of two string values: e.g. .addAxis("x", ["Brand", "Region"], null). The string values should be field names in the data, and will create a clustered axis. The first category will define the axis values, the second will provide the nested points.

    • Null: e.g. .addAxis("x", null, "Sales Volume"). If set to null, the measure must be provided. This will create a linear numerical axis.

  • measure (Optional): Although the categoryFields and measure parameters are optional at least 1 must be provided. Either null or a single string value will be accepted. The following options are accepted values for measure:

    • Single string value: e.g. .addAxis("x", null, "Sales Volume"). This string value must be a field name from the data. If the field is numerical the values will be aggregated, otherwise a distinct count of values will be used.

    • Null: e.g. .addAxis("x", "Brand", null). If set to null, the categoryFields parameter must be provided. This will create an ordinal axis.

  • timeField (Optional): Setting a timeField here will cause this axis to behave as a time axis. Either null or a single string value will be accepted. The following options are accepted values for timeField:

    • Single string value: e.g. .addAxis("x", null, null, "Date"). This string value must be a field name from the data. The values in the timeField must be able to parse to dates. A format for the parsing can be provided to the dateParseFormat otherwise the default browser parse will be used which may cause inconsistency across browsers.

    • Null: e.g. .addAxis("x", "Brand", null, null). If set to null, the categoryFields or measure parameter must be provided. This will create a non-time axis

  • returns (dimple.axis): The newly added axis.

The other possible parameter combination not discussed above is to provide both categoryFields and a measure. E.g. .addAxis("x", "Brand", "Sales Volume"). This will create a scaled ordinal axis for charts such as a Mekko.

Example:

// Add a Brand ordinal axis on "x"
myChart.addAxis("x", "Brand", null);
// Add a Sales Volume linear numerical axis on "y"
myChart.addAxis("y", null, "Sales Volume");

dimple.chart.addColorAxis(measure, colors) [code] - Add a color axis to the chart. A color axis provides dynamic coloring for series. The way that the colors are applied is determined by the colors parameter explained below.

  • measure (Required): The field whose values will be used to allocate colors from a graded range. The minimum field value will be allocated to the first color in the range, the maximum to the last color. All other values will receive a graded color within the range.

  • colors (Optional): The following values are accepted:

    • Null/Undefined: e.g. .addColorAxis("Sales Volume"). Each series will be allocated a color as usual but the individual data point values will be graded from white based on the measure value. Minimum measure value will be white, maximum will receive its standard series color.

    • Single color: e.g. .addColorAxis("Sales Volume", "#FF0000"). Each series will be allocated a color as usual but the individual data point values will be graded from the provided color based on the measure value. In this example the minimum sales volume value will be red ("#FF0000") and the maximum will recieve its standard series color.

    • Color array: e.g. .addColorAxis("Sales Volume", ["#FF0000", "#00FF00", "#0000FF"]). All colors are distributed across the value range and elements colored based on their value's position in this line. E.g. in the example above, if Sales Volume ranged from 0 to 100 an element with a Sales Volume of 60 would be graded at 20% of the color change between "#00FF00" and "#0000FF" (which incidentally is #00CC32").

  • returns (dimple.axis): The newly added axis.

Example:

// Create a Red, Amber, Green scale on Sales Volume using slightly muted colors
myChart.addColorAxis("Sales Volume", ["#DA9694", "#FABF8F", "#C4D79B"])

dimple.chart.addCategoryAxis(position, measure) [code] - Helper method overloading the addAxis method. This takes just a position and one or two categoryFields and creates an ordinal axis for the given field(s).

  • position (Required): A string value indicating the positioning of the axis. It must be one of the following values:

    • "x": Creates an axis for determining horizontal positioning. The first x axis created will cross the first y axis at zero. The second will be positioned at the top of the chart. Any further x axes will be hidden but can still be used for positioning.

    • "y": Creates an axis for determining vertical positioning. The first y axis created will cross the first x axis at zero. The second will be positioned at the right of the chart. Any further y axes will be hidden but can still be used for positioning.

  • categoryFields (Required): Either a single string value or an array of string values will be accepted for categoryFields. The following options are accepted values for categoryFields:

    • Single string value: e.g. .addCategoryAxis("x", "Brand"). This string value must be a field name from the data and its distinct values will be used to create an ordinal axis. E.g. "Brand 1", "Brand 2"...

    • Array of two string values: e.g. .addCategoryAxis("x", ["Brand", "Region"]). The string values must be field names from the data creating a clustered axis with the first dimension providing the axis alues and the second providing the clusters within.

  • returns (dimple.axis): The newly added axis.

Example:

// Add an ordinal axis for Brand/Region combinations on x 
myChart.addCategoryAxis("x", ["Brand", "Region"]);
// Add an ordinal axis for Brands on y
myChart.addCategoryAxis("y", "Brand");

dimple.chart.addLegend(x, y, width, height, horizontalAlign, series) [code] - Method for defining legend(s) to be drawn with this chart. A legend takes one or more series and renders the color mappings to a given area in the svg.

  • x (Required): The x co-ordinate of the upper left corner of the charts render area within the SVG object. This should be a positive number and can either be an integer or a string suffixed px to set absolute position in pixels, or it can be suffixed % to use a proportion of svg width.

  • y (Required): The y co-ordinate of the upper left corner of the charts render area within the SVG object. This should be a positive number and can either be an integer or a string suffixed px to set absolute position in pixels, or it can be suffixed % to use a proportion of svg height.

  • width (Required): The width of the legend's plot area within the SVG object. This should be a positive number and can either be an integer or a string suffixed px to set absolute position in pixels, or it can be suffixed % to use a proportion of svg width. Elements in the legend will wrap if their width exceeds this bound.

  • height (Required): The maximum vertical bounds of the legend within the SVG object. This should be a positive number and can either be an integer or a string suffixed px to set absolute position in pixels, or it can be suffixed % to use a proportion of svg height. Any elements which fall outside this bound will not be rendered.

  • horizontalAlign (Optional): Accepted values are "left" and "right", default is "left". The horizontal positioning of the elements within the bounds defined. This does not affect individual legend entries, which will always render with the key on the left and the text on the right. As all elements are sized to the widest, the left edges of each element will always align even if this is set to right.

  • series (Optional): One or more series to include in the legend. By default all chart series will be included, however this allows you to pick particular ones. Accepts either a single dimple.series or an array of dimple.series objects.

Example:

// Add some series
var bars = myChart.addSeries("Brand", dimple.plot.bar);
var lines = myChart.addSeries("Channel", dimple.plot.line);
var bubbles = myChart.addSeries("Region", dimple.plot.bubble);
// Draw a legend for channels and regions only
myChart.addLegend(10, 10, 500, 30, "left", [lines, bubbles])

dimple.chart.addLogAxis(position, measure, logBase) [code] - Helper method overloading the addAxis method. This takes a position and a measure and creates a non-linear numerical axis for the given measure field. By default the axis will be base 10 but if an alternative log base is supplied, that will be used instead. Log axes are excellent for comparing trends of small and large series, however use with care, they can create charts which are misleading at first glance particularly if used with stacked series.

  • position (Required): A string value indicating the positioning of the axis. It must be one of the following values:

    • "x": Creates an axis for determining horizontal positioning. The first x axis created will cross the first y axis at zero. The second will be positioned at the top of the chart. Any further x axes will be hidden but can still be used for positioning.

    • "y": Creates an axis for determining vertical positioning. The first y axis created will cross the first x axis at zero. The second will be positioned at the right of the chart. Any further y axes will be hidden but can still be used for positioning.

    • "z": Creates an axis for determining scale of elements. This axis does not render any visual elements and currently only affects bubble plots.

  • measure (Required): This should be a field name from the data. If the field contains numerical values they will be aggregated, if it contains any non-numeric values the distinct count of values will be used.

  • logBase (Optional): This should be a numerical value. By default this will be 10. It determines the log base used for the axis. The default (10) will create ticks at 10, 100, 1000, 10000 etc.

  • returns (dimple.axis): The newly added axis.

Example:

// Add a vertical log axis of base 10 with ticks 10, 100, 1000 etc.
myChart.addLogAxis("y", "Sales Volume");

dimple.chart.addMeasureAxis(position, measure) [code] - Helper method overloading the addAxis method. This takes just a position and a measure and creates a linear numerical axis for the given measure field.

  • position (Required): A string value indicating the positioning of the axis. It must be one of the following values:

    • "x": Creates an axis for determining horizontal positioning. The first x axis created will cross the first y axis at zero. The second will be positioned at the top of the chart. Any further x axes will be hidden but can still be used for positioning.

    • "y": Creates an axis for determining vertical positioning. The first y axis created will cross the first x axis at zero. The second will be positioned at the right of the chart. Any further y axes will be hidden but can still be used for positioning.

    • "z": Creates an axis for determining scale of elements. This axis does not render any visual elements and currently only affects bubble plots.

  • measure (Required): This should be a field name from the data. If the field contains numerical values they will be aggregated, if it contains any non-numeric values the distinct count of values will be used.

  • returns (dimple.axis): The newly added axis.

Example:

// Add an x axis for summing sales volume
myChart.addMeasureAxis("x", "Sales Volume");
// Add a y axis for counting distinct brands
myChart.addMeasureAxis("y", "Brand");

dimple.chart.addPctAxis(position, measure, categories) [code] - Helper method overloading the addAxis method. This can take just a position and a measure and creates a proportional numerical axis for the given measure field (equivalent to using addMeasureAxis and setting the showPercent property of the axis to true). Alternatively if any category fields are provided in the third parameter it will create a mekko axis.

  • position (Required): A string value indicating the positioning of the axis. It must be one of the following values:

    • "x": Creates an axis for determining horizontal positioning. The first x axis created will cross the first y axis at zero. The second will be positioned at the top of the chart. Any further x axes will be hidden but can still be used for positioning.

    • "y": Creates an axis for determining vertical positioning. The first y axis created will cross the first x axis at zero. The second will be positioned at the right of the chart. Any further y axes will be hidden but can still be used for positioning.

    • "z": Creates an axis for determining scale of elements. This axis does not render any visual elements and currently only affects bubble plots.

  • measure (Required): This should be a field name from the data. If the field contains numerical values they will be aggregated, if it contains any non-numeric values the distinct count of values will be used.

  • categories (Optional): If provided this generates a mekko axis where each category is sized according to its propotion based on the provided measure.

  • returns (dimple.axis): The newly added axis.

Example:

// Create a bar chart showing brand shares of region
myChart.addCategoryAxis("x", "Region");
myChart.addPctAxis("y", "Sales Volume");
myChart.addSeries("Brand", dimple.plot.bar);

dimple.chart.addTimeAxis(position, timeField, inputFormat, outputFormat) [code] - Helper method overloading the addAxis method. This takes a position and a date field to create a time axis. Input and output formats can also be specified.

  • position (Required): A string value indicating the positioning of the axis. It must be one of the following values:

    • "x": Creates an axis for determining horizontal positioning. The first x axis created will cross the first y axis at zero. The second will be positioned at the top of the chart. Any further x axes will be hidden but can still be used for positioning.

    • "y": Creates an axis for determining vertical positioning. The first y axis created will cross the first x axis at zero. The second will be positioned at the right of the chart. Any further y axes will be hidden but can still be used for positioning.

  • timeField (Required): This should be a field name from the data. The field should contain date values, its parsing and display can be controlled with the input and output format.

  • inputFormat (Optional): This should take a string containing the format of the dates in the data source. The format string should be built as described here d3 time formatting. Although this is optional it is highly recommended, if not provided the browser default date parse will be used which is very inconsistent.

  • outputFormat (Optional): This should take a string containing the format of the dates as you wish to display them. The format string should be built as described here d3 time formatting. This is optional but by default the javascript default format is used which is the full ISO standard so you will probably want to specify a format here.

  • returns (dimple.axis): The newly added axis.

To change the number of periods displayed you can use the timePeriod and timeInterval properties of the dimple.axis.

Example:

// Create a bar chart showing brand sales over time, the data is stored in dd/mm/yyyy format and is being
// displayed as "dd yyyy"
myChart.addTimeAxis("x", "Date", "%d/%m/%Y", "%d %Y");
myChart.addPctAxis("y", "Sales Volume");
myChart.addSeries("Brand", dimple.plot.bar);

dimple.chart.addSeries(categoryFields, plotFunction, axes) [code] - Create a new series object and add to the chart's series property, which connects axes together and uses the passed plot function to render on the chart. The order in which series are added will determine the order they are drawn, therefore a series may fall behind any future ones.

  • categoryFields (Optional): The categories by which to disaggregate the series. The following value types are accepted:

    • Null/Undefined: e.g. .addSeries(null, dimple.plot.bar). Setting the categories to null means no disaggregation is applied apart from the axis disaggregation. E.g. this would be used with a category and a measure axis to create a non-stacked, standard bar chart.

    • Single String Value: e.g. .addSeries("Brand", dimple.plot.bar). Splits the series by the given categories values. So this would stack the bars by brand values. If the passed value is not a field name from the data it will be used like the null case above but named with the passed value (meaning it receives a color mapped to this value)

    • Array of String Values: e.g. .addSeries(["Region", "Brand"], dimple.plot.bar). Splits the series by the distinct combinations of the category values. So this would stack the bars by all region/brand combinations. If the passed value is a single element array which is not a field name from the data it will be used like the null case above but named with the passed value (meaning it receives a color mapped to this value)

  • plotFunction (Optional): Defaults to dimple.plot.bubble, this accepts a plot object matching a specific format. If you want to provide a custom plot function object please see the structure defined for the objects in the dimple.plot object. Generally this will be a predefined object:

  • axes (Optional): Accepts the following value types:

    • Null/Undefined: e.g. .addSeries("Brand", dimple.plot.bar) or .addSeries("Brand", dimple.plot.bar, null). Setting the axes to null will mean that the first axis of every type is assigned to the series. This means this parameter can be safely ignored for standard charts with a single x and single y axis.

    • Array of axis objects: Assigns specific axes to different series. This is required where for example multiple y axes are used, see example below.

  • returns (dimple.series): The newly added series.

Example:

// Create a chart of brands by region with bars on one y axis and a line on a second
var x = myChart.addCategoryAxis("x", "Region");
var y1 = myChart.addMeasureAxis("y", "Sales Volume");
var y2 = myChart.addMeasureAxis("y", "Price");
myChart.addSeries("Brand", dimple.plot.bar, [x, y1]);
myChart.addSeries("Brand", dimple.plot.line, [x, y2]);

dimple.chart.assignColor(tag, fill, stroke, opacity) [code] - Associate a specific color with a passed string value. Setting this against a series value will cause any series using that value to color with the given fill and stroke. The only exception to this is where the series is also under the influence of a color axis.

  • tag (Required): A string value against which to assign the passed color. To associate the color with elements on the chart this should be the series value (e.g. if drawing a series of bars for each day of the week, assigning a color to the "Wednesday" tag would cause that item to be specifically colored).

  • fill (Required): A color string with which to fill the series points matching the passed tag. This can be any standard web color string. e.g. "white", "#FFFFFF", "rgb(255, 255, 255)" or "argb(0, 255, 255, 255)" will all render as white.

  • stroke (Optional): By default the value passed for fill will be darkened and assigned to stroke. Accepts a color string with which to draw the outline for series points matching the passed tag. This can be any standard web color string. e.g. "white", "#FFFFFF", "rgb(255, 255, 255)" or "argb(0, 255, 255, 255)" will all render as white.

  • opacity (Optional): By default the color will be opaque however this allows you to configure transparency. Values must range from 0 (fully transparent) to 1 (fully opaque).

  • returns (dimple.color): The newly assigned color.

Example:

// Draw a bar chart and highlight the Coolio brand with a red fill and black outline
var myChart = new dimple.chart(svg, data);
myChart.addCategoryAxis("x", "Region");
myChart.addMeasureAxis("y", "Sales Volume");
myChart.addSeries("Brand", dimple.plot.bar);
myChart.assignColor("Coolio", "red", "black", 1);
myChart.draw();

dimple.chart.draw(duration) [code] - The most essential method in the chart object, without calling this the chart will do nothing. It is a full draw including all axes and series. This will also update a previously drawn chart. Setting the duration will animate the series between the two states for the passed duration. To perform a series of transitions easily you can set a storyboard.

  • duration (Optional): Defaults to 0. This is the number of milliseconds over which to transition from the state of the chart after the last draw and the new state.

  • noDataChange (Optional): Defaults to false. If true this will not recalculate the data. This should only be called once draw has already been called and the data has not changed. It is useful for resizing, where the chart needs to re-render but the data is the same.

  • returns (dimple.chart): The chart parent to allow chaining if wanted.

Example:

// Draw the chart
myChart.draw();
// Peform a data update
myChart.data = getNewData();
// Update the chart to a new state over 2 seconds
myChart.draw(2000);

dimple.chart.getColor(tag) [code] - Associate a color with a passed string value if one has not been assigned, otherwise return a previously assigned color. The colors will be automatically assigned from the defaultColors collection.

  • tag (Required): A string value against which to retrieve a color. Within the lifetime of the chart object, this will always return the same color from the defaultColors for the same tag (unless you override the assigned color with assignColor). It will not necessarily return the same color across different chart lives, as the color is assigned to the next unused color during the first request.

  • returns (dimple.color): The newly allocated color.

Example:

// Get the fill color for the Coolio brand
console.log(mychart.getColor("Coolio").fill);

dimple.chart.setBounds(x, y, width, height) [code] - Set the size of the plot within the svg. Assign the bounds of the chart plot area within the svg. Values may either be pixels or percent of the relevant svg bound (i.e. x and width are percentages of svg width, the others are of height). Please note, this is the bounds of the plot area, not all chart components. Some chart elements (such as axis text) will surround the plot area.

  • x (Required): The x co-ordinate of the chart's plot area within the SVG object. This should be a positive number and can either be an integer or a string suffixed px to set absolute position in pixels, or it can be suffixed % to use a proportion of svg width. Values may also be mixed in a comma separated list. e.g. "10%,20px" will set the x co-ordinate to 10% of the svg width + 20 pixels.

  • y (Required): The y co-ordinate of the chart's plot area within the SVG object. This should be a positive number and can either be an integer or a string suffixed px to set absolute position in pixels, or it can be suffixed % to use a proportion of svg height. Values may also be mixed in a comma separated list. e.g. "10%,20px" will set the y co-ordinate to 10% of the svg height + 20 pixels.

  • width (Required): The width of the chart's plot area within the SVG object. This should be a positive number and can either be an integer or a string suffixed px to set absolute position in pixels, or it can be suffixed % to use a proportion of svg width. Values may also be mixed in a comma separated list. e.g. "10%,20px" will set the width to 10% of the svg width + 20 pixels.

  • height (Required): The height of the chart's plot area within the SVG object. This should be a positive number and can either be an integer or a string suffixed px to set absolute position in pixels, or it can be suffixed % to use a proportion of svg height. Values may also be mixed in a comma separated list. e.g. "10%,20px" will set the height to 10% of the svg height + 20 pixels.

  • returns (dimple.chart): The chart parent to allow chaining if wanted.

Example:

// Draw the chart a quarter the size of the svg 50px from the top and 80px 
// from the left of the SVG origin - the x and y are only done with different
// styles to show possibilities, both result in absolute pixel offsets.
myChart.setBounds(80, "50px", "50%", "50%");

dimple.chart.setMargins(left, top, right, bottom) [code] - Set the margins around the plot area from the edge of the SVG. This replaces anything done via setBounds and offers an alternative which makes it easier to allow the chart plot area to fill remaining space.

  • left (Required): The x co-ordinate of the chart's plot area within the SVG object. This should be a positive number and can either be an integer or a string suffixed px to set absolute position in pixels, or it can be suffixed % to use a proportion of svg width. Values may also be mixed in a comma separated list. e.g. "10%,20px" will set the left margin to 10% of the svg width + 20 pixels.

  • top (Required): The y co-ordinate of the chart's plot area within the SVG object. This should be a positive number and can either be an integer or a string suffixed px to set absolute position in pixels, or it can be suffixed % to use a proportion of svg height. Values may also be mixed in a comma separated list. e.g. "10%,20px" will set the top margin to 10% of the svg height+ 20 pixels.

  • right (Required): The right margin of the plot area. The width of the plot area will be calculated as SVG width - left - right. This should be a positive number and can either be an integer or a string suffixed px to set absolute position in pixels, or it can be suffixed % to use a proportion of svg width. Values may also be mixed in a comma separated list. e.g. "10%,20px" will set the right margin to 10% of the svg width + 20 pixels.

  • bottom (Required): The bottom margin of the plot area. The height of the plot area will be calculated as SVG height - top - bottom. This should be a positive number and can either be an integer or a string suffixed px to set absolute position in pixels, or it can be suffixed % to use a proportion of svg height. Values may also be mixed in a comma separated list. e.g. "10%,20px" will set the bottom margin to 10% of the svg height + 20 pixels.

  • returns (dimple.chart): The chart parent to allow chaining if wanted.

Example:

// Draw the chart whose plot area will fill the centre of the svg with a 100px margin all around
myChart.setMargin(100, 100, 100, 100);

dimple.chart.setStoryboard(categoryFields, tickHandler) [code] - Creates a dimple.storyboard object which will automatically animate the chart across the values in a given dimension. The tickHandler parameter will take an event handler which is fired everytime the frame changes.

  • categoryFields (Required): The categories over whose values the chart will be animated. For example passing a date field into this will render the chart for each date in the data set. The properties of the animation can be controlled via the dimple.storyboard object.

  • tickHandler (Optional): A function to be called every time the chart updates. A single parameter will be passed to the function containing a dimple.eventArgs object.

  • returns (dimple.storyboard: The newly added storyboard object.

Example:

// Animate a chart over the date field and write the current frame value to the console on update
myChart.setStoryboard("Date", function (e) {
	console.log(e.frameValue);	
});
Add a custom footer
Add a custom sidebar

Clone this wiki locally