Understand charts: Underlying data and chart representation

Charts display data visually by mapping textual values on two axes: horizontal (x) and vertical (y). The x axis is called the category axis and the y axis is called the series axis. The category axis can display numeric and non-numeric values whereas the series axis only displays numeric values.

Charts in model-driven apps can be further classified into the following groups:

  • Single-series charts: Charts that display data with a series (y) value mapped to a category (x) value.

  • Multi-series charts: Charts that display data with multiple series values mapped to a single category value. Multi-series charts include stacked column charts, which vertically display the contribution of each series to a total across categories, and 100% stacked column charts, which compare the percentage that each series contributes to a total across categories. You can combine different compatible chart types in multi-series charts, for example, column and line, bar and line, and so on.

Note

Multi-category charts can be created through the web application or by modifying the XML strings described here.

While authoring a chart in model-driven apps using the SDK, you need to consider the following two important aspects:

  • Underlying data for the chart: Specified using the data description XML string.

  • Data representation (appearance): Specified using the presentation description XML string.

Note

Microsoft Chart Controls lets you create various types of charts such as column, bar, area, line, pie, funnel, bubble, and radar. The chart designer in model-driven apps lets you create only certain types of charts. However, using the SDK, you can create most of the chart types that Microsoft Chart Controls support.

Use the data description XML string to specify chart data

The data description XML string defines the data that is displayed on the chart. The contents of the XML string are validated against the visualization data description schema. For more information about the schema, see Visualization Data Description Schema.

You can specify the data description XML string while you're creating a chart using the SavedQueryVisualization.DataDescription or UserQueryVisualization.DataDescription for the organization-owned or user-owned chart respectively.

The data description XML string contains the following two elements: <FetchCollection> and <CategoryCollection>.

The <FetchCollection> element

The <FetchCollection> element uses FetchXML to retrieve data for the chart. The FetchXML query specifies information about the table columns, aggregate functions, and the group by clauses for the data to be displayed in a chart. All the FetchXML aggregate functions are supported for charts. For more information about the FetchXML aggregate functions, see Aggregate data using FetchXml.

The FetchXML query enables you to filter your data. Also, filters are applied on charts through views. Therefore, if a filter condition is already specified in the FetchXML query in the <FetchCollection> element, and additionally a filter is applied through a view, the chart will display data that is returned after it applies all the filters. For more information about how to use the FetchXML query to filter data, see Query data using FetchXml.

Note

Although the data description XML string is validated again the visualization data description schema, the FetchXML query inside the <FetchCollection> element isn't. The FetchXML query is validated against the FetchXML schema. For more information, see FetchXml reference.

If the chart is a comparison chart, the <FetchCollection> element contains two groups by* clauses.

The <CategoryCollection> element

The <CategoryCollection> element contains information about the category (horizontal) and the series (vertical) axes in a chart.

  • Each <Category> subelement has a child element called <MeasureCollection> that maps to the <Series> element in the presentation description XML. A single series chart has a single <MeasureCollection> child element whereas a multi-series chart has multiple <MeasureCollection> child elements, each mapped to the respective <Series> element in the presentation description XML.
  • Each <MeasureCollection> child element has an element called <Measure> that corresponds to the series (vertical) axis value, corresponding to each value on the category (horizontal) axis.

Example

The following is a sample data description XML string:

<datadefinition>  
  <fetchcollection>  
    <fetch mapping="logical" count="10">  
      <entity name="opportunity">  
        <attribute name="estimatedvalue" />  
        <order attribute="estimatedvalue" descending="true" />  
      </entity>  
    </fetch>  
  </fetchcollection>  
  <categorycollection>  
    <category>  
      <measurecollection>  
        <measure alias="estimatedvalue" />  
      </measurecollection>  
    </category>  
  </categorycollection></datadefinition>  

For more sample data description XML strings, see Sample Charts.

Use the presentation description XML string to specify data representation

The presentation description XML string contains information about the appearance of the chart such as chart title, chart color, and chart type (bar, column, line, and so on). There's no schema definition for this XML string. However, the XML is a serialization of the Chart class in Microsoft Chart Controls. Learn more about Chart Controls

You can specify the presentation description XML string while you're creating a chart using the SavedQueryVisualization.PresentationDescription or UserQueryVisualization.PresentationDescription for the organization-owned or user-owned chart, respectively.

