A SimpleTheme or Theme is a pre-defined object, primarily JSON-based, that makes up the definitions to style a chart.
While you can set up style definitions on a chart directly (usually through the various add methods on a dojox.charting.Chart object), a Theme simplifies this manual setup by allowing you to pre-define all of the various visual parameters of each element in a chart.
Most of the properties of a Theme are straight-forward; if something is line-based (such as an axis or the ticks on an axis), they will be defined using basic stroke parameters. Likewise, if an element is primarily block-based (such as the background of a chart), it will be primarily fill-based.
In addition (for convenience), a Theme definition does not have to contain the entire JSON-based structure. Each theme is built on top of a default theme (which serves as the basis for the theme "GreySkies"), and is mixed into the default theme object. This allows you to create a theme based, say, solely on colors for data series.
Defining a new theme is relatively easy; see any of the themes in dojox.charting.themes for examples on how to define your own.
When you set a theme on a chart, the theme itself is deep-cloned. This means that you cannot alter the theme itself after setting the theme value on a chart, and expect it to change your chart. If you are looking to make alterations to a theme for a chart, the suggestion would be to create your own theme, based on the one you want to use, that makes those alterations before it is applied to a chart.
Finally, a Theme contains a number of functions to facilitate rendering operations on a chart--the main helper of which is the ~next~ method, in which a chart asks for the information for the next data series to be rendered.
A note on colors: A theme palette is usually comprised of 5 different color definitions, and no more. If you have a need to render a chart with more than 5 data elements, you can simply "push" new color definitions into the theme's .color array. Make sure that you do that with the actual theme object from a Chart, and not in the theme itself (i.e. either do that before using .setTheme on a chart).
| Parameter | Type | Description |
|---|---|---|
| kwArgs | undefined |
See the dojox/charting/SimpleTheme reference documentation for more information.
The default theme (and structure) looks like so:
// all objects are structs used directly in dojox.gfx
chart:{
stroke: null,
fill: "white",
pageStyle: null // suggested page style as an object suitable for dojo.style()
},
plotarea:{
stroke: null,
fill: "white"
},
axis:{
stroke: { // the axis itself
color: "#333",
width: 1
},
tick: { // used as a foundation for all ticks
color: "#666",
position: "center",
font: "normal normal normal 7pt Tahoma", // labels on axis
fontColor: "#333" // color of labels
},
majorTick: { // major ticks on axis, and used for major gridlines
width: 1,
length: 6
},
minorTick: { // minor ticks on axis, and used for minor gridlines
width: 0.8,
length: 3
},
microTick: { // minor ticks on axis, and used for minor gridlines
width: 0.5,
length: 1
},
title: {
gap: 15,
font: "normal normal normal 11pt Tahoma", // title font
fontColor: "#333", // title font color
orientation: "axis" // "axis": facing the axis, "away": facing away
}
},
series: {
stroke: {width: 1.5, color: "#333"}, // line
outline: {width: 0.1, color: "#ccc"}, // outline
//shadow: {dx: 1, dy: 1, width: 2, color: [0, 0, 0, 0.3]},
shadow: null, // no shadow
//filter: dojox/gfx/filters.createFilter(),
filter: null, // no filter, to use a filter you must use gfx SVG render and require dojox/gfx/svgext
fill: "#ccc", // fill, if appropriate
font: "normal normal normal 8pt Tahoma", // if there's a label
fontColor: "#000" // color of labels
labelWiring: {width: 1, color: "#ccc"}, // connect marker and target data item(slice, column, bar...)
},
marker: { // any markers on a series
symbol: "m-3,3 l3,-6 3,6 z", // symbol
stroke: {width: 1.5, color: "#333"}, // stroke
outline: {width: 0.1, color: "#ccc"}, // outline
shadow: null, // no shadow
fill: "#ccc", // fill if needed
font: "normal normal normal 8pt Tahoma", // label
fontColor: "#000"
},
grid: { // grid, when not present axis tick strokes are used instead
majorLine: { // major grid line
color: "#666",
width: 1,
length: 6
},
minorLine: { // minor grid line
color: "#666",
width: 0.8,
length: 3
},
fill: "grey", // every other stripe
alternateFill: "grey" // alternate stripe
},
indicator: {
lineStroke: {width: 1.5, color: "#333"}, // line
lineOutline: {width: 0.1, color: "#ccc"}, // line outline
lineShadow: null, // no line shadow
lineFill: null, // fill between lines for dual indicators
stroke: {width: 1.5, color: "#333"}, // label background stroke
outline: {width: 0.1, color: "#ccc"}, // label background outline
shadow: null, // no label background shadow
fill: "#ccc", // label background fill
radius: 3, // radius of the label background
font: "normal normal normal 10pt Tahoma", // label font
fontColor: "#000" // label color
markerFill: "#ccc", // marker fill
markerSymbol: "m-3,0 c0,-4 6,-4 6,0 m-6,0 c0,4 6,4 6,0", // marker symbol
markerStroke: {width: 1.5, color: "#333"}, // marker stroke
markerOutline: {width: 0.1, color: "#ccc"}, // marker outline
markerShadow: null, // no marker shadow
}
Defining a new theme is pretty simple:
var Grasslands = new SimpleTheme({
colors: [ "#70803a", "#dde574", "#788062", "#b1cc5d", "#eff2c2" ]
});
myChart.setTheme(Grasslands);
Add a custom marker to this theme.
| Parameter | Type | Description |
|---|---|---|
| name | String | |
| segment | String |
myTheme.addMarker("Ellipse", foo);
Add a mixin object to the passed theme and process.
| Parameter | Type | Description |
|---|---|---|
| theme | dojox/charting/SimpleTheme | The theme to mixin to. |
| elementType | String | The type of element in question. Can be "line", "bar" or "circle" |
| mixin | Object | Array | The object or objects to mix into the theme. |
| doPost | Boolean | If true, run the new theme through the post-processor. |
The new theme.
Clone the current theme.
The cloned theme; any alterations made will not affect the original.
Calculates and merges tick parameters.
| Parameter | Type | Description |
|---|---|---|
| name | String | Tick name, can be "major", "minor", or "micro". |
| mixin | Object |
Optional Optional object to mix in to the tick. |
Get the next color or series theme.
| Parameter | Type | Description |
|---|---|---|
| elementType | String |
Optional An optional element type (for use with series themes) |
| mixin | Object |
Optional An optional object to mix into the theme. |
| doPost | Boolean |
Optional A flag to post-process the results. |
An object of the structure { series, marker, symbol }
Process any post-shape fills.
| Parameter | Type | Description |
|---|---|---|
| theme | dojox/charting/SimpleTheme | The theme to post process with. |
| elementType | String | The type of element being filled. Can be "bar" or "circle". |
The post-processed theme.
Set all the markers of this theme at once. obj should be a dictionary of keys and path segments.
| Parameter | Type | Description |
|---|---|---|
| obj | Object |
myTheme.setMarkers({ "CIRCLE": foo });