Charts

Introduction

The Charts widget enables plotting and comparing your data across different charts.

For more examples of what Charts widgets can do, see the following documents:

• Create a Basic Chart
• Use Any Chart
• Fine-Tune a Chart with Advanced Settings
• Use the Charts Theme
• Create a Dynamic Series Chart
• Use a Chart with a REST Data Source
• Use the Plotly Images REST Service Endpoint

These are the available charts:

• Column chart
• Line chart
• Pie chart
• Area chart
• Bar chart
• Time series chart
• Heat chart
• Bubble chart

Common Chart Properties

Data Source

Series

The Series property makes it easy to configure, control, and modify a chart series:

You do not need to put a chart into a data view to feed data into a widget. When you click the New button on a series panel, the Edit Series dialog box will be shown:

In this dialog box you will find these properties:

• Data set
  • Single – This represents controls for a single set of dates. This is good option to start with, as you can have multiple Single series.
  • Multiple – This is useful if you have a more complex data model or a microflow which could be used as data source for your chart. In this case you must specify which attribute to use as the Series name, otherwise your widget will be unable to visualize your data correctly.
• Data source – This property controls your data set’s type and source. If you click Edit you will see a Data source edit dialog box where you specify the data series retrieval location.
• Group by – This is the attribute used to split items into groups (visible only when Data set is set to Multiple).
• Series name – This property controls the legend of a data series.
• X axis attribute – This is the attribute used to get a value for the X axis (visible only when Data source is set).
• Y axis attribute – This is the attribute used to get a value for the Y axis (visible only when Data source is set).
• Aggregation function – This attribute defines how data is aggregated when multiple Y values are available for a single X value.
• Tooltip hover text – This is the text template used to customize the message shown to user upon a cursor hovering over the series.

Beside the General tab you will find 3 more tabs in the Edit Series dialog box:

• Appearance – This lists properties which allow you to modify styling for the current data series. In most cases there will be color properties.
• Events – This lists possible event triggers.
• Advanced – This uses one field which will hold a JSON object with advanced configuration for this data series.

General

Enable Developer Mode

When set to Yes this property enables Developer mode for the selected chart. After enabling Developer mode you will see a Toggle Editor button. When clicked, this button opens the Chart settings panel:

This developer mode panel is a live settings editor, meaning that your changes will be instantly applied to the current chart.

At the top of the panel there is a drop-down list which shows the currently selected settings group. By default each chart has a Layout group and Configuration group—these groups control chart and layout settings. Also, in this drop-down list you will find named groups that allow you to configure chart settings per series:

For more information on saving custom settings for a chart, see the Chart customization.

Show Legend

This setting controls the visibility of a chart’s legend block (highlighted in the picture above). If set to no, then the legend block is hidden.

X Axis Label and Y Axis Label

These two properties control labels for the X and Y axis respectively.

Grid Lines

This property controls horizontal and vertical rulers of the chart:

• None – No rulers are visible.
• Horizontal – Only a horizontal ruler is visible.
• Vertical – Only a vertical ruler is visible.
• Both – Both types of rulers are visible.

Dimensions

Width Unit

This property controls the unit measuring the widget (it can be percentage or pixels).

Width

This property controls width of the widget.

Height Unit

This property controls the unit for measuring widget height:

• Percentage of width – Height is measured relative to widget width (use this mode to keep width and height in aspect ratio).
• Pixels – This uses pixels as height unit (a good option for most cases).
• Percentage of parent – Height is measured relative to a parent height property (only works when parent has height CSS property).

Height

This property controls height of the widget.

Advanced

Enable Theme Folder Config

If set to Yes this widget will try to load global chart settings specified in the theme/web/com.mendix.charts.json file. Before using this feature make sure this file is present in your app.

Custom Layout

Please, find more details in Custom Layout in customization section.

Custom Configurations

Please, find more details in Custom Configurations in customization section.

Chart-Specific Settings

Area Chart

Edit Series Item Dialog

Appearance

• Interpolation – Determines the line shape. Could be linear or curved. In linear mode dots will be connected using straight lines, in curved they will be connected using curved lines.
• Line style
  • Line – Draws a series as simple line.
  • Line with markers – Draws a line with markers on top of each dot.
  • Custom – Makes a custom line style for series.
• Line color – The color used to fill line for this data series.
• Area fill color – The color used to fill area for this data series.