Note

With the modern, refreshed look, charts control on view pages and dashboards were updated to a new color palette, overriding any custom colors by default. If you would like your charts to continue using custom colors with the modern refreshed look, you need to add CustomColorOverride property in the chart .xml file.

<Chart CustomColorOverride="true">

Important

In Unified Interface, only a subset of properties are supported. Learn more about Supported methods and properties in Unified Interface

Example for web client

The following XML is a sample presentation description XML string for web client:

<Chart Palette="BrightPastel">
  <Series>
    <Series _Template_="All"
      Color="153, 204, 255"
      BorderColor="164, 164, 164"
      BorderDashStyle="Solid"
      BorderWidth="1"
      ShadowColor="128, 128, 128, 128"
      ShadowOffset="1"
      IsValueShownAsLabel="true"
      Font="{0}, 6.75pt"
      BackGradientStyle="TopBottom"
      BackSecondaryColor="0, 102, 153"
      LabelForeColor="100, 100, 100"
      ChartType="Column">
      <SmartLabelStyle Enabled="True" />
      <Points />
    </Series>
  </Series>
  <ChartAreas>
    <ChartArea _Template_="All"
      BackColor="White"
      BorderColor="26, 59, 105"
      BorderWidth="0"
      BorderDashStyle="Solid">
      <AxisY LineColor="204, 204, 204"
        TitleFont="{0}, 8pt, GdiCharSet=0"
        TitleForeColor="100, 100, 100"
        LabelAutoFitMaxFontSize="7"
        LabelAutoFitMinFontSize="7">
        <MajorTickMark LineColor="Gray" />
        <MajorGrid Enabled="false" />
        <LabelStyle Font="{0}, 6.75pt, GdiCharSet=0"
          ForeColor="100, 100, 100" />
      </AxisY>
      <AxisX LineColor="204, 204, 204"
        TitleFont="{0}, 8pt, GdiCharSet=0"
        TitleForeColor="100, 100, 100"
        LabelAutoFitMaxFontSize="7"
        LabelAutoFitMinFontSize="7">
        <MajorTickMark LineColor="Gray" />
        <MajorGrid Enabled="false" />
        <LabelStyle Font="{0}, 6.75pt, GdiCharSet=0"
          ForeColor="100, 100, 100" />
      </AxisX>
    </ChartArea>
  </ChartAreas>
  <Titles>
    <Title _Template_="All"
      Font="{0}, 9pt, style=Bold, GdiCharSet=0"
      ForeColor="100, 100, 100"></Title>
  </Titles>
  <BorderSkin PageColor="Control"
    BackColor="CornflowerBlue"
    BackSecondaryColor="CornflowerBlue" />
</Chart>  

For more sample presentation description XML strings, see Sample Charts.

Methods and properties supported in Unified Interface

The following section shows the methods and properties that are supported in Unified Interface:

AxisX

Gets or sets the X-axis type of the series.

Properties

Property Name Description
Enabled Gets or sets a value that indicates whether an axis is enabled.
LabelStyle Enabled Gets or sets a flag that indicates whether the label is enabled.
LabelStyle ForeColor Gets or sets the color of the label.
LabelStyle Format Gets or sets the formatting string for the label text. Learn more about Supported numeric format for charts
LineColor Gets or sets the line color of an axis. Learn more about Supported color format
IsReversed Gets or sets a flag which indicates whether the axis is reversed.
If set to true, it has two effects for x-axis:
- x-axis labels are flipped in the reversed order (from right-to-left)
- It also brings the y-axis to the opposite side, to accommodate above right-to-left x-axis label.
MajorGrid Enabled Gets or sets a flag that determines whether major or minor grid lines are enabled.
MajorGrid LineColor Gets or sets the line color of a grid. Learn more about Supported color format
MajorTickMark Enabled Gets or sets a flag that determines whether major grid lines are enabled.
MajorTickMark LineColor Gets or sets the line color of a grid.
Title Gets or sets the title of the axis.
TitleForeColor Gets or sets the text color of an axis title. Learn more about Supported color format

Tip

  • When there are too many LABELS, HighCharts omits every second label and tries to render again. A quick work around is to either remove the records, or zoom out the browser.

Example

