Ext Charts Upgrade Guide

We introduced a new, high performance, touch-optimized charts package in Sencha Touch 2.1. We have now enhanced that charts package to work with Ext JS 5 and Sencha Touch. This brings lots of new capabilities, as well as great performance on tablet devices.

Let’s talk about some of the changes that may need to be made to update from Ext JS charts to the new Sencha Charts package.

Installing Sencha Charts

Sencha Charts are not included in the Ext JS library by default. In order to include the charts package, simply add “sencha-charts” to the requires block in your application’s app.json file. Adding a package name to the requires block directs Cmd to make the package available to your application.

After making the inclusion, ensure that your application has been rebuilt. Applications may be rebuilt by manually issuing the following command:

sencha app build

You may also activate “app watch”:

sencha app watch

Sencha app watch monitors your application’s assets and rebuilds when it detects change.

Charts

There are three types of base charts:

• cartesian/chart - Creates a chart for series implementations that plot values using cartesian coordinates. Examples of this include Bar, Area, Scatter, and Line charts.
• polar - Creates a chartfor series implementations that plot values using polar coordinates. Examples of this include Pie and Radial charts.
• spacefilling - Creates a chart that fills the entire area of the chart. Examples of this include Gauge and Treemap charts.

ext-charts tried to automatically determine the chart type by evaluating the series type. This allowed users to simply set the xtype to ‘chart’. However, sencha-charts needs a designated xtype in some circumstances. Cartesian charts are the most commonly used and are mapped to the alias of ‘chart’. Setting an xtype of ‘chart’ will makes the assumption that you want a Bar,Line, Scatter, or Area chart. Other types of charts will require an xtype designation of polar or spacefilling.

Canvas & SVG

Charts can now use either HTML Canvas or SVG to render its contents. The render engine is selected automatically depending on the platform used. Priority is given to the canvas engine due to its performance advantage. SVG is currently only used on Android 4.0+ due to the following bug:

http://code.google.com/p/android/issues/detail?id=37529

That said, charts will look the same regardless of the engine used, though the SVG engine does not support shadows at the moment.

You may force the use of either engine by adding the engine property to the chart’s config. These configs would look like this:

engine: Ext.draw.engine.Canvas
engine: Ext.draw.engine.Svg

During development, you can quickly switch from one engine to another by appending/removing ?svg=true to/from the URL.

Chart Redraw

In the past, you may have found yourself using chart’s refresh() method to repaint the chart. We now recommend using chart’s redraw() method for this functionality.

Chart Animation

Chart’s animate config will now default to true. You will need to set animate to false if you intend to disable animations.

Gradients

The gradients config object now uses slightly different syntax. Any charts using the gradients object will need to be updated as per the following:

Old style

gradients: [{
    id: 'gradientId',
    angle: 45,
    stops: {
        0: {
            color: '#555'
        },
        100: {
            color: '#ddd'
        }
    }
}, {
    id: 'gradientId2',
    angle: 0,
    stops: {
        0: {
            color: '#590'
        },
        20: {
            color: '#599'
        },
        100: {
            color: '#ddd'
        }
    }
}]

New style

gradients: [{
    id: 'gradientId1',
    type: 'linear',
    angle: 45,
    stops: [{
        offset: 0,
        color: 'red'
    }, {
       offset: 1,
       color: 'yellow'
    }]
}, {
   id: 'gradientId2',
   type: 'radial',
   stops: [{
       offset: 0,
       color: '#555',
   }, {
       offset: 1,
       color: '#ddd',
   }]
}]

Radial Gradients

We have added support for radial gradients, which means that the gradient type is now required in the gradient object.

Saving Charts

Chart saving cannot be consistently implemented across all the platforms. Many mobile devices simply won’t allow users to download files. For that reason, the chart.preview() method should be used instead of chart.download() . Both are new methods for Ext JS 5.

Preview

chart.preview() shows a dialog window with an image of the chart inside. The user can then use their browser’s native image saving functionality to download the image.

Download

chart.download()attempts a client-side download of the chart’s image. This method currently works exclusively in Chrome at this time.

Save

It is also important to note that the chart.save() method is now deprecated. While in the deprecated state, chart.save() will disregard the value of type passed to it and the actual format will be SVG or PNG. This type is dependent on the render engine used. If chart.save() is called on a device in which downloading is not possible, chart.save() will result in a chart.preview() .

Image Rasterization

In previous versions of charts, chart.save() generated an SVG document and sent it to a Sencha server for rasterization. New charts generate a DataURL in the Canvas or SVG format (depending on the render engine used), so the same approach can be used.

Note: We have not yet upgraded our server-side application with support for the new formats.

Sprites

Sprite attribute names now mimic Canvas context attributes instead of SVG attributes:

