The Configuration Item Templates for Chart Controls

Current version: 9.0

Many of the chart controls use configuration items based on common templates. This topic describes these common configuration item templates:

The ChartField template

All charting controls have properties called CategoryChartField, ValueChartFields and SeriesChartField in the DataMapping group. You specify a ChartField configuration item as the value of these control properties, and you specify which chart data fields the control uses (as well as other information) in this ChartField configuration item.

You create a ChartField configuration item by creating an item based on the ChartField template. The convention is to place this item in the PageSettings folder of your page or application.

The item has these fields:

Field

Description

HeaderText

Specify the name that the control shows as a label for this field.

DataField

Specify the name of the data field.

MultiAxisChartPosition

Specify the position of the axis that the control shows for this field in a multiaxis LineChart. You can specify Left or Right.

CombinationChartRenderAs

Specify a combination chart-rendering mode. You can specify Line, Area, or Column.

Prefix

Specify a string that the control prepends to the chart values when it shows them.

Suffix

Specify a string that the control appends to the chart values when it shows them.

NumberScale

Specify a NumberScale configuration item that the control uses for scaling numbers. You can specify one of these predefined items: DataSize, Number, or Time.

For more details and information about how to create your own number scales, see the description of the NumberScale template.

ScaleRecursively

If you select this field, the number scale is broken into smaller sections. This can make it easier for users to understand the data.

For example, if you plot time values, 3.87 days is displayed as 3 days, 20 hours, 52 minutes and 25 seconds.

The NumberScale template

You use a NumberScale configuration item to scale the numbers that a charting control shows. Number scaling shortens the numbers on a chart according to a scale. You can specify a specific number scaling for each chart field in a ChartField configuration item.

A number-scaling specification consists of two series of values: the ScaleValue and the ScaleUnit. The ScaleValue series is a series of numbers, and the ScaleUnit series is a series of labels. The two series must have the same number of members.

For example:

The predefined Number configuration item has ScaleValue"1000,1000,1000" and ScaleUnit"K,M,B". This is a standard Metric scaling: K for thousands (kilo), M for millions, and B for billions. This configuration will scale numbers for display like this:

Number

Scales as

800

800

8000

8K

8000000

8M

8000000000

8B

This means that values in the same chart can have different scales (if, for example, 8,000 and 8,000,000 were values in the same chart).

The logic is as follows:

  • If the value is less than the first number in ScaleValue, nothing happens. “800” scales as “800.”

  • If the value is larger than the first number in ScaleValue, but less than the product of the first and the second number in ScaleValue, the value is divided by the first number in ScaleValue, and the first ScaleUnit is appended. 8000 is larger than 1000 but less than 1000*1000. Therefore, 8000 is divided by 1000 and K is appended: “8000” scales as “8K.”

  • If the value is larger than the second number in ScaleValue, but less than the product of the first, second and third number in ScaleValue, the value is divided by the product of the first and the second number in ScaleValue, and the second ScaleUnit is appended. 8000000 is larger than 1000*1000 but less than 1000*1000*1000. Therefore, 8000000 is divided by 1000*1000 and M is appended: “8000000” scales as “8M.”

  • And so forth.

SPEAK has four predefined NumberScale configuration items:

Name

ScaleValue

ScaleUnit

Number

"1000,1000,1000"

"K,M,B"

DataSize

"8,1024,1024,1024,1024"

"bytes,KB,MB,GB,TB"

Percentage

Time (scales a value in seconds)

"60,60,24,7"

"min,hr,day,wk"

You can create your own scales for numbers:

  1. Create an item based on the NumberScale template in the /sitecore/client/Business Component Library/System/Charting/NumberScales folder.

  2. Enter a comma-separated and quoted string of numbers in the ScaleValue field.

  3. Enter a comma-separated and quoted string text strings in the ScaleUnit field. It is important that you specify the exact same number of numbers in ScaleValue and text strings in ScaleUnit.

  4. Save this item.

You can now select the NumberScale item that you created in the NumberScale field of a ChartField item.

Do you have some feedback for us?

If you have suggestions for improving this article,