<AxisX Enabled="True"
  LineColor="165, 172, 181"
  Title="Test XAxis Title"
  TitleForeColor="91,151,213"
  IsReversed="true">
  <MajorTickMark LineColor="165, 172, 181"
    Enabled="true" />
  <MajorGrid LineColor="green"
    Enabled="true" />
  <LabelStyle ForeColor="red"
    Format="#,0,.##K"
    Enabled="true" />
</AxisX>

AxisY

Gets or sets the Y-axis type of the series.

Properties

Property Name Description
AxisY2 Gets or sets an Axis object that represents the secondary Y-axis.
- Second Y-axis only applies to multiple series chart.
- If you create multiple series chart with the chart editor, by default, the YAxisType=Secondary property is added to the second series of your chart, and a AxisY2 node is added to the XML.
- If you want another series to be measured by second Y axis, you can move the YAxisType=Secondary to that series node.
- If you don't want a second Y axis, you can delete the YAxisType=Secondary.
- If a Y Axis (either primary or secondary) measures more than one series, title won't be added to that Y Axis, because Y Axis title doesn't know which series to display.
Enabled Gets or sets a value that indicates whether an axis is enabled.
Interval Gets or sets the interval of an axis.
LabelStyle Enabled Gets or sets a flag that indicates whether the label is enabled.
LabelStyle ForeColor Gets or sets the color of the label.
LabelStyle Format Gets or sets the formatting string for the label text. Learn more about Supported numeric format for charts
LineColor Gets or sets the line color of an axis. Learn more about Supported color format
MajorGrid Enabled Gets or sets a flag that determines whether major grid lines are enabled.
MajorGrid LineColor Gets or sets the line color of a grid. Learn more about Supported color format
MajorTickMark Enabled Gets or sets a flag that determines whether major grid lines are enabled.
MajorTickMark LineColor Gets or sets the line color of a grid.
Maximum Gets or sets the maximum value of an axis.
Minimum Gets or sets the minimum value of an axis.
Title Gets or sets the title of the axis.
TitleForeColor Gets or sets the text color of an axis title. Learn more about Supported color format

Example

<AxisY Enabled="True"
  LineColor="165, 172, 181"
  Title="Test YAxis Title"
  TitleForeColor="91,151,213"
  Interval="1"
  Minimum="0"
  Maximum="5">
  <MajorTickMark LineColor="165, 172, 181"
    Enabled="true" />
  <MajorGrid LineColor="green"
    Enabled="true" />
  <LabelStyle ForeColor="red"
    Enabled="true" />
</AxisY>
<AxisY2 Enabled="True"
  LineColor="165, 172, 181"
  Title="Test YAxis2 Title"
  TitleForeColor="91,151,213"
  Interval="10"
  Minimum="0"
  Maximum="100">
  <MajorTickMark LineColor="165, 172, 181"
    Enabled="true" />
  <MajorGrid LineColor="green"
    Enabled="true" />
  <LabelStyle ForeColor="red"
    Enabled="true" />
</AxisY2>

Chart

The root class for the charts.

Properties

Property Name Description
PaletteCustomColor Gets or sets an array of custom palette colors. It follows the priority as shown below:
- Renders the color defined in the Series node.
- If the color palette is specified, chart picks the color from the color palette.
- If none is specified, it picks up the default color palette. Learn more about Supported color format

Example

<Chart
  Palette="None"
  PaletteCustomColors="91, 151, 213; #4169E1, red, 127,97,142,206"
></Chart>

ChartArea

Represents a chart area on the chart image.

Properties

Property Name Description
Area3DStyle Enable3D Gets or sets a value that indicates whether the flag toggles the 3D on and off for a chart area. It supports the following 3D chart types:
- 3D Column
- 3D Bar
- 3D StackedColumn
- 3D StackedBar
- 3D StackedColumn100
- 3D StackedBar100
- 3D Pie
BackColor Allow users to set the plot background to either a solid or a gradient color. Learn more about Supported color format
BackSecondaryColor Allow users to set the plot background to either a solid or a gradient color. Learn more about Supported color format
BackGradientStyle Allow users to set the plot background to either a solid or a gradient color.

Example

<ChartArea BackColor="orange"
   BackSecondaryColor="purple"
   BackGradientStyle="LeftRight" >
  <Area3DStyle Enable3D="true" />
