Creating charts and tables in wiki pages
Introduction
Mingle supports support the creation of graphs, charts and tables in wiki pages, which query the Mingle database to display up-to-date project information graphically.
The wiki toolbar allows you to insert templates for graphs, charts and tables via the icons indicated below
Finding a wiki page
There are several ways within Mingle to find wiki pages to view, edit or delete, including:
-
from the Project admin tab Wiki pages link (full list of all wiki pages)
This page is also available by clicking on the Index of pages link in the Recently viewed pages control which is displayed when viewing any Wiki page.
-
from the recently viewed pages control which is displayed when viewing any Wiki page.
- links from other wiki pages
- links from within card descriptions
- directly from a URL, e.g. http://mingle.yourcompany.com/your project/wiki/wiki_name, where your project is your project identifier and wiki_name is the name of the wiki page
- from a Mingle search.
Creating Charts and Graphs
To create a chart or graph, you use a Mingle wiki macro. You can either type the macro in by hand, or insert a template macro using the toolbar and then edit it.
Types of charts
-
Data series chart - used to plot series of data line graphs
e.g. a burndown/burnup chart showing progress by iteration.
-
Stacked bar chart - used to plot series of data not only in bar charts, but also area charts and line graphs
e.g. a chart showing the count of cards in each state (New, In progress, Complete) by iteration.
-
Ratio bar chart - used to show what percentage of cards across the values of a single specified property meet certain conditions
e.g.
-
Pie chart - pie chart showing a percentage breakdown of all cards which meet the selection criteria, for each value of a single property
Data series chart
A burnup chart showing the number of points of scope for stories in each card status over time. Trend lines have been added to project into the future.
{{
data-series-chart
conditions: 'Type' = 'Story' AND NOT 'Iteration - Added' = NULL
labels: SELECT DISTINCT 'Iteration - Scheduled'
x-title: Iteration
y-title: Total Story Points
show-start-label: true
data-point-symbol: diamond
data-labels: true
cumulative: true
chart-height: 500
chart-width: 800
plot-height: 375
plot-width: 500
series:
- label: Total Scope
color: black
type: line
data: SELECT 'Iteration - Added', SUM('Estimate')
- label: Analysis Complete
color: green
type: line
trend: true
trend-line-width: 2
data: SELECT 'Iteration - Analysis Completed', SUM('Estimate') WHERE 'Status' = 'Ready for Development' and 'Iteration - Analysis Completed' IS NOT NULL
- label: Development Complete
color: orange
type: line
trend: true
trend-line-width: 2
data: SELECT 'Iteration - Dev Completed', SUM('Estimate') WHERE 'Status' = 'Development Complete' and 'Iteration - Dev Completed' IS NOT NULL
- label: Signed Off
color: blue
type: line
trend: true
trend-line-width: 2
data: SELECT 'Iteration - Accepted', SUM('Estimate') WHERE 'Status' = 'Accepted' and 'Iteration - Accepted' IS NOT NULL
}}
Preview
| Chart-level options | |||
|---|---|---|---|
| Name | Meaning | Required | Default value |
| three-d | One of [true/false] indicating whether to plot in a 3-d style | no | |
| x-title | Specify the title for the x-axis. Defaults to name of property that is driving the labels. | no | |
| y-title | Specify the title for the y-axis. Defaults to the aggregation of the first data series. | no | |
| chart-height | Specify the height of the entire chart (plot area plus legend) in pixels. | no | |
| chart-width | Specify the width of the entire chart (plot area plus legend) in pixels. | no | |
| plot-height | Specify the height of the plot area in pixels. | no | |
| plot-width | Specify the width of the plot area in pixels. | no | |
| cumulative | One of [true/false] indicating whether the data of each series accumulates or is stand-alone. Defaults to false. | no | |
| series | a list of the actual data series to be plotted. at least one series is required. Markup format is same basic format as stack-bar-chart. | yes | |
| conditions | MQL WHERE clause narrowing the the set of cards available to each series. | no | |
| x-labels-property | Allow user to specify a property for label values. Defaults to the property definition specified by the first data series. In either case, all values will be used as labels. | no | |
| x-labels-start | Allow user to specify the start value for labels on the x axis. Must be a valid, existing value for the x labels property. Defaults to first value for the x labels property. When x labels property is a date property, the value can be earlier than any existing value. Note that when plotting a cumulative chart, this parameter does not impact the scope of included cards in any data accumulation. I.e, this parameter only impacts the scope of what is drawn. Use the conditions parameter to restrict the cards to be accumulated. | no | |
| x-labels-end | Allow user to specify the end value for labels on the x axis. Must be a valid, existing value for the x labels property. Defaults to first value for the x labels property. When x labels property is a date property, the value can be later than any existing value. Note that when plotting a cumulative chart, this parameter does not impact the scope of included cards in any data accumulation. I.e, this parameter only impacts the scope of what is drawn. Use the conditions parameter to restrict the cards to be accumulated. | no | |
| x-labels-step | Allow user to specify that only every N labels should be displayed on the x-axis. This is useful when plotting against a property with many values, such as date properties. Default is 1, except in the case of date properties with more than 14 values, in which case the default is 7. | no | |
| x-labels-conditions | When charting against a card property, allow the user to specify conditions to narrow the set of cards to be used as x labels. Does not work when charting against text, numeric, or user properties. Use x-labels-start and x-labels-end to restrict the set of labels for those property types. | no | |
| show-start-label | One of [true/false] specifying whether to add a data point at the start of your series to show an implied starting point. This is especially useful when wanting to show a down-from line starting from the down-from value, or when wanting to show a line starting from 0. The default value is false unless any series specifies a 'down-from' parameter, in which case the default is true. The label can be set with the 'start-label' parameter. | no | |
| start-label | Any text to be used as the label when using the 'show-start-label' parameter. | no | |
| Chart-level options that can be overridden by any individual series | |||
| Name | Meaning | Required | Default value |
| chart-type | One of [line/area/bar] specifying how to draw each series. Default is line. Can be overridden by an individual series type. | no | |
| line-width | Line width for any series of type line. Default is 3. | no | |
| line-style | One of [solid/dash] specifying line style for any series of type line. Default is solid. | no | |
| trend | One of [true/false] specifying whether to plot each series' data beyond the point at which the series contains no new data. Defaults to false. Can be overridden by an individual series. | no | |
| trend-scope | Can be 'all' or an integer number. Specify the number of 'recent' data points (from the set of relevant data points-see trend-ignore) to be used in plotting the trend. Defaults to 'all.' Can be overridden by an individual series. | no | |
| trend-ignore | One of [none/zeroes-at-end/zeroes-at-end-and-last-value] specifying which data points at the end of the series to ignore when plotting the trend. The 'zeroes-at-end' option ignore all zeroes in the series beyond the last non-zero value. The 'zeroes-at-end-and-last-value' option ignores all zeroes in the series beyond the last non-zero value as well as that non-zero value, assuming that it's an 'in-progress' item. The 'none' option considers all data points in the series. The default is 'zeroes-at-end-and-last-value.' Can be overridden by an individual series. | no | |
| trend-line-color | Specifies the color of the trend line. Defaults to same color as actual data line. Can be overridden by an individual series. | no | |
| trend-line-style | One of [dash/solid] specifying the line's style. The default is dash. Can be overridden by an individual series. | no | |
| trend-line-width | Any integer number greater than 0 specifying the line's width. Can be overridden by an individual series. | no | |
| data-point-symbol | One of [none/square/diamond] specifying whether to plot the data points. Default value is 'none.' Can be overridden by a series. Only applicable to chart-type of 'line' | no | |
| data-labels | One of [true/false] specifying whether to show the value of each data point. Default value is 'false.' Can be overridden by a series. | no | |
| project | Any valid project identifier, specifying which project’s cards will be plotted by this chart. Authorization will be enforced upon view. That is, if a user does not have access to a project, that data series will not be included in the chart for that user. Default is the project to which the page or card containing the macro belongs. | no | |
| Series-level options | |||
| Name | Meaning | Required | Default value |
| line-width | Overrides chart-level setting. See chart-level description. | no | |
| line-style | Overrides chart-level setting. See chart-level description. | no | |
| label | Any text specifying name of series to be displayed in the legend. | yes | |
| color | And text specifying a standard web color indicating the color to be used when plotting the series. | no | |
| data | MQL SELECT clause specifying the property and aggregation (and optional WHERE clause) for this series. | yes | |
| type | Overrides chart-level 'chart-type' setting. See chart-level description. | yes | |
| data-point-symbol | Overrides chart-level setting. See chart-level description. Only applicable to type of 'line.' | no | |
| data-labels | Overrides chart-level setting. See chart-level description. | no | |
| project | see chart-level options | no | |
| down-from | MQL SELECT clause specifying a value from which this series will be plotted down from. This is how Mingle supports burn downs. E.g.
SELECT SUM WHERE 'Entered Scope Iteration' IS NOT NULL | no | |
| trend | Overrides chart-level setting. See chart-level description. | no | |
| trend-scope | Overrides chart-level setting. See chart-level description. | no | |
| trend-ignore | Overrides chart-level setting. See chart-level description. | no | |
| trend-line-color | Overrides chart-level setting. See chart-level description. | no | |
| trend-line-style | Overrides chart-level setting. See chart-level description. | no | |
| trend-line-width | Overrides chart-level setting. See chart-level description. | no | |
Stacked bar chart
Suppose you are tracking when cards enter scope, have been fully prepared for development, and are completed. You would like a chart that can display a running total of cards in each of those three states at the end of each iteration. To most effectively use the stack-bar-chart to display this sort of chart you will need to track three separate 'iteration' properties, each specifying when the card entered a particular state.
{{
stack-bar-chart
conditions: 'Release' = '2.0' AND 'Type' = 'Story' AND NOT 'Iteration' = NULL
labels: SELECT DISTINCT 'Iteration' ORDER BY 'Iteration'
cumulative: true
series:
- label: Closed
color: green
type: bar
data: SELECT 'Closed Iteration', COUNT(*) WHERE NOT 'Closed Iteration' = NULL
combine: overlay-bottom
- label: Anaylsis Complete
color: yellow
type: bar
data: SELECT 'Analysis Complete Iteration', COUNT(*) WHERE NOT 'Analysis Complete Iteration' = NULL
combine: overlay-bottom
- label: Entire Scope
color: blue
type: bar
data: SELECT 'Entered Scope Iteration', COUNT(*) WHERE NOT 'Entered Scope Iteration' = NULL
combine: total
}}
Preview
| Name | Meaning | Required | Default value |
|---|---|---|---|
| conditions | MQL condition clause that restricts the cards which will be included in all of the data series | No | If not specified, all cards will be considered for each series. |
| labels | MQL query that returns a list of values to be used as labels across the x-axis | No | If not specified, x-axis labels will be every value of the property selected in the first data series. |
| cumulative | Whether each data series includes all previous series. I.e., if a bar shows only data for that x-axis label, or a running total, including its own data and all previous bars. | No | TRUE |
| x-label-start | The first label that should be plotted on the x-axis. | No | If not specified, the first label value returned by the label query will be used. |
| x-label-end | The last label that should be plotted on the x-axis. | No | If not specified, the last label value returned by the label query will be used. |
| x-label-step | The number of labels to skip before the next data value is plotted. Use this to display every nth value if a set of labels. E.g., To show every 7th date in a series of dates rather than every date. | No | If not specified, the following defaults will be used depending on what kind of property is used on the x-axis. 5 days at a time for Date Properties. Every label value for others. |
| x-title | The title for the x-axis. Use this to override the default if there is a better name to explain what the labels represent. | No | If not specified, the property name of the series with a combine of 'total' series will be used. If no series is specified with a of 'total', the property of the very first series will be used. |
| y-title | The title for the y-axis. | No | If not specified, this will default to the property name of the first series. |
| three-d | If set to true, 3-d effects will be turned on. Data series of type bar will be shown as rectangular columns. Data series of type area will be shown in different layers, stacked one behind the other. Line graphs do not benefit much from 3-d effects. | No | FALSE |
| chart-width | The total width of the chart. This area includes the plot area, and any additional area used for labels and legends. | No | 400 |
| chart-height | The total height of the chart. This area includes the plot area, and any additional area used for labels and legends. | No | 300 |
| plot-width | The total width of the plotted area. Increasing this will increase the number of labels that can be clearly shown on the graph, but reduce the amount of area available for the legends. | No | 230 |
| plot-height | The total height of the plotted area. Increasing this will increase the height of the plot itself, but reduce the amount of area available for the labels. | No | 220 |
| series | A list of data series. Each series represents a portion of each bar on the bar chart. When type is set to area or line, each series represents a different chart line. (Note that each series need not select the same property for this chart to be meaningful. Each series must select data that is of the same type and same scale, but not the exact same property.) | Yes. At least one series must be specified. | |
| series label | The name of this series to appear in the chart's legend | No | |
| series color | A hex string or standard web color to be used when rendering a series | No | |
| series data | A MQL query that selects property values and an aggregation of those values. The property values will be used to group the aggregation. The aggregation represents how much of the bar will be represented by this series. | Yes | |
| series combine | How to combine the value of this series with the values of other series in a given bar. Valid values are total, overlay-top, and overlay-bottom. Use total to specify that a series represents the full height of the bar. Use overlay-bottom to have this series render in a stack, starting at the bottom of the bar. Use overlay-top to have this series render in a stack, starting at the top of the bar. | Yes | |
| series type | How to draw a series. Valid values are area, line, and bar. | No | bar |
| series hidden | Will the graph for this data series show up in the final graph? Use this to not show data series that are only used for calculation. This is similar to setting the series color to transparent. | No | FALSE |
Ratio bar chart
Display a bar chart with each bar showing the percentage of closed stories in a particular feature. In terms of card properties, what we want to show is this: for all cards with property 'Type' equal to 'Story,' calculate the percentage (based upon the SUM of the 'Size' property) of cards with property 'Status' equal to 'Closed.'
{{
ratio-bar-chart
totals: SELECT Feature, SUM(Size) WHERE Type = Story
restrict-ratio-with: Status = Closed
}}
Preview
| Name | Meaning | Required | Default value |
|---|---|---|---|
| totals | A MQL query returning the full scope of the chart. The MQL query must return a two column results set. The values in the first column will be the labels for the result set. The values in the second column represent the full height of the bars (the y-axis). | Yes | |
| restrict-ratio-with | A MQL condition that represents the portion of each bar to be filled in with color. The results of the totals parameter represent 100% of the height. | Yes | |
| color | A hex string representing the color of the bars. Can optionally be any standard web color name. | No | LightBlue |
| x-title | The title for the x-axis. Use this to override the default if there is a better name to explain what the labels represent. | No | If not specified, the name of the first property in the totals query will be used. |
| y-title | The title for the y-axis. | No | If not specified, this will default to the property name of the property being plotted in the totals query. |
| three-d | If set to true, 3-d effects will be turned on. The data will be shown as rectangular columns. | No | FALSE |
| chart-width | The total width of the chart. This area includes the plot area, and any additional area used for labels and legends. | No | 400 |
| chart-height | The total height of the chart. This area includes the plot area, and any additional area used for labels and legends. | No | 300 |
| plot-width | The total width of the plotted area. Increasing this will increase the number of labels that can be clearly shown on the graph, but reduce the amount of area available for the legends. | No | 230 |
| plot-height | The total height of the plotted area. Increasing this will increase the height of the plot itself, but reduce the amount of area available for the labels. | No | 220 |
Pie chart
Display a pie chart showing a percentage breakdown of all bugs (cards with a property 'Type' set to 'Bug') by status
{{
pie-chart
data: SELECT Status, COUNT(*) WHERE Type = Bug
}}
Preview
| Name | Meaning | Required | Default value |
|---|---|---|---|
| data | MQL query returning the data to be represented by the pie chart. The query must return a two-column result set. The values in the first column represent the chart labels. The values in the second column represent the portion of the pie for that row. Aggregation is supported. | Yes |
Creating Tables
Table - based on a query
Display a table with two columns, name and number, with one row for each card that has a property 'Priority' set to 'Critical' and a property 'Release' set to 'Release One.' As usual, quotes are used only when grouping words with spaces in them.
{{
table
query: SELECT name, number WHERE Priority = Critical AND Release = 'Release One'
}}
Preview
| Name | Meaning | Required | Default value |
|---|---|---|---|
| query | A custom MQL query, the results of executing this query will be shown in the table. | One, and only one, of query or view is required. |
Table - based on a saved view
Render a table containing all cards that are a part of the view named 'Release One'. Quotes may be omitted if the view name does not contain any spaces.
{{
table
view: 'Release One'
}}
Preview
| Name | Meaning | Required | Default value |
|---|---|---|---|
| view | A previously saved card view, the contents of which will be shown in the table. | One, and only one, of query or view is required. |
Pivot table
Display a pivot table summing the estimates for in-scope stories by priority (cards of type 'Story' and property 'Story Status' is not set to 'Out of Scope') for each status. The table will not display any empty rows or columns, but will display a total for each status in the bottom row.
{{
pivot-table
conditions: not 'Story Status'= 'Out of Scope' and 'Type' = 'Story'
columns: 'Story Status'
rows: Priority
aggregation: SUM('Story Estimate - Original')
totals: true
empty-columns: true
empty-rows: false
}}
Preview
| Name | Meaning | Required | Default value |
|---|---|---|---|
| rows | The card property whose values make up the rows of the table | Yes | |
| columns | The card property whose values make up the columns of the table | Yes | |
| conditions | A custom MQL condition clause that restricts the cards which are to be aggregated | No | If not specified, all cards are aggregated. |
| aggregation | The database function to perform across all cards having the row and column values for a particular cell. The result of this function will display in the cell | No | COUNT(*) |
| empty-columns | Should the table contain empty columns | No | TRUE |
| empty-rows | Should the table contain empty rows | No | TRUE |
| links | Should the cell contain a link to a card list containing the cards specified by the cell's row and column values | No | TRUE |
| totals | Should column totals display | No | FALSE |
Wiki page layout
You can use one or two column layout blocks to organise information in a wiki page. In Mingle this kind of layout is often referred to as a dashboard.
You can take a look at this example project overview page to see how that might look with some charts and tables included.
One-column layout
To create a single column layout block, this will create a named section within a wiki page which spans the wiki page and encloses other wiki content.
{% dashboard-panel %}
{% panel-heading %} A heading for the layout {% panel-heading %}
{% panel-content %}
Some wiki content for layout
{% panel-content %}
{% dashboard-panel %}
Preview
Where you would substitute appropriate text and content for A heading for the layout, and Some wiki content for layout respectively. The layout content can include any other wiki formatting or content, however nesting layout blocks is not recommended except as part of a two-column layout.
Two-column layout
To create a two column layout block, this will create a set of named sections within a wiki page, organized into two columns of equal width.
{% two-columns %}
{% left-column %}
{% dashboard-half-panel %}
{% panel-heading %}Top left panel{% panel-heading %}
{% panel-content %}
Some content
{% panel-content %}
{% dashboard-half-panel %}
{% dashboard-half-panel %}
{% panel-heading %}Second left panel{% panel-heading %}
{% panel-content %}
Some content
{% panel-content %}
{% dashboard-half-panel %}
{% left-column %}
{% right-column %}
{% dashboard-half-panel %}
{% panel-heading %}Top right panel{% panel-heading %}
{% panel-content %}
Some content
{% panel-content %}
{% dashboard-half-panel %}
{% right-column %}
{% two-columns %}
Preview
Where you would substitute appropriate text and content for xxx left/right panel, and Some content. You can add multiple
{% dashboard-half-panel %}
blocks on each side of the layout.
Mixed column layout
This is an example of using both one-column and two-column layout blocks in the same page
{% dashboard-panel %}
{% panel-heading %} A heading for the layout {% panel-heading %}
{% panel-content %}
Some wiki content for layout
{% panel-content %}
{% dashboard-panel %}
{% two-columns %}
{% left-column %}
{% dashboard-half-panel %}
{% panel-heading %}Top left panel{% panel-heading %}
{% panel-content %}
Some content
{% panel-content %}
{% dashboard-half-panel %}
{% dashboard-half-panel %}
{% panel-heading %}Second left panel{% panel-heading %}
{% panel-content %}
Some content
{% panel-content %}
{% dashboard-half-panel %}
{% left-column %}
{% right-column %}
{% dashboard-half-panel %}
{% panel-heading %}Top right panel{% panel-heading %}
{% panel-content %}
Some content
{% panel-content %}
{% dashboard-half-panel %}
{% right-column %}
{% two-columns %}
Preview
