As described in the article when getting started with Corporate Charts, we configure chart and color templates in .json files. With Corporate Charts, we are able to set series color, font, font size and weight, configure lines (axis, grid, etc.) and control tick marks and data labels. This article will elaborate how to configure these templates.
Contents
Color template
It is pretty simple to configure a color template. The .json file should consist of nothing but a key with a value for each color that should be in the color template. The key is the name of the color, while the value is the color in RGB. The color template can contain as many colors as needed.
Here is an example:
{
"White": "255,255,255",
"Black": "0,0,0", "Chocolate": "77,60,47", "Caramel": "207,189,155", "Terracota": "192,113,86", "Honey": "232,199,103" }
An example of usage can be seen in a solution.
We also support using alpha. If ARGB is defined, we set transparency on the chart. This can be done for all color references in the configuration. If the alpha is 0, it will be fully transparent, while it will not be transparent at all if alpha is 255. Here are some examples:
"0,0,0,0"
= Fully transparent"255,0,0,0"
= Not transparent at all black (this is the same as just writing "0,0,0")"127,0,0,0"
= 50% transparent black
Accent colors
If the chart colors should be the same as the accents already defined in the word template, then those accents can be called instead.
Here is an example:
{
"Color2": "Accent2",
"Color3": "Accent3",
"Color4": "Accent4",
"Color5": "Light2",
"Color6": "Dark1"
}
When referencing the color code of "Color2", it will have the "Accent2" relevant for the active document or presentation.
Chart template
There are several elements that can be configured in the chart template. These are shown and shortly described below. We have an empty default template that can be copied and pasted into the json.
General
The general configuration includes font name, font size and font color. Furthermore, we support setting the font size for PowerPoint, if it is different from the font size in Word and Excel. When a color is defined in the color template, it can later be referred to in the chart template, so instead of setting the color with RGB, we type the name of the color (the key in the color template).
"General": { "FontName": "Arial", "FontSize": 12,
"FontSizePp": 14, "FontColorRef": "Black",
"FontBold":false }
Nevertheless, it is also possible to define the color in RGB (or ARGB).
Supporting East Asian font parameter
Some solutions require different font settings for Latin characters and East Asian characters. In such case, we must include several parameters, FontNameFarEast
and FontNameComplexScript
. It is possible to set the following theme fonts:
-
+Body
-
+Body Asian
- +Body CS
- +Headings
- +Headings Asian
- +Headings CS
Here is an example:
"General": { "FontName": "+Body", "FontNameFarEast": "+Body Asian", "FontNameComplexScript": "+Body CS", "FontSize": 12,
"FontSizePp": 14, "FontColorRef": "Black" }
HasChartTitle
This property controls chart title visibility. Default or omit to true. Set to false if the chart is intended to be inserted into placeholder already containing chart title.
Gridlines
We are able to define major/minor vertical/horizontal gridlines in the chart. The default value is false. Further, it is possible to define the weight (using points) and color (using a color reference) of the gridlines.
NOTE: Horizontal/vertical is inverse.
We also support styling of the line using the LineStyle
property where the following values are supported:
- Continuous
- Dash
- DashDot
- DashDotDot
- Dot
- LineStyleNone
NOTE: Double and SlantedDashDot gridlines aren't supported anymore in charts.
If LineStyle
property is omitted but gridlines are defined to be visible, they will just be default solid.
"Gridlines": { "MajorHorizontal": false, "MajorVertical": true, "MinorHorizontal": true, "MinorVertical": false, "Weight": 0.5, "ColorRef": "Black",
"LineStyle": "DashDotDot" }
Axis
In the Axis
property, we can control the axis lines, tick marks, rotation of the axis text as well as series overlap and gap width.
If the chart template has the major gridlines set to be true, the design for the gridlines will automatically count for the axis line as well. If the chart design requires specific settings for the axis line(s), we must use the following properties within AxisLine
to specify the design:
PrimaryCategory
- the primary axis that holds the category (typically the X-axis).PrimaryValue
- the primary axis that holds the values (typically the Y-axis).SecondaryCategory
- the secondary axis that holds the category. Only needed if the particular chart has a secondary axis (rarely used).SecondaryValue
- the secondary axis that holds the values. Only needed if the particular chart has a secondary axis (rarely used).
Each of these supports the following parameters:
Visible
which controls the visibility usingtrue
orfalse
(required parameter).Weight
of the axis line which must be defined in points.ColorRef
which controls the color of the axis line and is defined with a key from the color template.HasAxisTitle
which should be defined totrue
if the particular axis should have an axis title.AxisTitleDesign
which controls the design of the axis title that is set to be true. DefineFontName
,FontBold
FontItalic
andFontSize
inside this property.MajorTickMarks
which applies major tick marks. The value should be eitherOutside
,Inside
,Cross
orNone
, depending on how the tick marks should be applied. This parameter can be omitted if the chart should have none.MinorTickMarks
which applies minor tick marks. The value should be eitherOutside
,Inside
,Cross
orNone
, depending on how the tick marks should be applied. This parameter can be omitted if the chart should have none.TickLabelPosition
By default, the axis labels will be placed right under the x-axis, but if the y-axis is negative, it can be useful to move the labels to the button of the chart. UseLow
,High
orNextToAxis
, to move the labels. UseNone
if the labels should not be shown.
An example of configuration can be seen below.
Notice that most of our current clients that have CC3 implemented have another configuration in terms of axis lines. Here, we define the weight and the color directly in the AxisLine
property and then there is a third parameter called TickMarks
, which can be either true or false. The naming of this parameter is not appropriate as it does not set tick marks but define whether the weight and color should apply for the X-axis (rather than the settings from the gridlines) as well as it adds a Y-axis. For this reason, we recommend that we use the above-mentioned approach to define the axis line design in future CC3 configurations, as it also allows us to design the Y-axis.
AxisText rotation is not fully implemented and should only be defined as "null".
Series overlap and gap width must be defined in points.
You can use null as a value if nothing is to be set for the parameter concerned.
"Axis": { "AxisLines": { "PrimaryCategory": {
"Weight": 1,
"ColorRef": "Black",
"Visible": true,
"MajorTickMarks": "Cross",
"HasAxisTitle": true,
"TickLabelPosition": "Low",
"AxisTitleDesign": {
"FontName": "Arial",
"FontBold": true,
"FontItalic": true,
"FontSize": 8
}
},
"PrimaryValue": {
"Visible": false
},
"SecondaryCategory": {
"Visible": false
},
"SecondaryValue": {
"Visible": false
} }, "AxisText": { "Rotation": null }, "SeriesOverlap" : "0", "GapWidth" : "50" }
Chart title
We support configuring font name, font size and font color of chart titles. Furthermore, we support setting the font size for PowerPoint, if it is different from the font size in Word and Excel. We can also define whether the chart title should be bold using true
or false
, and how it should be positioned according to the chart, using Right
, Left
or Center
.
"ChartTitle": { "FontName": "Arial", "FontSize": 14,
"FontSizePp": 16, "FontColorRef": "Black",
"FontBold": true,
"ChartTitlePosition": "Left" }
We also support East Asian font parameters for the chart title. Here is an example:
"ChartTitle": { "FontName": "+Headings",
"FontNameFarEast": "+Headings Asian",
"FontNameComplexScript": "+Headings CS", "FontSize": 14,
"FontSizePp": 16, "FontColorRef": "Black",
"FontBold": true,
"ChartTitlePosition": "Left" }
Legends
We support setting the position for legends and we can set one of the following options: Bottom
Left
Right
Top
TopRight
Furthermore, we support the same font properties as in general and chart title (including the East Asian parameters) which, for example, allow us to set a different font size in the legends.
"Legend": {
"Position": "Bottom", "FontName": "Arial", "FontSize": 8, "FontColorRef": "Black", "FontBold": false
}
Series design
We support different options for the design of the series, including settings for data labels, the angle of the first slice, marker style, series lines, the size of the hole in the doughnut, line weight, explosion in doughnut, and pie as well as borders on the series.
For borders, we type the name of the color (the key in the color template). Furthermore, we support defining series overlap and gap width specifically for bar charts.
The LineWeight
property sets the line width of line series in a line chart, scatter chart, or radar chart. The BorderWidth
property controls the width of the border around non-line-based charts. If this is not defined, but LineWeight
is, the border around the non-line-based series will have the width of the LineWeight
parameter. Notice that the separator in the value for both properties must be a dot, otherwise, it will not be able to parse the chart design.
Besides the font settings for data labels, we can define their position. For most charts, we support the following values:
- Center
- InsideEnd
- InsideBase
- OutsideEnd
- BestFit
Stacked, pie and doughnut charts support only some of these, while line, X Y (Scatter), and radar charts support different values. For more information, please see chapter 2.h Specify chart design for stacked, pie, doughnut or line charts. However, if there is a case where we try to set the data label position to an unavailable position, the applier will not break but instead set the initial chart position and give a warning in the log.
The following is an example of configuration with the present properties.
"SeriesDesign" : {
"FirstSliceAngle" : 30,
"DoughnutHoleSize" : 45,
"DoughnutExplosion" : 10,
"PieExplosion" : null,
"SeriesOverlap": 0,
"GapWidth": 50,
"BorderColorRef": "White",
"BorderWidth": 1,
"HasMarker": true,
"MarkerSize":10,
"MarkerStyle": "Star",
"LineWeight": 2.25,
"DashStyle": "Solid",
"DisableBorders": true,
"SeriesLinesDesign" : {
"ColorRef" : "Accent4",
"Weight" : "0.5"
},
"HasDataLabels": true,
"DataLabelDesign": {
"FontBold": false,
"FontName": "Arial",
"FontSize": 6,
"FontSizePp": 10,
"FontColorRef": "Black",
"Position": "BestFit",
"ShowValue": true,
"Showpercentage" : false
}
}
To show data labels in values, we need to set ShowValue
as true, and to show data labels in percentage, we need to set ShowPercentage
as true. Both can be set to true simultaneously, but it is important to remember that ShowPercentage
can only be applied to Pie and Doughnut charts. That means that it has to be included in the Pie
, Doughnut
, or PieDoughnut
objects in the template (which are explained later in this article). Including it in the general SeriesDesign
object will break the configuration.
The DisableBorders
parameter makes it possible to remove borders from series. This is mostly used for pie and doughnut charts. If the property is set to false or omitted, the series will have white borders as default. Note that this setting does not affect line-based charts.
The MarkerStyle
is only for scatter charts and we support the following types:
- Automatic
- Circle
- Dash
- Diamond
- Dot
- None
- Picture
- Plus
- Square
- Star
- Triangle
- X
The DashStyle
property allows to define the style of the lines in a line chart. The following options are supported:
- Dash
- DashDot
- DashDotDot
- LongDash
- LongDashDot
- RoundDot
- Solid
- SquareDot
Chart area
In the chart area, we can set the fill type and fill color of the background. We define fill type using one of the following properties:
Accent
Automatic
NoChange
NoFill
None
Rgb
SolidFill
If the FillType
parameter is set to null
, we look into the color .json file.
Furthermore, we support settings for the border of the chart area. Here, we can define the width (in points), the color using a color reference and the border type, which can be either Solid
or None
.
Below is an example.
"ChartArea": { "FillType": null, "FillColorRef": "White",
"Border": {
"Width": 1.5,
"ColorRef": "Black",
"Type": "Solid"
} }
Specify design for defined chart types
It is possible to define the entire chart design properties specifically for stacked, pie, doughnut and line charts, e.g. if a line chart should have other settings than the remaining chart types. Thus, we support the following properties for the chart template which then can contain the above-mentioned parameters:
Stacked
Pie
Doughnut
PieDoughnut
Line
LineWithMarkers
LineRadarScatter
Scatter
Radar
Column
Bar
The difference between Line
and LineRadarScatter
is that the latter, apart from line charts, also applies to radar and X Y (Scatter) charts. Scatter
is just for scatter charts.
In Pie charts, a border with 100% transparency will display with no borders (Office behavior).
As mentioned earlier, stacked, pie and doughnut charts support only some of the standard values for data label positions:
Supported data label positions | |
Stacked chart |
|
Pie chart |
|
Doughnut chart |
|
Furthermore, line, radar and scatter charts support different values in order to control the position of data labels. More specifically, the parameter LineBasedPosition
needs to be included and the supported values are as follows:
- Center
- Above
- Below
- Left
- Right
Here are some examples:
"Stacked": {
"SeriesDesign": {
"HasDataLabels": true,
"DataLabelDesign": {
"FontBold": true,
"FontColorRef": "ColorName",
"Position": "Center",
"ShowValue": true
}
}
},
"Doughnut":{
"SeriesDesign":{
"DisableBorders": true
}
},
"PieDoughnut": {
"SeriesDesign": {
"FirstSliceAngle" : 0,
"DoughnutExplosion" : 0,
"DoughnutHoleSize" : 50,
"HasDataLabels": true,
"DataLabelDesign": {
"FontName": "Arial",
"FontSize": 16,
"FontColorRef": "Black",
"Position": "Center",
"ShowPercentage": true,
"ShowValue": false
}
}
},
"Line": {
"Axis": {
"AxisLines": {
"PrimaryCategory": {
"Weight": 0.75,
"ColorRef": "Accent5",
"Visible": true,
"MajorTickMarks" : "Inside",
},
"PrimaryValue": {
"Visible": false
},
"SecondaryCategory": {
"Visible": false
},
"SecondaryValue": {
"Visible": false
}
}
}
},
"LineWithMarkers": {
"SeriesDesign": {
"MarkerStyle": "Diamond",
"HasMarker": true
}
},
"LineRadarScatter":{
"SeriesDesign": {
"HasDataLabels": true,
"DataLabelDesign": {
"FontBold": true,
"FontSize": 20,
"FontColorRef": "ColorName",
"LineBasedPosition": "Above",
"ShowValue": true
}
}
}
Extended chart types
Funnel, Histogram, BoxWhisker, Waterfall, Treemap and Sunburst.
Support for these chart types were implemented much later than the other supported chart types.
NOTE: At the moment we have not implemented support for axis, gridline and label configuration for extended charts.
Note that the Funnel
chart cycles through all the colors data series while the Histogram
sets the same color to all its bars.
BoxWhisker
has it's own object of design properties, similarly to the chart types described in the previous section (ie. Line, Donut, etc.). This is because the BoxWhisker
chart types is reliant on the outline, so the option exists to overwrite the outline colors specifically for this chart type.
{
"BoxWhisker":{
"DataSeries": [
{
"OutlineColorRef": "Blue"
},
{
"OutlineColorRef": "Green"
}
]
}
}
- BoxWhisker.DataSeries.OutlineColorRef
- DataSeries.OutlineColorRef
- DataSeries.MarkerBorderColorRef
- DataSeries.MarkerFillColorRef
- DataSeries.PrimaryColorRef
This means that if no outline color is defined, the BoxWhisker chart will be generated with the same color as the data series. This means that the outline will not be visible.
Invisible series
If a chart has hidden series, it can be handy to skip these when applying colors. To do so, include the following parameter in the .json. This will skip the invisible series as well as remove the series from the legends.
"SkipBlankSeries" : true
Colors of data series
In the chart template, we define which colors each series should have and here we also refer to the color template. You can include as many primary colors as needed. Note that the order of the colors will be the same when inserting a chart. This means that if you insert a chart with three data series, it will take the first three colors from the template.
Additionally, we can define the color of the data labels for each data series. This is possible by using the DataLabelColorRef
parameter and referring to the color template. The OutlineColorRef
parameter controls series' outline colors. Currently only supported for BoxWhisker chart type.
If this is present for each DataSeries
element, it will override the default data label color that is defined in the SeriesDesign
element.
"DataSeries": [ { "PrimaryColorRef": "Chocolate",
"DataLabelColorRef": "White",
"OutlineColorRef": "Chocolate" }, { "PrimaryColorRef": "Caramel",
"DataLabelColorRef": "White",
"OutlineColorRef": "Caramel" }, { "PrimaryColorRef": "Terracota",
"DataLabelColorRef": "Black",
"OutlineColorRef": "Terracota" }, { "PrimaryColorRef": "Honey",
"DataLabelColorRef": "Black",
"OutlineColorRef": "Honey" } ]
Example of chart template
{
"General": {
"FontName": "+Body",
"FontNameFarEast": "+Body Asian",
"FontSize": 10,
"FontColorRef": "Black"
},
"Gridlines": {
"MajorHorizontal": false,
"MajorVertical": true,
"MinorHorizontal": false,
"MinorVertical": false,
"Weight": 0.25,
"ColorRef": "Black"
},
"Axis": {
"AxisLines": {
"PrimaryCategory": {
"Weight": 1,
"ColorRef": "Black",
"Visible": true
},
"PrimaryValue": {
"Visible": false
},
"SecondaryCategory": {
"Visible": false
},
"SecondaryValue": {
"Visible": false
}
},
"AxisText": {
"Rotation": null
},
"SeriesOverlap" : "0",
"GapWidth" : "50",
},
"ChartTitle": {
"FontName": "+Body",
"FontNameFarEast": "+Body Asian",
"FontSize": 10,
"FontColorRef": "Black"
},
"Legend": {
"Position": 1
},
"SeriesDesign" : {
"MarkerStyle": "Square"
},
"ChartArea": {
"FillType": null,
"FillColorRef": null
},
"PlotArea": {
"FillType": null
},
"SkipBlankSeries" : true,
"DataSeries": [
{
"PrimaryColorRef": "Chocolate"
},
{
"PrimaryColorRef": "Caramel"
},
{
"PrimaryColorRef": "Terracota"
},
{
"PrimaryColorRef": "Honey"
},
{
"PrimaryColorRef": "Stone"
},
{
"PrimaryColorRef": "Chestnut"
},
{
"PrimaryColorRef": "Straw"
},
{
"PrimaryColorRef": "Smoke"
},
{
"PrimaryColorRef": "Cinnamon"
}
]
}
Comments
0 comments
Article is closed for comments.