</ChartArea>

Legend

Represents the legend for the chart image.

Properties

Property Name Description
Enabled Defines whether the legend is enabled. By default it's set to True.

Example

<Legends>
  <Legend Enabled="True"/>
</Legends>

Series

Stores data points and series.

Properties

Property Name Description
BorderColor Gets or sets the border color of the data point. Learn more about Supported color format
BorderWidth Gets or sets the border width of the data point.
ChartType An enumeration value that indicates the chart type that is used to represent the series. The default value is Column. It supports the following chart types:
- Column
- StackedColumn
- StackedColumn100
- Bar
- StackedBar
- StackedBar100
- Area
- StackedArea
- StackedArea100
- Line
- Pie
- Funnel
- Tag
- Doughnut
- Point
Color Gets or sets the color of the data point. For funnel and pie charts, the color property defined in the series node is ignored, but picks the chart color from color palette. Learn more about Supported color format
IsValueShownAsLabel Gets or sets a flag that indicates whether to show the value of the data point on the label.
CustomProperties Allows users to set FunnelNeckHeight and FunnelNeckWidth to customize funnel chart's shape. FunnelNeckHeight & FunnelNeckWidth represents the percentage. This parameter is only supported for funnel chart types.
IsVisibleInLegend Gets or sets a flag that indicates whether the item is shown in the legend.
LabelForeColor Gets or sets the text color of the label. Learn more about Supported color format
LabelFormat Gets or sets the format of the data point label. Learn more about Supported numeric format for charts
LegendText Gets or sets the text of the item in the legend. For funnel and pie charts, the legend displays each data point's value in a series. Instead of displaying the series name as a whole.
YAxisType Gets or sets the Y-axis type of a series. Only the second Y-axis is supported, not second X-axis.

Note

  • Currently, we partially support #PERCENT. #VAL and #TOTAL aren't supported in Unified Interface.
  • For non comparison charts, we support a maximum of five series (one category). For comparison charts, we only support one series and two categories.

Example

<Series>
  <Series ChartType="Column"
    Color="91, 151, 213"
    LegendText="Est Revenue"
    IsVisibleInLegend="True"
    BorderColor="red"
    BorderWidth="1"
    IsValueShownAsLabel="True"
    LabelFormat="$#,0,.##K"
    LabelForeColor="59, 59, 59">
  </Series>
  <Series ChartType="Column"
    Color="237, 125, 49"
    LegendText="Actual Revenue"
    IsVisibleInLegend="True"
    BorderColor="red"
    BorderWidth="1"
    IsValueShownAsLabel="True"
    LabelFormat="$#,0,.##K"
    LabelForeColor="59, 59, 59"
    YAxisType="Secondary">
  </Series>
</Series>

Supported color format in Unified Interface

Unified Interface supports the following color formats in chart presentation xml, which is compatible with web client:

  • RGB Decimal format: 97,142,206
  • RGB HEX format: #4169E1
  • ARGB Decimal format: 127,90,138,57
  • Browser recognized named colors: red, transparent

Supported numeric format for charts in Unified Interface

Formatting values Description
#,0 No scaling, No decimals, leading zero
#,0,.##K Thousands, up to two decimals, leading zero
#,0,,.##M Millions, up to two decimals, leading zero
#,0,,,.##B Billions, up to two decimals, leading zero
C Currency with default decimals
C0 Currency with no decimals
C2 Currency with two decimals
F0 Fixed point
#,0;(#,0);' ' No scaling, no decimals, leading zero, negative value shown in braces, suppress zeros
#,0,.##K;(#,0,.##K);' ' Thousands, up to two decimals, leading zero negative value shown in braces, suppress zeros
#,0,,.##M;(#,0,,.##M);' ' Millions, up to two decimals, leading zero negative value shown in braces, suppress zeros
#,0,,,.##B;(#,0,,,.##B);' ' Billions, up to two decimals, leading zero negative value shown in braces, suppress zeros
% Percent sign (%) in a format string causes a number to be multiplied by 100 before it's formatted

See also

Visualizations (Charts)
Actions on visualizations (Charts)
Create a chart
Query data using FetchXml
Visualization data description schema
Sample charts
Chart class (Microsoft Chart Controls)