Creating New Themes

Prerequisites

• Introduction to Themes
• Applying Themes
• Basics of Theme Definition

FusionCharts Suite XT is shipped with the following three predefined themes:

• zune
• ocean
• carbon

You can choose a theme depending on your aesthetic requirements for the charts, gauges, and maps in your application. Additionally, FusionCharts Suite XT gives you the option of modifying existing themes or creating entirely new ones, if your requirements differ from what is already there.

This article describes how you can create and register new themes using the FusionCharts API.

Creating and Registering a New Theme

Assume that you have to create a theme (call this theme mySampleTheme) that should include the properties listed in the table below:

Given below is a step-wise procedure for creating this theme:

Step 1:

In a text editor, create a new text file. Name this file mySampleTheme.js.
Save it in the js/themes folder.

Step 2:

Determine the structure of the theme by mapping properties to tiers.
A theme is structured using tiers that are used to specify the scope of application of the properties.
The table below maps the properties in the theme definition to the corresponding tier in the theme structure:

Step 3:

Determine the structure for each tier by mapping the attributes to be defined with the objects they belong to.
Based on the properties mentioned in the first table (the one that outlines the requirements for the theme sample), the table below lists the attributes that will be used to fulfil each requirement and the objects that the attributes belong to.

Refer the FusionCharts Suite XT Chart Attributes page for a complete understanding of the objects and attributes used to configure the charts, gauges, and maps.

Step 3:

Add the JavaScript code for the theme in the theme file.
Based on the property-tier-attribute-object mapping shown above, write the JavaScript code for your theme in the mySampleTheme.js file created in Step 1.

Given below is the JS code for the sample theme:

//The `FusionCharts.register()` API is used to register the new theme in the FusionCharts core.
FusionCharts.register(‘theme’, {
	name: ‘mySampleTheme’,
	theme: {
		base: {
			chart: {
				paletteColors: '#0075c2,#1aaf5d,#f2c500',
				subCaption: ‘Harry’s SuperMart !important’, //The !important directive is used to ensure that the sub-caption cannot be overriden in the theme definition or in the chart data.
				captionFontSize: ‘14’
				subCaptionFontSize: ‘12’
				captionFontBold: ‘1’,
				subCaptionFontBold: ‘0’,
				showHoverEffect: ‘1’,
				placeValuesInside: ‘0’
				},
			trendlines: [{
				color: ‘#FF000’,
				thickness: ‘3’,
				dashed: ‘1’,
				dashLen: ‘4’,
				dashGap: ‘2’
				}]
			},
		column2d: {
			dataset: {
						data: function(dataObj) {
                        	color: (Number(dataObj.value) < 0 ? "#3333FF" : "#CC0000"),
                    }
                }
			}
		bubble: {
			chart: {
				drawQuadrant: ‘1’,
				quadrantLineColor: ‘3’,
				quadrantLineThickness: ‘1’,
				quadrantLineAlpha: ‘4’,
				},
			dataset: [{
				regressionLineColor: ‘#123456’,
				regressionLineThickness: ‘3’,
				regressionLineAlpha: ‘70’  
			}]
		}
		pie2d: {
			chart: {
				showPercentInToolTip: ‘1’,
				enableSmartLabels: ‘1’
				}
			},
		zoomline: {
			chart: {
			anchorMinRenderDistance : ‘20’				
				}
			},		
		gantt: {
			processes: [{
				headerFont: ‘Arial’,
				headerFontSize: ‘16’,
				headerFontColor: ‘#321ABC’,
				headerIsBold: ‘1’,
				headerIsUnderline: ‘1’,
				headerAlign: ‘left’,
				headerVAlign: ‘bottom’
				}]
			},      
		geo: {
			chart: {
				showLabels: ‘1’,
				useSNameInLabels: ‘1’,
				useSNameInToolTip: ‘0’,
				entityFillHoverColor: ‘#9A9A9A’,
				entityFillHoverAlpha: ‘60’,
				markerFillHoverColor: ‘#8AE65C’,
				markerFillHoverAlpha: ‘60’,
				}
			marker: {
				connector: {
					thickness: ‘4’,
					color: ‘#336699’,
					alpha: ‘60’,
					dashed: ‘1’,
					dashLen: ‘4’,
					dashGap: ‘2’
				}
			}
		}
	}
});

Step 4:

Use your theme!
You can now apply your new theme to the charts, gauges, and maps in your application using either the theme attribute of the chart object or the setChartAttribute() method of the FusionCharts API.

Creating and Registering Multiple Themes

If you need to create multiple new themes for your application, the advisable approach is to specify all theme definitions in the same file. That way, you will have to include only one .js file in your application, instead of multiple files. The theme name, as the value of the theme attribute or as the parameter of the setChartAttribute() method, can then change depending on your requirement.

A sample of the code that goes into the JavaScript file for creating multiple themes together is shown below:

var myTheme1 = {
         	name: ‘my-theme-1’,
			theme: {...} // Theme JSON
      	},
    myTheme2 = {
          	name: ‘my-theme-1’,
			theme: {...} // Theme JSON
      	},
    myTheme3 = {
          	name: ‘my-theme-1’,
			theme: {...} // Theme JSON
      };

To register all the themes in one go, use the FusionCharts.register() API as shown below:

FusionCharts.register('theme', [myTheme1, myTheme2, myTheme3]);

An alternate way of creating and registering multiple themes is shown below:

FusionCharts.register('theme', [
	{name: ‘my-theme-1’, theme: {...}}, 
	{name: ‘my-theme-2’, theme: {...}}, 
	{name: ‘my-theme-3’, theme: {...}}
]);

Including Escape Characters in Theme Definition

When modifying theme definitions, it is important for you to understand the concept of escape characters. Read the example below to understand what escape characters are and why they are needed.

Assume that the sub-caption of your chart is Harry’s SuperMart .

How do you write this in the theme definition?

subCaption: ‘Harry’s SuperMart’

is the code line that you would include in your theme definition.

However, a glitch that may go unnoticed here is the use of three single quotes, which the browser may not exactly interpret the way you want it to.

In this example, the single quote after ‘y’ may be interpreted as the closing quote, ignoring the rest of the string and the sub-caption will not be rendered the way you want it to.

Escape characters are used to solve this problem.

For the quotation mark after ‘y’ to be interpreted as an apostrophe, this is how you write the code line in your theme definition:

subCaption: ‘Harry\’s SuperMart’

\’ is an escape character that is used to tell the browser that the quotation mark is to be used as an apostrophe; this is called character quoting—using escape characters to represent characters that would otherwise have an incorrect interpretation.

The table below shows the other escape characters that can be used: