FlexChart Templates

FlexChart Templates allow you to create highly flexible chart definitions that you can use throughout the application. Details of the chart are defined in the calculation logic, together with the data which can come either from Analytics or other storages or can be created on the fly.

With the templates you can also work-around some of the limitations of the server side framework. When you build a flex chart in the Groovy logic, you might not be able to use all the options – but you can place these options into the template.

The template defines the chart type and its properties. There are two predefined templates available (base and default) and you can create as many custom templates as you need.

Base template – Specifies options which are applied to all charts, regardless whether an explicit custom template was selected or not. The settings are merged with the custom or default template settings. In case of conflicts, the settings from the default or custom template have priority.
Default template – Specifies options which apply when no explicit custom template is selected. The settings are merged with the settings from the base template.
Custom template – An administrator-defined template. It is always merged with the base template. In case of conflicts, the settings from the custom template have priority.

The content of the chart is defined in the calculation logic. To generate a chart from the calculation logic, the following method is available:

api.buildFlexChart(String baseTemplateToUse, Object definition)

Parameters:

baseTemplateToUse – The name of the template used as a basis for merging with the passed definition. If null, the predefined Default template is used.
definition – The definition of the FlexChart. This will typically be a string or a map of maps containing chart options. Returns a helper object linking the resulting FlexChart, baseTemplateToUse and type of the result, which will always be 'FLEXCHART'.

Currently, this feature supports only Highcharts. Therefore, the chart (and template) definition must denote Highcharts options – see the Highcharts documentation for details. Note that some Highcharts options are not supported (global, events and all options based on JavaScript functions). Since Highcharts options are normally specified using a JavaScript object literal, the passed definition must be either a JSON string representing such object literal, or any object which can be mapped to a JSON representation. Therefore, the definition will typically be passed on as a map of maps.

Example

Here is a template for a waterfall chart. Make sure to use only double quotes " in the attribute names. Single quotes ' or no escaping lead to parsing errors.

{
	"chart": {
		"type": "waterfall"
	},

	"xAxis": {
		"type": "category"
	},

	"legend": {
		"enabled": false
	},

	"tooltip": {
		"headerFormat": "",
		"pointFormat": "{point.name}: {point.y:,.3f}"
	}, 

	"plotOptions": {
		"waterfall": {
			"upColor": "#8bbc21",
			"color": "#910000",
			"dataLabels": {
				"enabled": true,
				"formatter": function () {
					return Highcharts.numberFormat(this.y, 2, ',') + ' EUR';
				},
				"style": {
					"color": "#FFFFFF",
					"fontWeight": "bold",
					"textShadow": "0px 0px 3px black"
				}
			},
			"pointPadding": 0
		} 
	}
}

Data definition and chart generation in calculation logic:

def grossPrice = api.getElement("GrossPrice")
def netPrice = api.getElement("GrossNetPrice")
def discount = grossPrice - netPrice
def quantity = api.getElement("Quantity")

def data = [
		title: [
			text: 'Waterfall for product: ' + api.product("sku") + " and customer: " + api.customer("customerId")
		],
		yAxis: [
			title: [
				text: 'EUR'
			]
		],

		tooltip: [
			pointFormat: '<b>{point.y:,.2f}</b> EUR'
		],
		series: [[
			data: [[
				name: 'Gross Price',
				y: grossPrice,
				color: "#0d233a"
			], [
				name: 'Discount',
				y: - discount
			],[
				name: 'Gross Net Price',
				isSum: true,
				color: "#0d233a"
			], [
				name: 'Promotion',
				y: - api.getElement("Promotion")
			],[
				name: 'Net Price',
				isSum: true,
				color: "#0d233a"
			], [
				name: 'Surcharges',
				y: api.getElement("Surcharges")
			], [
				name: 'Invoice Price',
				isSum: true,
				color: "#0d233a"
			], [
				name: 'Costs',
				y: - api.getElement("Cost")
			], [
				name: 'Margin',
				isSum: true,
				color: "#0d233a"
			]]
		]]
	]
api.buildFlexChart("demo_contract_waterfall", data)