DataMatrix Portlet

This portlet allows you to display additional information below a stacked column chart in form of a “data matrix”.

1 Required Data
2 Portlet
3 Independent Generation

Required Data

In order to generate the portlet you need to provide the following information:

Main series data. Each series should contain:
- Name – Displayed on hover and in the legend below the chart.
- Values (in form of a list)
Data matrix series data. Each series should contain:
- Name – Displayed on the left, below the main Y axis title.
- Values (in form of a list) – The number of values should equal to the number of categories on the X axis.
Axis height – Defines the amount of space that should be taken by a data matrix row. It is a percentage value (0–100).
X Axis Categories – Defines the categories used on the X axis.
Chart title – Defines the title of the portlet.

The data should be passed to the portlet generation method in the following map form:

[mainSeries      : [[name: "John",
                     data: [5, 3, 4, 7, 2]],
                    [name: "Jane",
                     data: [2, 2, 3, 2, 1]],
                    [name: "Joe",
                     data: [3, 4, 4, 2, 5]]],
 dataMatrixSeries: [[name: "Male(2nd)",
                     data: [8, 7, 8, 9, 7]],
                    [name: "Female(3nd)",
                     data: [8, 7, 8, 9, 7]]],
 axisHeight      : 10,
 xAxisCategories : ['Apples', 'Oranges', 'Pears', 'Grapes', 'Bananas'],
 yAxisTitle      : "Total fruit consumption",
 chartTitle      : "Stacked chart with mock data matrix below"]

Portlet

The above definition will generate the following portlet:

Independent Generation

It is possible to use just parts of the portlet. The element contains methods that will allow the user to reuse parts of the portlet functionality. The methods are:

prepareDataMatrixSeries()
- Parameters
  - axisTitle – Name to be displayed on the left side of the series.
  - axisHeight – Height of the data matrix row.
  - seriesId – ID of the row. Starting with 0. Allows to properly set the "top" height value.
  - seriesData – List of values for the data matrix row.
  - xAxis – Highchart definition of the xAxis.
  - axisOffset – Allows you to set the offset from left side of the chart for a given data matrix row. Can be useful when axisTitle is long.
- Result – Highchart definition of a singular data matrix row.
prepareDataMatrixAxis()
- Parameters
  - axisTitle – Name to be displayed on the left side of the series.
  - axisHeight – Height of the data matrix row.
  - seriesId – ID of the row. Starting with 0. Allows to properly set the "top" height value.
  - axisOffset – Allows you to set the offset from left side of the chart for a given data matrix row. Can be useful when axisTitle is long.
- Result – Highchart definition of a singular data matrix row axis that can be attached to a custom data series. The series data if properly configured will be displayed as a matrix row.

Additionally, if you decide to completely abandon the idea of using the out-of-the-box portlet functionality, these are the properties that (if used) lead to the data matrix behavior:

Axis:
- top – In this example it is set to 100% (height of axis * seriesId) but you can experiment with the values.
- title.rotation – Allows you to change the orientation of axisTitle to horizontal instead of vertical.
- min – If set to 0, you get rid of the scale.
- max – If set to 0, you get rid of the scale.
- gridLineWidth – If set to 0, you get rid of the grid lines.
- labels.enabled – If set to false, you get rid of axis labels that display the max and min values of the given axis.
- offset – Allows you to move the axis horizontally. It is useful when fine tuning the placement.
- height – Allows you to set up the total screen height the given axis should take. Use this to manipulate axis vertical placements.
Series (preferred type used for data matrix is column series):
- color – If set to white, you get rid of any display properties of the series and keep just the values .
- enableMouseTracking – If set to false, you get rid of tooltips and any other mouse events. It makes the data row feel more “static” and read only.
- showInLegend – If set to false, the data row series are not displayed in the legend.
- label.enabled – If set to false, series labels do not show.
- borderWidth – If set to 1, you get rid of the column series box borders (and together with white color you can make them invisible).

Tip: In order to get the best display results, consider preparing your data matrix series data in the following form [ y: 1, value: your value ]. Setting the y value to 1 makes the column really small, contributing to making it invisible.

Series Data Label:
- color – Setting this option to black clearly displays any data points, but any other color can be used as well.
- align – Setting this option to center displays the data point value in the middle of the “invisible” column, making a perfect alignment.
- format – Setting this option to <b>{point.value}</b> makes the value bold, therefore more visible.
Series Tooltip:
- enabled – If set to false, no tooltips are displayed, which is handy for a static, “read only” data matrix.