Introduction to theme files editing

About theme files

The theme file is an XML file which you can edit to change the look and the layout of the chart. Think of your chart code as defining the functionality of your chart, while your theme file defines its layout.

ArcadiaCharts provides many ways of customizing the graphical appearance of the chart. Detailed informations about modifying particular elements can be found within the corresponding pages:

How to use a theme file:

  1. To select a theme file, use the function setTheme(themeFilename) in the chart code to tell your application where your custom theme lies. For more details, see the section below on 'Selecting your theme file'.
  2. However, if you prefer to keep things simple you do not have to define a theme file. Instead, you can use one of the so-called standard themes. These are pre-designed themes included in the distribution which will fit and look good in most chart situations. For information on how to use standard themes, please read the section below on standard themes. (link)

How to locate the theme file

Generally, your chart code has to select which theme file should be used. In a typical chart, this would be done in the following manner:

new ac.ACBarChartBuilder()
    // ...
    .setTheme("arcadiacharts/themes/theme_barchart_2d_sales_chartoptions.xml")
    .build()
    .addToDom('chart');

The themes contained in the ArcadiaCharts distribution are contained in the arcadiacharts/themes subdirectory. This directory contains both the external standard themes (theme_standard_XYZ.xml) as well as the themes for the ArcadiaCharts showcases
(e.g. theme_linechart_2d_econ_chartoptions.html).

Structure of the theme file

The theme file is an XML file which contains a section in which you can define various variable settings for the chart (for example the font sizes used in the charts, the position of the footer - inside or outside the chart - or the path to images used in the chart) and a section called 'chart options' which defines more complex graphical options (for example the graphical appearance of the chart elements, paddings and sizes of the elements). Generally, the theme file is structured as follows:

<?xml version="1.0" encoding="UTF-8"?>
<theme>
  <variables>
    <!-- Theme variables may be defined within the <variables> part. -->
    <variable name="VALUE_BAR_SIZE" type="size" value="0.6" />
    ...
    <!-- "Style" variables define fonts (font name, size etc.) of particular chart elements. -->
    <variable type="style" name="TitleElement">
      <fontFamily>Bebas</fontFamily>
      <color>$WHITE</color>
    </variable>
    ...
  </variables>
  <!-- The following section defines chart options which define the layout and look of the chart. -->
  <chartOptions>
    <legend>
      <background>
        <style>TRANSPARENT</style>
      </background>
    </legend>
  </chartOptions>
</theme>

Standard themes vs. individual themes

You can edit a theme in one of the following ways:

  1. Either you create a customized, individual theme by creating an .xml file with the chart options and variables described above. (Another possibility is to use one of the existing showcase themes and modify them to your needs. This allows you to develop your personal theme step by step from one which already works well.)
  2. The more convenient way, however, is to use the “standard themes” built into ArcadiaCharts, theme files which will work in all situations and provide you with a pleasing chart layout design. These standard themes can be combined with one of the pre-defined color sets included in the distribution to produce a wide variety of charts.
  3. If you specify no theme at all for the chart, one of the standard themes will be used.

The available standard themes are listed on the line chart, bar chart and pie chart pages respectively. As always, they are loaded using the setTheme(themeName) function.

Standard themes can be combined with all available color schemes.
If you want to modify one the standard themes included in the ArcadiaCharts distribution, please see the section below “Standard themes: Built-in themes vs external themes”.

Changing the theme options at the chart code level (i.e. not in the theme file)

Generally, layout options should be changed in the theme file, in order to separate the chart's layout from the chart's functionality (which is contained in the (Javascript) chart code).
However, sometimes it may be more convenient to quickly change a theme variable directly within your chart code. In such a situation, you can access a theme variable from the chart (Javascript) code in the following way:

new ac.ACBarChartBuilder()
    // ...
    .setSizeVariable(variableName, variableValue)
    // ...
For example:
To set the width of the legend to 500 pixels:
new ac.ACBarChartBuilder()
    // ...
    .setSizeVariable("LEGEND_WIDTH","500")
    // ...
To set the size of the axis to range between 10 and 20 pixels with a default of 20% chart width:
new ac.ACBarChartBuilder()
    // ...
    .setSizeVariable("AXIS_SIZE", "min: 10; default: 0.2 * $chartWidth; max: 20")
    // ...


Color variables can be changed from the code with

new ac.ACBarChartBuilder()
    // ...
    .setColorVariable(variableName, String colorString)
    // ...
For example:
To set the color of the background shadow to a RGB color value of (12, 34, 56) with 100% opacity:
new ac.ACBarChartBuilder()
    // ...
    .setColorVariable("BACKGROUND_SHADOW_COLOR", "rgba(12, 34, 56, 1.0)" )
    // ...

String variables (e.g. LEGEND_VERTICAL_ALIGNMENT) can be changed with setStringVariable( “LEGEND_VERTICAL_ALIGNMENT” , “100” ).

Priority of theme variables changed within the chart code vs. the theme file

If a theme setting is changed both in the chart code file and the theme file, the following priority rules apply:

  1. Theme variables (those contained in the <variables> section of the theme file) take priority over theme chart options (those contained in the <chartOptions> section)
  2. Theme variables defined within the chart code (i.e., not in the theme file) take priority over theme properties defined in the theme file

More advanced theme options

The theme can be customized even more: If you need to, you can completely define the way any chart element is rendered. (You will find some examples of these functionalities in the showcase themes, under the headings of <spawnList> and <RenderInstructionList>.) If you are interested in these more advanced modifications, please contact us and we can assist you with your needs or provide additional documentation.