Old name	New name
fill, color	fillStyle
stroke	strokeStyle
stroke-width	lineWidth
stroke-linejoin	lineJoin
stroke-miterlimit	miterLimit
text-anchor	textAlign
opacity	globalAlpha
translateX	translationX
translateY	translationY
rotateRads	rotationRads
rotateCenterX	rotationCenterX
rotateCenterY	rotationCenterY
scaleX	scalingX
scaleY	scalingY
scaleCenterX	scalingCenterX
scaleCenterY	scalingCenterY

Old attribute names will still be recognized since new attribute names have been given aliases. That said, we highly recommend the use of new attribute names to ensure your application’s longevity.

Additional Attributes

We have also added support for two new attributes: lineDash and lineDashOffset.

• lineDash - takes an array of numbers that specify a sequence of dash/space, e.g. [1,1] or [7,3,3,3].
• lineDashOffset - specifies how far into the line dash sequence drawing commences.

Axes

Axes Type

Axis type should now be all lowercase:

axes: [
    {
        type: 'numeric',
        position: 'left',
        ...
    },
    {
        type: 'category',
        position: 'bottom',
        ...
    }
]

Renderers

Renderers should be defined directly on the axis, not inside the label config as in previous versions:

axes: [{
    type: 'numeric',
    position: 'left',
    // Will make all labels have precision of 1 decimal place
    // and have '%' added at the end.
    renderer: function (v) { return v.toFixed(1) + '%' },
    label: { // no renderer here
        fontSize: 14
    }
}]

Grid

Grid is now disabled by default.

Limits

Axes now support the limits config. Example usage can be seen here:

limits: [{
    value: 70,
    line: {
        strokeStyle: 'red',
        lineDash: [6, 3],
        title: {
            text: 'Average temperature (˚F)',
            fontSize: 14
        }
    }
}]

Floating Axes

Floating axes are now supported. Floating axis tracks a specified value on another axis that runs in the opposite direction.

Please refer to the docs for the floating config and/or see the following Kitchen Sink examples:

Column - Multi Axis

Radial - Multi Axis

Series

Bar and Column Widths and Gaps

The Ext JS 5 API focuses on setting maximum and minimum values to manipulate widths and gaps.
These settings allow the chart’s bars and columns to fit within the available space. The Ext JS 4 API set absolute values for the width of bars and columns and let the gaps fill the rest of the space. You were then allowed you to define the gaps as a ratio of the bar and column width.

When migrating bar and column width/gap settings to Ext JS 5, you’ll want to begin working with the following configs:

• Ext.chart.series.sprite.Bar-cfg-maxBarWidth
• Ext.chart.series.sprite.Bar-cfg-minBarWidth
• Ext.chart.series.sprite.Bar-cfg-minGapWidth

highlightCfg

highlightCfg config (object) should be used in place of highlight config (boolean/object), e.g.:

series: {
  type: 'pie',
  highlightCfg: {   // defines a change in series sprite's style that
      margin: 30    // happens when series item becomes highlighted
  }
}

Notice the difference with the old definition for Pie series:

highlight: {
    segment: {
        margin: 30
    }
}

Color

The color config should be used instead of colorSet config to set series’ colors manually, e.g.: colorSet: ['#82B525', '#ddd'] .

shadowAttributes

shadowAttributes config is no longer supported. But you can define a style instead, e.g.:

series: {
    style: {
        shadowColor: 'rgba(0,0,0,0.5),
        shadowBlur: 10
    }
}

Note: shadows are not supported by the Svg engine Ext.draw.engine.Svg .

Config

Chart’s series config is an Array now. That said, chart.series.first() won’t work.

Please use:

chart.getSeries()[0]

Marker

One should use marker config instead of markerConfig config to define series’ markers.

Column series

There’s no series of type column anymore, one has to use bar series instead, e.g.:

axes: [{
    type: 'numeric',
    position: 'left',
    ...
}, {
    type: 'category',
    position: 'bottom',
    ...
}],
series: {
    type: 'bar',
    ...
}

Bar series

In the same vein of column chart, there is no bar type anymore. You’ll need to use the bar series but with flipXY property set to true for horizontal bars.

When flipping the chart, axes positions should be changed accordingly, e.g.:

flipXY: true,
axes: [{
    type: 'numeric',
    position: 'bottom',
    ...
}, {
    type: 'category',
    position: 'left',
    ...
}],
series: {
    type: 'bar',
    ...
}

Pie series

labelField

labelField: 'name'

config should be used instead of

label: {
  field: 'name'
}

Radar series

There is no axis type radial . Use

axes: [{
    type: 'numeric',
    position: 'radial',
}, {
   type: 'category',
   position: 'angular',
}]

instead of:

axes: [{
    type: 'Radial',
    ...
}]

Gauge series

Gauge series do not support themes and have to be styled manually with chart.colors , series.style and series.subStyle configs.

Area series

label config is not yet supported.

Scatter series

label config is not yet supported.