jQuery Common - Appearance Customization

To define an appearance for your widget, you can use themes and palettes. Themes determine the overall look and feel of a widget by painting its visual elements. Palettes are sets of colors for painting chart series or points. The documents in this section explain these concepts in greater detail.

The DevExtreme data visualization widgets consist of many elements, each of which has options that determine appearance. The default values of appearance options are united in a theme.

DevExtreme provides Android, iOS and Windows themes as well as several generic themes. Generic themes are platform-agnostic and vary in color scheme.

Each DevExtreme visualization widget has a theme configuration option that allows you to set a theme. It is also convenient to apply a theme for the entire page with several DevExtreme widgets. To do this, use the DevExpress.viz.currentTheme method passing the name of the required theme as a parameter.

DevExpress.viz.currentTheme('android5.light');

If you are creating a cross-platform application, you can determine on which platform the page is currently running. Use the DevExpress.devices.current() method. The method's return value can be used for auto-specifying the theme.

DevExpress.viz.currentTheme(DevExpress.devices.current());

In addition to the current device, you can specify the required color scheme. For this purpose, pass 'light' or 'dark' as the second parameter of the currentTheme method.

DevExpress.viz.currentTheme(DevExpress.devices.current(), 'light');

If you do not set the required theme, the "generic.light" theme is applied.

You can customize the applied themes by setting custom values when defining the widget's configuration object. However, if you need to have a custom theme, implement a new theme. In this topic, you will learn how to implement and use a custom theme.

If you are satisfied with the majority of option values in the applied predefined theme, but need a few of the option values changed, customize the theme. For this purpose, do the following.

• Introduce an object for a new theme and give a name to it.

  JavaScript

  var myTheme = {
      name: 'myCustomTheme',    
  };

• Specify the required settings for each widget you use within separate objects.

  JavaScript

  var myTheme = {
      name: 'myCustomTheme',
      chart: {
          // Theme options for "Chart"
      },
      pie: {
          // Theme options for "PieChart"
      },
      gauge: {
          // Theme options for "CircularGauge" and "LinearGauge"
      },
      barGauge: {
          // Theme options for "BarGauge"
      },
      rangeSelector: {
          // Theme options for "RangeSelector"
      },
      bullet: {
          // Theme options for "Bullet"
      },
      sparkline: {
          // Theme options for "Sparkline"
      },
      map: {
          // Theme options for "VectorMap"
      },
      treemap: {
          // Theme options for "TreeMap"
      },
      funnel: {
          // Theme options for "Funnel"
      }
  };

  The options that can be set in a theme are described in the Reference section.

• Register your theme, indicating the theme that your theme is based on. For this purpose, use the registerTheme method.

  JavaScript

  DevExpress.viz.registerTheme(myTheme,'generic.light');

To apply a custom theme for all widgets on the page, use the DevExpress.viz.currentTheme method passing the name of your theme as a parameter.

DevExpress.viz.currentTheme('myCustomTheme');

To use a custom theme for a particular widget only, set the theme name to the theme configuration option.

var chartOptions = {
    theme: 'myCustomTheme',
    //...   
};

Certain charts contain several series at a time. Similarly, the gauge range container can contain several ranges, and a vector map consists of several areas. In such instances, a color would need to be set for each series, range or area individually. Instead, you can use built-in palettes - sets of colors.

Palettes can be specified and used in the following widgets.

• Chart
• PieChart
• PolarChart
• CircularGauge
• LinearGauge
• BarGauge
• VectorMap
• TreeMap
• Funnel

By using the palettes, you can be sure that the colors mix well with each other and create beautiful charts. If the number of series (in Chart), series points (in PieChart), ranges (in CircularGauge and LinearGauge), bars (in BarGauge) or areas (in VectorMap) is greater than the number of colors in the palette, the palette colors are repeated with a slight modification.

The "default" palette is used by default. To apply another palette, use the palette option.

var chartOptions = {
    palette: 'Soft Pastel',
    //...   
};

Below, you can try out the predefined palettes in action.

The following subsections provide information about the available palette customizations.

If you use a predefined palette, you can still set a custom color for a particular series, range or area using the color option.

var chartOptions = {
    series: [{
        color: 'red'
        //...
    }, {...}, ...]
};

var gaugeOptions = {
    rangeContainer: {
        ranges: [{
            color: 'red'
            //...
        }, {...}, ...]
    }
};

var vectorMapOptions = {
    layers: [{
        // ...
        customize: function (elements) {
            $.each(elements, function (i, element) {
                element.applySettings({ 
                    // ...
                });
            });
        }
    }]
};

You can set a custom palette for a chart, gauge or map using the palette configuration option. Assign an array of colors to this field.

var chartOptions = {
    palette: ['#7CBAB4', '#92C7E2', '#75B5D6', '#B78C9B', '#F2CA84', '#A7CA74'],
    //...   
};

To use a custom palette in different charts, gauges and maps, define and register that palette in the following way.

var myPalette = {
    simpleSet: ['#60a69f', '#78b6d9', '#6682bb', '#a37182', '#eeba69'], // for "Chart", "PieChart", "BarGauge", "Funnel",
                                                                        // and "TreeMap" with a gradient or range colorizer 
    indicatingSet: ['#90ba58', '#eeba69', '#a37182'], // for "CircularGauge" and "LinearGauge"
    gradientSet: ['#78b6d9', '#eeba69'] // for "VectorMap" and "TreeMap" with a gradient or range colorizer 
};
DevExpress.viz.registerPalette('myCustomPalette', myPalette);

Note that different palettes apply to different widgets. Simple set is used to color chart series in Chart and PieChart and bars in BarGauge. Indicating set is used to color ranges in CircularGauge and LinearGauge. Gradient set is used to color map areas in VectorMap.

To use the registered palette, assign the palette name to the palette option of the required widgets.

To obtain the color sets of a registered palette, use the DevExpress.viz.getPalette(paletteName) method. This method returns an object of the following type.

{
    simpleSet: ['#60a69f', '#78b6d9', ... ], // palette colors for "Chart", "PieChart", "BarGauge", "Funnel",
                                             // and "TreeMap" with a gradient or range colorizer 
    indicatingSet: ['#90ba58', '#eeba69', ... ], // palette colors for "CircularGauge" and "LinearGauge"
    gradientSet: ['#78b6d9', '#eeba69'] // palette colors for "VectorMap" and "TreeMap" with a gradient or range colorizer 
}

You can apply a predefined or registered custom palette to all widgets at once. Use the DevExpress.viz.currentPalette(paletteName) method to do this.

DevExpress.viz.currentPalette('Soft Pastel');

If you call this method at runtime, re-render widgets on your page to make palette change visible.