Bar Chart

General

Bar Format

This setting controls the bar format. In the group format, bars go one below the other. In the stacked format, bars are stacked on top of one another forming one line.

Edit Series Item Dialog

Appearance

• Bar color – The color used to fill line for this data series.

Bubble Chart

Edit Series Item Dialog

General

• Bubble Size Attribute – This attribute controls bubble size for a given item in series.
• Auto Scale – If Yes then bubble size and proportions will be computed automatically (otherwise the value from Scale factor will be used).
• Scale Factor – This controls the scale factor of bubbles on a chart. This value will be used to determine the final bubble size by multiplying current scale factor value and value from the bubble size attribute.

Appearance

• Marker color – The color used to fill marker for this data series.

Column Chart

General

Column Format

This setting controls a chart’s format. In the group format, columns go one after another. In the stacked format columns from each series will be stacked on top of each other.

Edit Series Item Dialog

Appearance

• Column color – The color used to fill columns for this data series.

Heat Map

Data Source

Value attribute

The entity attribute used to retrieve value for z axis (aka heat).

Axis

X Axis Attribute

This is a value for a chart’s horizontal (x) axis.

X Axis Sort Attribute

The attribute to used when sorting items in series for horizontal axis.

Y Axis Attribute

This is a value for a chart’s vertical (y) axis.

Y Axis Sort Attribute

The attribute to used when sorting items in series for vertical axis.

General

Show Scale

If set to Yes then show scale on the right side of the chart.

Scale

Colors

Allow to specify list of colors to use in the heat map. Each item define color for value in percentage. At least two values needs to be specified, for 0% and 100%, else the default colors are used.

Smooth Color

If set to Yes then show scale as smooth gradient between two colors.

Show Values

If set to Yes then show value for each dot on chart.

Font Value Color

The font color to display values for each dot.

Line Chart

Edit Series Item dialog

Appearance

• Interpolation – This determines the line shape: linear or curved. In linear mode dots will be connected using straight lines, in curved they will be connected using curved lines.
• Line style
  • Line – Draws a series as a simple line.
  • Line with markers – Draws a line with markers on top of each dot.
  • Custom – A custom line style for a series.
• Line color – The color used to fill line for this data series.
• Area fill color – The color used to fill area for this data series.

Pie Chart

Data Source

Series Name

This property allows for an expression that when evaluated will return a unique name for a single series:

Value Attribute

The attribute used to retrieve value for an item in the series.

Sort Attribute

The attribute used to sort items in the series.

Slice Color

Text template used to get color value for an item. Can use attributes as parameters.

General

Hole Radius

A percentage between 0 an 100 indicating the radius of the hole in the pice chart relative to the chart itself. Defaults to 0.

Time Series

General

Show Range Slider

If set to Yes then show additional range control at the bottom of chart.

Edit Series Item Dialog

Appearance

• Interpolation – Determines the line shape. Could be linear or curved. In linear mode dots will be connected using straight lines, in curved they will be connected using curved lines.
• Line style
  • Line – Draws a series as a simple line.
  • Line with markers – Draws a line with markers on top of each dot.
  • Custom – Makes a custom line style for a series.
• Line color – The color used to fill line for this data series.
• Fill area – If set to Yes then fill area between data point and x-axis.
• Area fill color – The color used to fill area for this data series.

Chart Customization

Custom Series Settings

Our underlying graphics library has a flexible API which allows you to configure each series in a chart individually.

To navigate to a series’ custom settings, do the following:

1. Go to Chart settings > Data Source > Series.

2. Select the series you want to configure, then click Edit.

3. Open the Advanced tab and paste your custom series settings object there (in JSON format):

   

   

Custom Layout

This property allows you to save your custom Layout settings for this widget.

To save your custom settings that related to the Layout group, navigate to the Advanced tab and paste your JSON in Custom layout text area:

These layout settings will be passed to the underlying Plotly JavaScript library. To see available options and their description. Visit the Layout section of the Plotly Reference Guide.

Custom Configurations

This property allows you to save your custom Configuration settings for this widget.

This object will be merged with default settings and passed to the underlying Plotly JavaScript library. To see available settings and examples check the Configuration Options in JavaScript section of the Plotly Reference Guide.

Legacy Chart Widget Documentation

Introduction

The Charts widget enables plotting and comparing your data across different charts.

