Dojo Charting: Dive Into Theming

By on November 9, 2012 2:00 am

The previous installment of the Dive Into Dojo series shows how easy it is to Dive Into Dojo Charting. It comes with dozens of stylish themes you can effortlessly plug into any chart. But what if you want your charts to match your website’s design or business’ branding? No worries: Dojo’s charting library allows you to create custom themes!

dojo-chart-creation

Setting Up Your Namespace

All of Dojo’s charting themes live with in the dojox/charting/themes namespace. As is the best practice with custom class creation with Dojo, we’ll create our own namespace for our custom chart themes. Let’s give our custom theme the /app/charting/themes/ namespace. /app is a good namespace for most Dojo projects, and I’ve chosen to mimic the path DojoX uses for themes.

/* create the theme files in the app namespace */
/app/charting/themes/SitePen.js
/app/charting/themes/SitePenFTW.js

Quick Peek at a Simple Theme

The levels of complexity within Dojo themes can vary greatly depending on your desire to use simply defined colors or implement advanced features like gradations, markers, scrolling, panning, and chart events. Let’s start by looking at a basic theme called Dollar:

define([
	"../SimpleTheme",
	"./common"
], function(SimpleTheme, themes){

	themes.Dollar = new SimpleTheme({
		colors: [
			"#A4CE67",
			"#739363",
			"#6B824A",
			"#343434",
			"#636563"
		]
	});
	return themes.Dollar;
});

Dollar illustrates how simple creating a theme can be; provide a list of colors and you’ve created a custom theme!

Basic Custom Theme: SitePen

Now that we’ve seen how simple it is to make a basic theme, we can easily create a custom SitePen theme base on the SitePen logo colors:

define([
	"dojox/charting/SimpleTheme",
	"dojox/charting/themes/common"
], function(SimpleTheme, themes){
	
	themes.SitePen = new SimpleTheme({
		colors: [
			"#A4CE67",
			"#739363",
			"#6B824A",
			"#343434",
			"#636563"
		]
	});
	return themes.SitePen;
});

Your colors array can have any number of colors. Colors are repeated in sequence within the chart, if necessary. Check out a few different charts using the new SitePen theme:

Basic Custom Chart Theme

Advanced Chart Theming

With the basic SitePen chart theme, we simply defined a series of colors we’d like used in the chart. With advanced chart theming, you can customize everything from default plotareas, axis, series, and marker colors, fonts, and strokes. The amount of control you can have over your charts by creating your own theme is truly incredible. Using Tom Trenka’s “Tom” theme as a template, let’s make an advanced customization of the SitePen theme in /app/charting/themes/SitePenFTW:

define([
	"dojox/charting/Theme",
	"dojox/charting/themes/common",
	"dojox/gfx/gradutils"
], function(Theme, themes){

	var gradient = Theme.generateGradient;

    /* fill settings for gradation */
    defaultFill = {type: "linear", space: "shape", x1: 0, y1: 0, x2: 0, y2: 100};

	/* create theme */
	themes.SitePenFTW = new Theme({

		/* customize the chart wrapper */
		chart: {
			fill: "#333",
			stroke: { color: "#333" },
			pageStyle: {
				backgroundColor: "#000",
				color: "#fff"
			}
		},

		/* plotarea definition */
		plotarea: { fill: "#000" },

		/* axis definition */
		axis:{
			stroke: { // the axis itself
				color: "#fff",
				width: 1
			},
			tick: { // used as a foundation for all ticks
				color: "#fff",
				position: "center",
				font: "normal normal normal 7pt Helvetica, Arial, sans-serif",  // labels on axis
				fontColor: "#fff" // color of labels
			}
		},

		/* series definition */
		series: {
			stroke: { width: 2.5, color: "#fff" },
			outline: null,
			font: "normal normal normal 8pt Helvetica, Arial, sans-serif",
			fontColor: "#fff"
		},

		/* marker definition */
		marker: {
			stroke: { width: 1.25, color: "#fff" },
			outline: { width: 1.25, color: "#fff" },
			font: "normal normal normal 8pt Helvetica, Arial, sans-serif",
			fontColor: "#fff"
		},

		/* series theme with gradations! */
		//light => dark
		//defaultFill object holds all of our gradation settings
		seriesThemes: [
			{ fill: gradient(defaultFill, "#fff", "#f2f2f2") },
			{ fill: gradient(defaultFill, "#d5ecf3", "#bed3d9") },
			{ fill: gradient(defaultFill, "#9ff275", "#7fc25d") },
			{ fill: gradient(defaultFill, "#81ee3b", "#60b32b") },
			{ fill: gradient(defaultFill, "#4dcff4", "#277085") },
			{ fill: gradient(defaultFill, "#666", "#333") }
		],

		/* marker theme */
		markerThemes: [
			{fill: "#bf9e0a", stroke: {color: "#ecc20c"}},
			{fill: "#73b086", stroke: {color: "#95e5af"}},
			{fill: "#216071", stroke: {color: "#277084"}},
			{fill: "#c7212d", stroke: {color: "#ed2835"}},
			{fill: "#87ab41", stroke: {color: "#b6e557"}}
		]
	});

	return themes.SitePenFTW;
});

You wont need to define every property created above; if a given property isn’t defined, a default value will be used. On the flip side, you may also override each and any of these settings when creating chart instances. This custom theme acts as a middle-ground between chart defaults and chart instance settings.

Take a look at some of our enhanced theme examples:

Advanced Custom Chart Theme

Using Gradients

The advanced SitePen theme we created above made use of gradients thanks to the dojox/gfx/gradutils class and the generateGradient() method in dojox/charting/Theme. Gradation instances can be passed to any property that desires a color (usually the fill property.) The signature of the generateGradient method is:

generateGradient: function(
	fillPattern, 
	colorFrom, 
	colorTo
}

The fill pattern holds the gradient settings:

{
	type: "linear",		//or "radial"
	space: "shape", 
	x1: 0, 			//gradation direction
	y1: 0, 			//gradation direction
	x2: 0, 			//gradation direction
	y2: 100			//gradation direction
}

Feel free to experiment with the gradation settings to find just the right gradient for you. Or use one of the dozens of available Themes. While Dojo’s charting library comes with a variety of stylish themes, don’t feel as though you need to choose an existing theme; take a few minutes to create an eye-catching custom theme to match your branding!

Further Reading

Comments