Bar chart widget

A bar chart provides a method of displaying data values using vertical bars. It is commonly employed to illustrate trend data and compare multiple datasets side by side.

Entity #

This refers to the entity that the view will target. Only records from this entity will be listed in the bar chart widget.

Label #

This is a human-readable name for the view. You can use spaces, special characters, and a mixture of upper and lower case letters.

This label will appear at the top of the widget view, so ensure you use language that users will understand.

Name #

This is the internal name of the view. It cannot contain special characters or spaces.

You will usually utilize the view’s name in scripts and the REST API. Changing it may impact your app, necessitating manual adjustments.

Description #

This is a human-readable description of the widget. You can use spaces, special characters, and a mixture of upper and lower case letters. Internationalization is possible.

This description will be visible at the top of the added widget in your dashboard.

Allow refresh #

This option determines whether the refresh button is displayed or hidden. This button facilitates the update of widget information. It’s enabled by default.

Filtering settings #

These settings define how the listing behaves.

Sort field #

This is the default sorting field for the listing.

Users might be able to alter the default sorting if that functionality is enabled in any of the columns.

Sort type #

This indicates the sorting direction.

Users might be able to change the default sorting if that’s enabled in any of the columns.

Filter type #

It can be either an expression or a script. If “expression” is selected, record filters should be set. Otherwise, a script should be returned.

Record filters #

This defines which records will appear in the list. Only records that match the given expression will be listed in the table widget view.

Script #

Returns a query parameter or queryMap. The query map object is used to filter records. For query map version, refer to the Query Language documentation.

Size #

The maximum number of records to fetch when the view is initially loaded and when clicking “More” to fetchadditional records.

Horizontal axis settings #

View type #

Represents the field type used to generate the horizontal axis values. It can be an entity field or a calculated field.

Entity field #

Allows selection of an existing entity field. The value will be stored as a reference to metadata, being updated similarly when changes occur. The default value applies only when creating a new record, thus having no effect on editing an existing record.

Calculated field #

Values for this type of field are generated by a script for the horizontal axis.

Horizontal bar #

Configuration options for the horizontal bar chart mirror those of the bar chart. However, options specified on the horizontal axis in a bar chart are applied to the vertical axis in a horizontal bar chart.

Grid lines #

If set to false, grid lines for this axis are not displayed.

Vertical axis settings #

Label #

This is a human-readable name displayed on the vertical axis. You can use spaces, special characters, and a mixture of upper and lower case letters.

Ticks suggested Min/Max #

The suggestedMax and suggestedMin settings adjust the data values used to scale the axis. These settings extend the axis range while maintaining the auto-fit behavior.

Grid lines #

If set to false, grid lines for this axis are not displayed.

Series #

You can add series based on an entity field or a calculated series.

Entity field #

Allows selection of an existing entity field. The value will be stored as a reference to metadata, being updated similarly when changes occur. The default value applies only when creating a new record, thus having no effect on editing an existing record.

Calculated field #

Values for this type of field are generated by a script for the vertical axis.

Bar styling settings #

Settings mode #

This can be either simple or advanced. In simple mode, only the bar color needs to be set; other settings are calculated or set by default. For advanced mode, developers define each value.

Background color #

This sets the line color. It should be a hexadecimal color code.

Border color #

The bar’s border color. It should be a hexadecimal color code.

Border skipped #

Indicates the edge to skip when drawing the bar.

Border width #

The bar’s border width (in pixels).

Hover background color #

The bar’s background color when hovered over.

Hover border width #

The bar’s border width when hovered over (in pixels).

UI messages #

Widgets can respond to UI messages. A common use case is when data needs refreshing or filters need applying.

Refresh and filter #

You can send a message to refresh the widget using its default settings. These messages are sent to the dashboard container and propagated to each widget.

Additionally, you can send a filter parameter to apply to the query used to retrieve data. This query can be a query object or a query map. When using a query object, the filter is only applied if the entity matches the one set in the widget. For more information, consult the Query Language.

To apply filters, set the widgetContainer with a list of objects. Each object describes the container name and the filter to be applied to each widget. You can also include title to update the widget title.

Example #

In the following example, you can refresh and apply a filter by sending the filter parameter to a specific widget container.

var query = sys.data.createQuery('salesInfoPeriod');
query.field('department').equals('Department A');

sys.ui.sendMessage({
  scope: 'view',
  name: 'refresh',
  views: ['salesDashboard'],
  widgetContainers: [
    {
        name: 'salesPerDepartment',
        filter: query
    }
  ]   
});