These are the available charts:

• Column chart
• Line chart
• Pie chart
• Area chart
• Bar chart
• Time series chart
• Heat chart
• Bubble chart

Basic Configuration

Line Chart

A Line chart (scatter chart) should have one or more series, each displaying commonly grouped data points.

A series’ data can be retrieved from the database, by a microflow, or from a REST endpoint:

1. Place the widget in a page within the context of an entity.
2. Select the either Static or Dynamic for the Series.
3. Select a Data entity for the chart values.
4. Select the Data source:
   • If the Data source selected is Database, optionally change the XPath constraint
   • If the Data source selected is Microflow, select a Microflow that returns the series values
   • If the Data source selected is REST endpoint, enter the REST URL
5. If you set a Dynamic series, this will retrieve all the chart series in one configuration. Add configurations for them on the Dynamic series tab.

Area Chart

The Area chart has data properties identical to those of the Line chart.

Column Chart

The Column chart has data properties identical to those of the Line chart. However, there is no support for the Date and time data type.

Bar Chart

The Bar chart has data properties identical to those of the Column chart.

Pie Chart

Unlike the chart types above, the Pie chart requires no series.

These are the properties for configuring Pie chart data:

• Data source tab
  • Entity (required) – the entity from which the data values will be retrieved
• Data points tab
  • Name attribute (required) – the attribute that contains the data point captions
  • Value attribute (required) – the attribute that contains the data point values
  • Color attribute (required) – the attribute that contains the data point colors
  • Sort attribute – the attribute to use for sorting the X-axis data

Time Series Chart

The Time series chart is a specialised version of the Line chart, focusing on the X-axis dates. Therefore, it has data properties identical to those of the line chart.

Heat Map

The Heat map should be configured with required horizontal, vertical, and data attributes.

The sample domain model could be either of the two configurations below:

Bubble chart

The Bubble chart has data properties identical to those of the Line chart. However, the Bubble size data attribute is required, as it contains and determines the size of the bubble.

Advanced Configuration

The charts in this widget are based on the mendixlabs/charts library. As such, the widget provides support for advanced users to extend or overwrite the basic settings by adding the chart properties as JSON.

To enable this feature, go to the Mode option in the Advanced properties tab. For the Line chart and Column chart, each series has its own Advanced tab for specialized configurations.

The available advanced options and their usage are described below.

Layout Options for All Charts

The layout options control the general appearance of a chart. Common options include title, showlegend, xaxis, and yaxis.

{
  "showlegend": true,
  "legend": {
    "orientation": "h",
    "y": "auto"
  }
}

Configurations Options for All Charts

Configuration options control the appearance of a chart beyond the layout options. Common options include displayModeBar and doubleClick.

{
  "displayModeBar": true,
  "doubleClick": true,
  "displaylogo": false
}

For more details, see the Advanced Configuration Settings.

Data Options for the Pie Chart

On the Pie chart, the data options control the appearance of the pie circle beyond the general layout options. Options include hole, name, and marker.

{
  "hole": 0.5
}

For more details, see the Advanced Configuration Settings.

Series Options for the Line and Column Charts

The series options control the appearance of a specific series on the Line chart and Column chart. Options include line color and line shape.

For the full Plotly API reference, see JavaScript Figure Reference.

Theme-Based Advanced Configuration

The settings above can also be added in a global context via the theme folder of your Mendix app root directory.

Add a .json file named com.mendix.charts to the theme folder. The JSON should be in the following format:

{
  "layout": {
    // Add shared layout options here (for all charts)
  },
  "configuration": {
    // Add shared configuration options here (for all charts)
  },
  "charts": {
    "LineChart": {
      "layout": {
        // Add line chart only layout options here
      },
      "data": {
        // Add line chart only data options here
      },
      "configuration": {
          // Add line chart only configuration options here
      }
    },
    "AreaChart": {
      // Same arrangement as the line chart
    },
    "BubbleChart": {
      // Same arrangement as the line chart
    },
    "TimeSeries": {
      // Same arrangement as the line chart
    },
    "ColumnChart": {
      // Same arrangement as the line chart
    },
    "BarChart": {
      // Same arrangement as the line chart
    },
    "PieChart": {
      // Same arrangement as the line chart
    },
    "HeatMap": {
      // Same arrangement as the line chart
    }
  }
}

Read More

• Charts Configuration