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 as well as non-numeric values whereas the series axis only displays numeric values.
Charts in model-driven apps can be further classified into the following:
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 are supported by Microsoft Chart Controls.
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 are 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 is not. 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 will contain 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>sub-element 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 will have 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 is no schema definition for this XML string. However, the XML is a serialization of the Chart class in Microsoft Chart Controls. More information: Chart Controls
You can specify the presentation description XML string while you are creating a chart using the SavedQueryVisualization.PresentationDescription or UserQueryVisualization.PresentationDescription for the organization-owned or user-owned chart, respectively.
Important
In Unified Interface, only a subset of properties are supported. More information: Supported methods and properties in Unified Interface
Example for web client
The following 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. More information: Supported numeric format for charts |
| LineColor | Gets or sets the line color of an axis. More information: 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 bring 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. More information: 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. More information: Supported color format |
Tip
- When there are too many
LABELS,HighChartsomits 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 will be added to the 2nd 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 1 series, title will not 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. More information: Supported numeric format for charts |
| LineColor | Gets or sets the line color of an axis. More information: 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. More information: 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. More information: 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. More information: Supported color format |
Example
<Chart Palette="None" PaletteCustomColors="91, 151, 213; #4169E1, red, 127,97,142,206">
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. More information: Supported color format |
| BackSecondaryColor | Allow users to set the plot background to either a solid or a gradient color. More information: 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 is 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. More information: 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. More information: 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. More information: Supported color format |
| LabelFormat | Gets or sets the format of the data point label. More information: 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.#VALand#TOTALare not supported in Unified Interface. - For non comparison charts, we support a maximum of 5 series (1 category). For comparison charts, we only support 1 series and 2 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 2 decimals, leading zero |
#,0,,.##M |
Millions, up to 2 decimals, leading zero |
#,0,,,.##B |
Billions, up to 2 decimals, leading zero |
C |
Currency with default decimals |
C0 |
Currency with no decimals |
C2 |
Currency with 2 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 2 decimals, leading zero negative value shown in braces, suppress zeros |
#,0,,.##M;(#,0,,.##M);' ' |
Millions, up to 2 decimals, leading zero negative value shown in braces, suppress zeros |
#,0,,,.##B;(#,0,,,.##B);' ' |
Billions, up to 2 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 is 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)
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for