The Chart Canvas element's Series child elements cause a data visualization (the chart) to be rendered in the canvas. This topic discusses the Series.Bar element.
- About Series.Bar
- Using Multiple Series
- Using the Data Labels Element
- Using the Quicktips Element
- Using the Chart Drill To Element
- Using the Trend Line Element
- Using Action Elements
- Using Input Selection
- Using the Refresh Series Timer
The Series.Bar element generates a Bar chart, which uses either vertical or horizontal bars to show comparisons among categories.
The example above shows a simple Bar chart, representing sales per month by sales rep, in both vertical and horizontal orientations.
As shown above, the chart is created by adding Series.Bar to the canvas, along with a datalayer and, typically, some child elements that may include a Group Filter, and a Group Aggregate Column element. Very few attributes need to be set for the Series element in order to produce a basic chart.
Note that a datalayer element can be used either beneath Series.Bar, as shown above, or beneath Chart Canvas. If used as a child of Chart Canvas, its data is available to all child Series elements. This can improve performance if you have several series, all using the same data, beneath the same Chart Canvas element.
The properties of the X- and Y-axis, including captions, are set using the X-Axis and Y-Axis elements. For example, in order to angle the X-axis labels, add an X-Axis element beneath Chart Canvas (none of its attributes need to be set) and add its child Label Style element. Set the Label Style element's attribute as shown above.
You can add additional series to the chart by adding additional Series elements:
The example above uses three Series, one for each year, and two different "stacking modes" are shown, along with a legend. Overlay and StackedPercentage stacking modes are also available. Combinations of stacking modes are also possible, for example, two years stacked, and one year beside them. Note that the scaling of the data axis may change depending on the stacking mode.
The example above shows the two Series elements, their datalayers, and an X-Axis element used to produce the previous chart. You can adjust the order of the series in the chart and the legend by changing the order of the Series elements in the definition. Setting the Series elements' Legend Label attribute will automatically cause the legend to be displayed.
When using multiple series, you may be able to reduce the number of data queries and improve performance by using local data to read all of the data once, see Datalayer Introduction. Then, link its datalayer to share it to the series, see Link Datalayers. At each Series element, link its datalayer to the shared Local Data datalayer and filter the data to meet the needs of each individual series.
You can combine different types of Series elements, for example, Series.Bar and Series.Line, to produce combinations of visualizations. A good example of this is when you wish to use forecasting.
Forecasting elements use a variety of techniques to produce projected values by analyzing existing values. The future values they "predict" are, in most cases, added as rows or columns to a datalayer so the data can be displayed along with the existing data. When using Chart Canvas charts, the forecast data is typically displayed using a Series.Line element, in conjunction with other series elements.
Forecasting elements add a "forecast value" column to the datalayer, and this column is used as the series' Y-axis data column. For more information about using forecasting elements, see The Forecasting Elements.
The Series.Bar element has the following attributes:
|Y-Axis Data Column||(Required) Specifies the name of a datalayer column whose values will be plotted along the Y-axis.|
|Bar Border Color||Sets the color of the thin border line around each bar. Enter a color by name, decimal RGB value, or hex RGB value. Prefix hex values with the pound sign, e.g. #112233.|
|Bar Border Color Transparency||Specifies the transparency of the thin border line around each bar. The lowest value of 0 specifies that the background is opaque, with no transparency. At the other end of the scale, 15 specifies a completely transparent background. Use medium-level transparency to allow different chart layers to show through each other.|
|Bar Border Radius||Sets the amount of rounding for bar corners, in pixels. The default value is 0 pixels, which produces square corners.|
|Bar Border Thickness||Sets the thickness of the bar border lines, in pixels, when the related Bar Border Color attribute has a value. The default value is 1 pixel.|
|Bar Thickness||Sets the width of the bar in pixels. If left blank, the width will be determined automatically.|
|Color||Sets the bar fill color. Enter a color by name, decimal RGB value, or hex RGB value. Prefix hex values with the pound sign, e.g. #112233.|
|Combine With Series ID||Set this attribute to the element ID of another series to combine it with this series in the legend. When two series are combined, by default only the first one will appear in the legend but clicking the item in the legend toggles both series to appear and disappear. Or, the value Previous can be entered to combine this series with the previous series.|
|Disable Mouse Tracking||
Disables mouse tracking for the series, when set to True. This affects
tooltips and click events on graphs and points. For large datasets, this may
The default value is False.
|Hover Brightness||Specifies the amount to change a bar's color when the mouse pointer is hovered over it. Values can be between 0 (no change) and 15 (lighter). The default value is 2.|
|Legend Label||Indicates text that will be shown for this series inside the chart legend. When a value is provided, it automatically causes the legend to be displayed.|
|Linked to X-Axis ID||Specifies the ID of an X-Axis element that this series should be linked to when using multiple X-axes.|
|Linked to Y-Axis ID||Specifies the ID of a Y-Axis element that this series should be linked to when using multiple Y-axes.|
|Negative Color||Sets the color for negative values. Enter a color by name, decimal RGB value, or hex RGB value. Prefix hex values with the pound sign, e.g. #D5F484. The default value is Red.|
|Negative Color Transparency||Specifies the transparency of the Negative Color. The lowest value of 0 specifies that the background is opaque, with no transparency. At the other end of the scale, 15 specifies a completely transparent background. Use medium-level transparency to allow different chart layers to show through each other.|
|Negative Threshold||Sets the positive-negative value threshold, also called the "zero level" or "base level". The default value is 0.|
|Stack Group Name||Enables the grouping of multiple series in a stacked chart. Enter the same arbitrary string value in this attribute for each series to be stacked.|
|Stacking||Sets the bar stacking mode. SideBySide arranges the bars beside each other, Stacked stacks the series one above the other in a single bar, while StackedPercentage stacks the series, then raises the levels to 100 percent, showing the percentage for each series' value. Overlay draws the bars on top of each other (use Transparency to let them show through). All series don't have to use the same stacking mode - they can be mixed to provide hybrid arrangements, such as two stacked and one beside them. Leave blank for no stacking.|
|Transparency||Specifies the transparency of the data region fill color. The lowest value of 0 specifies that the background is opaque, with no transparency. At the other end of the scale, 15 specifies a completely transparent background. Use medium-level transparency to allow different chart layers to show through each other.|
|X-Axis Data Column||Specifies the name of a datalayer column whose values will be plotted along the X-axis.|
|X-Axis Data Column Type||Specifies the data type of the datalayer column named in the X-axis Data Column attribute. Options include Auto (the default), Text, Number, and DateTime. By default, X-axis data values that are DateTime type will be automatically distributed evenly across the time series. If you want to disable this behavior, set this attribute value to Text. In general, when working with a Bar chart, you'll typically want to reference your X-axis column as Text data. Bar Charts do not depict any correlation from one group of bars to the next. However, when applying a data type of Number or DateTime, the chart attempts to establish a correlation between the points on the X-axis. Since there is only a single point per bar, it improperly displays the bars. Since a Bar Chart does not have a correlation between points, using DateTime data as text will not impact your results and you can still format the X-axis to meet your desired layout.|
A "data label" is text shown near each data point that shows its value. When the Data Labels element is used as a child of Series.Bar, text representing the data values will appear on the chart:
By default, with a single data series, the data labels will appear outside the bar, as shown above, left. The Data Labels element has attributes that allow you to control the font family, color, size, and weight, the data format, border color, and positioning of the text. The example above, right, shows data labels placed inside the bars and rotated 90-degrees. When series stacking is being used, the default is for data labels to appear inside the bars.
The Data Labels element's color-related attribute values can be set using @Chart tokens.
By default, a "quicktip" is displayed when the mouse hovers near or over a data point:
The automatically-generated quicktip displays information for the X- and Y-axis, as shown above, left. However, you may want to display other information or format it differently, perhaps as shown above, right, which can be done by adding a Quicktip child element beneath Series.Bar and setting its attributes and child elements. Use @Chart tokens to include chart data in the quicktip.
When using stacked series, if each series has its own Quicktips child element, the data shown in the quicktip will vary depending on which stacked segment the cursor hovers over, as shown above. Intrinsic functions are supported in the Quicktip attributes.
The Chart Drill To element, a child of the Series element, enhances charts by allowing users to examine the data "behind" the chart.
The parent Chart Canvas element must have an ID attribute value in order to use the Chart Drill To element with it.
As shown above, when this element is being used, clicking a chart bar displays a list of columns. Selecting a column re-draws the chart so that only the data representing the clicked bar is shown, and the X-axis is changed to the selected Drill To column:
After drilling to a column, the user can click a button to "drill back", as shown above. It's also possible to continue drilling further down into the data (assuming the elements are configured for it). For example, we could click on the Munchen chart bar next and then select Customer ID to drill down to the customers in that city.
Chart Canvas Charts that use the Chart Drill To element can only have a single Series. The Drill Back button only appears when the mouse cursor is hovered over the upper right-hand corner of the chart.
As shown above, the Chart Drill To element drills into grouped data, so the datalayer used beneath the Chart Canvas Chart or Series element must be grouped using a Group Filter or Sql Group element. The example datalayer has been grouped on the ShipCountry column and Keep Grouped Rows = False. The Series itself has been configured so that its X-axis Data Column = ShipCountry and its Y-axis Data Column = gacFreight (the Group Aggregate Column that sums the Freight values).
Next, a Chart Drill To element has been added beneath the Series element, as shown above. Required child Drill To Column elements have also been added; they define the columns the user can select to drill into. They should be added and configured for columns that can be reasonably grouped, such as text-type columns with a limited number of unique values and date-type columns.
You must also configure a Drill To Column element for the column that's specified as the chart's X-axis Data Column, in this example the ShipCountry column.
The Column Header attribute specifies the text that will appear in the Drill to Column drop-down list options and will become the drilled chart's X-axis caption. The vertical order of the drop-down list options will match the vertical order of the Drill To Column elements in the definition. Year, Quarter, and Month options will be added automatically for Drill To Columns with Data Type = Date. You do not need to add any filter or additional grouping elements to achieve the results shown in the example above.
The Drill Back button displayed on the chart after drilling has occurred can be styled using the Drill Back Button Style element.
The Trend Line element creates a line on the chart that indicates the "trend" of the data. The line connects a number of data points generated using a regression algorithm.
The Trend Line element is a child of the Series.Bar element and can be styled for color, line width, etc. When configured with a legend label, it will be represented by an item in the legend, as shown above.
Action elements initiate processing of a report or process task definition, redirection to a link, or other processing when a data point in the series is clicked.
In the example above, an Action.Report element has been added as a child of the Series, along with its Target.Report and Link Parameters child elements. To reference chart data in parameters, use the @Chart token, as shown above. A variety of Action elements are available for use with Series, including Action.Link, Action.Process, and Action.Refresh Element. Additional Action elements will be added in future releases.
This series can also be used with the Input Selection family of elements, which turn the chart into an input control. This allows users, at runtime, to select points or values on the chart with their mouse and your report can then take action using the selected data. This is very useful, for example, for drilling into the data.
For more information about this functionality, see Input Selectiony.
The Refresh Series Timer, added as a Series child element, updates charts automatically, based on a time interval. When the interval is reached, a request is sent back to the web server for updated data. Series are updated with a smooth animation.
The Refresh Interval attribute specifies the number of seconds to wait before refreshing the series data. A value is required and must be an integer greater than 0.
Series may be refreshed in two ways: either all of the data is refreshed with each request, or the series data automatically slides to the left one data interval per refresh. The refresh mode is selected in the Chart X Axis element's Axis Type attribute.
When the Axis Type is not set to DateTimeLinear, all of the data will be refreshed.
When the Axis Type value is DateTimeLinear, newer values are added to the right side of the chart, previous values slide left, and older values disappear as they reach the left edge of the chart. In this case, the Refresh Series Timer element's Time Span attribute is used to specify the age of the data included. This value must be in hh:mm:ss format (for example "00:02:00"
for two minutes) and must be larger than the Refresh Interval attribute value.
When a Time Span attribute is set, the series' datalayer can make use of a special timestamp token, @Chart.rdTimeSpanStart~, in a query to retrieve just the rows necessary to update the chart. On the initial request, this token returns the current time minus the Time Span value. For subsequent refreshes, when Axis Type = DateTimeLinear and the X-axis will be sliding, the token returns the last time the chart was updated, so only the newest rows are retrieved. Here's an MS SQL Server query example:
- SELECT * FROM MyTable WHERE UpdateTime BETWEEN '@Chart.rdTimeSpanStart~' AND '@Function.DateTime~'
For best performance, avoid setting a very short refresh interval if a very large number of users will be displaying the report.