Using colors and themes

Surrounding website color

A chart is always painted on a rectangular white frame, the “canvas”. If the chart is colored and has rounded corners there is always a piece of the canvas visible. This is no problem as long as the background-color of the website is white. But if your website has a colored background there is a white rectangular frame visible around the chart. The following figure illustrates the issue.

In order to integrate the chart seamlessly into the surrounding website, the canvas background color can be set to the same color as the website background. This is done using the setColorVariable( String name, String colorString ) function of the builder.

new ac.ACLineChartBuilder()
    // ...
    .setColorVariable("SURROUNDING_WEBSITE_COLOR", "rgba(204, 255, 51, 1.0)" )
    // ...

Colors in HTML are usually indicated in hex notation like this: #CCFF33.

setColorVariable() expects the colors as a color string either in hex (e.g. #FFFFFF or #fff), RGB (e.g. 120, 130, 150) or RGBA notation (e.g. 255, 0, 0, 1.0) with decimal or percentage numbers. The alpha value (A of the RGBA notation) describes the transparency level. Just leave this at “1.0” for full visibility. You can even mix absolute and percentage values for the RGB or RGBA notation, e.g. (100, 100%, 20, 1.0). setColorVariable() will still be able to understand and calculate the colors correctly.

Styles and Color: Theme and ColorScheme

A overview of available themes and colorSchemes can be found here.

The “look and feel” of the chart is determined by the two xml-files:

  • the Theme
  • the ColorScheme

The theme defines the general layout of a chart (line width, frame style, fonts, background style, color intensity etc.). The colorScheme defines the colors displayed in the chart.

A theme is set using the builder's setTheme( theme ) command. The color-scheme is set with the builder's setColorScheme( colorScheme ) command.

new ac.ACLineChartBuilder()
    // ...
    .setTheme("theme_standard_beveled.xml")
    .setColorScheme("color_scheme_orange.xml")
    // ...

By combining color scheme and theme, a lot of different layouts can be achieved.

See also the complete documentation of all existing themes and color schemes

Preferred ColorSchemes

In most cases you can combine themes and colorSchemes at will. As always, there are some combinations that look slightly better or slightly worse. When you only define a theme without setting a colorScheme, arcadiaCharts selects default combinations which provide the best results for the selected chart type and theme.

The preferred chart type, theme and colorScheme combinations are:

Theme Line chart Bar Chart Pie chart
theme_standard_business.xml color_scheme_darkblue.xml color_scheme_darkblue.xml color_scheme_darkblue.xml
theme_standard_classic.xml color_scheme_sand.xml color_scheme_blue.xml color_scheme_brown.xml
theme_standard_colorsphere.xml color_scheme_darkblue.xml color_scheme_darkblue.xml color_scheme_darkblue.xml
theme_standard_glazed.xml color_scheme_darkblue.xml color_scheme_darkblue.xml color_scheme_darkblue.xml
theme_standard_pastelshade.xml color_scheme_sand.xml color_scheme_sand.xml color_scheme_sand.xml
theme_standard_signet.xml color_scheme_green.xml color_scheme_brown.xml color_scheme_darkblue.xml
theme_standard_smokedglass.xml color_scheme_darkblue.xml color_scheme_darkblue.xml color_scheme_darkblue.xml
theme_standard_velvet.xml color_scheme_blue.xml color_scheme_brown.xml color_scheme_sand.xml

Built-in vs. external themes

As you might have noticed in the example code above, no path has been specified for the theme and colorScheme xml-files. This is due to the fact that all standard themes and colorSchemes exist twice:

  1. integrated into the library code as “built-in” theme and “built-in” colorScheme
  2. as external files on your file system in the directory /arcadiacharts/themes if you downloaded the complete distribution of the arcadiaCharts library.

If you specify only the name of a theme or colorScheme (like theme_standard_plain.xml) the internal or built-in version of a theme or colorScheme will be used. If you specify the complete path (like arcadiacharts/themes/theme_standard_plain.xml) the external version of the theme or colorScheme will be used.

For better response times use the internal version of a theme or colorScheme.

If you need to modify one of the theme or colorScheme files use the external version.

Enforce use of a built-in or external theme or colorScheme

You can enforce the use of either a built-in or an external theme / colorScheme by adding an additional parameter to the builder-command.

setTheme( theme, ac.Origin.EXTERNAL )
setColorScheme( colorScheme, ac.Origin.INTERNAL )

In the example below the use of the external theme and colorScheme is enforced. Please note that the theme and colorScheme xml-files have to exist in the designated directory (the root directory in this example).

new ac.ACLineChartBuilder()
    // ...
    .setTheme("theme_standard_plain.xml", ac.Origin.EXTERNAL)
    .setColorScheme("color_scheme_blue.xml", ac.Origin.EXTERNAL)
    // ...

Changing the color palette

arcadiaCharts supports easily memorizable color names instead of RGB, RGBA of HEX values. These are stored as variables inside the palette.xml file. Color names provided by the palette file can be used in your colorScheme

<?xml version="1.0" encoding="UTF-8"?>
<palette>
	<variables>
		<variable type="color" name="BLACK" value="rgba( 0, 0, 0, 1 )"/>
		<variable type="color" name="GRAY" value="rgba( 128, 128, 128, 1 )"/>
		<variable type="color" name="GREY" value="rgba( 128, 128, 128, 1 )"/>
		<variable type="color" name="MAROON" value="rgba( 128, 0, 0, 1 )"/>
		(...)
	<variables>
<palette>

The default palette.xml file contains all color names defined by the W3C in CSS Color Module Level 3. These colors can be used in your colorSchemes You can extend or replace the palette file as you wish.

To change color names you can simply edit the palette file and add or remove lines as you like. Palettes and colorSchemes are closely connected, so check your colorScheme files to make sure that they don´t use any color names you removed. To add an own palette file and colorScheme use the setPalette(palette, colorScheme [,paletteOrigin, colorSchemeOrigin] ) method

	.setPalette("myPalette.xml", "myColorScheme.xml" ,ac.Origin.EXTERNAL, ac.Origin.EXTERNAL)

Override theme variables in your application

While we recommend separating presentation and content, it may be necessary to override theme variables from your chart application. This is possible with setStyleVariable

You need to define your style to be able to use it:

var myTitleStyle = ac.Util.createHashMap( [
    [ "fontWeight", "bold" ],
    [ "color", "#ff0000"],
    [ "fontSize", "26px"]
] );

Then you can simply overwrite any theme setting with your style

.setStyleVariable( "TitleElement", myTitleStyle )

Warning: Changing theme variables in your application can lead to unpredictable results

Please be careful with replacing any theme variables within the application. It violates the separation of presentation and content and it can result in unpredictable consequences when you decide to use another theme file. This can lead to frustrating searches for the reason of unwanted and unplausible behaviour of your chart library.