Line chart widget

A line chart is an effective way to visualize data points along a line. It is commonly used to display trend data or compare two data sets. There are three types of line charts:

• Category: The horizontal axis represents labels (categories) for each value. This chart type is defined using data from a single entity.
• Linear: Numerical data is plotted for each point. The scatter chart type automatically configures a line chart to use one of these scales for the x-axis. Linear interpolation is used to position a value along the axis.
• Time: Points are defined with date-number pairs. The time scale is used for displaying dates. The ticks are automatically determined based on the scale’s size.

Category line chart #

The horizontal axis labels are derived from the values’ categories. This type of chart is built using data from a single entity.

Entity #

This refers to the entity that the view is associated with. Only records from this entity will be displayed in the line chart widget.

Label #

A human-readable name for the view. Special characters, spaces, and a mix of uppercase and lowercase letters can be used.

This label is displayed at the top of the widget view. Make sure it’s user-friendly.

Name #

The internal name of the view. It should not include special characters or spaces. You often use this view’s name in scripts and the REST API. Changing it might impact your app, necessitating manual adjustments.

Description #

A human-readable description of the widget. Special characters, spaces, and a mix of uppercase and lowercase letters can be used. Internationalization is possible.

This description appears at the top of the added widget on your dashboard.

Allow refresh #

This option controls whether to show or hide the refresh button. Enabling this allows users to update the widget’s information. It’s enabled by default.

List settings #

Dataset #

These settings define how the listing behaves.

Sort Field: The default sorting field for the listing. If allowed, users might change the default sorting by column.

Sort Type: The sorting direction. If allowed, users might change the default sorting by column.

Filter Type: Can be an expression or a script. For expression selection, set record filters. For the script selection, the script should be returned.

Record Filters: Defines which records are listed. Only records matching the given expression will appear in the table widget view.

Script: Returns a query parameter or queryMap. The query map object is used to filter records. See the Query Language documentation for query map usage.

Size: The maximum number of records to fetch when the view loads or when clicking “More” to fetch additional records.

Horizontal axis settings #

View type #

Specifies the field type used for generating 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 is stored as metadata reference, updating accordingly with changes.

Calculated field #

Generates field values by script for the horizontal axis.

Grid lines #

When set to false, grid lines for this axis are hidden.

Vertical axis settings #

Label #

A human-readable name displayed on the vertical axis. Special characters, spaces, and a mix of uppercase and lowercase letters can be used.

Ticks suggested min / max #

The suggestedMax and suggestedMin settings affect the data values used for axis scaling. They extend the axis range while maintaining auto-fit behavior.

Grid lines #

When set to false, grid lines for this axis are hidden.

Series #

You can add series based on entity fields or calculated series.

Entity field #

Allows selection of an existing entity field. The value is stored as metadata reference, updating accordingly with changes. The default value is effective when creating new records, not when editing existing ones.

Calculated field #

A field’s value generated by script for the vertical axis.

Line styling settings #

Settings Mode: Can be simple or advanced. In simple mode, only the line color needs setting; other settings are calculated or set by default. Advanced mode requires developers to define each value.

Color: Specifies the line color using a hexadecimal code.

Line Tension: Bezier curve tension of the line. Set to 0 to draw straight lines. Default value is 0.4.

Background Color: Fill color for the line. Use a hexadecimal code.

Border Width: Width of the line (in pixels).

Border Dash: Length and spacing of dashes.

Stepped Line: Supported values for stepped lines: None, Before, Middle, After.

Point styling settings #

Settings Mode: Can be simple or advanced. In simple mode, only the background color needs setting; other settings are calculated or set by default. Advanced mode requires developers to define each value.

Background Color: Fill color for points. Use a hexadecimal code.

Style: Point style, options include circle, cross, crossRot, dash, line, rect, rectRounded, rectRot, star, triangle.

Radius: Radius of the point shape.

Hover Background Color: Point background color on hover.

Border Width: Width of the point border (in pixels).

Border Color: Border color for points.

UI messages #

Widgets can respond to UI messages, such as data refresh or filter application.

Refresh and filter #

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

Additionally, you can send a filter parameter to apply it to the query used for data retrieval. The query can be a query object or a query map. If using a query object, the filter is applied only when the entity matches that set in the widget. Refer to the Query Language for more information.

To apply filters, set the widgetContainer with a list of objects, each describing the container name and the filter to be applied to each widget. The title can also be sent to update the widget title.

Example #

In this example, you can refresh and apply a filter by sending the filter parameter to a specified 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
    }
  ]   
});

Example #

Use case #

A line chart is designed by connecting a series of data points with a solid line. Examples of data types suitable for representation in a line chart include annual sales rates and monthly rainfall. This type of chart allows trends in the data to be clearly observed over a continuous period.

Precondition #

To set up information in a line chart, you need to have an entity. You can utilize a calculated entity to store aggregated information.

For instance, consider the entity salesInLastYear. It possesses a year-month field named period and an integer field named totalSales. This example assumes that the entity is calculated and is updated on a monthly basis.

Creating a Line Chart #

The following steps illustrate how to create a line chart:

• Step 1: Within the root layout of the designated dashboard, navigate to Assign Widget.
• Step 2: You can assign an existing widget or create a new one. In this scenario, we’re creating a new widget.
• Step 3: Provide a label and name for the new widget. Select Line Chart as the widget type and choose subtype category. Additionally, specify the salesInLastYear entity mentioned in the preconditions. Save the changes to proceed to widget configurations.
• Step 4: In the Dataset configuration, arrange the sorting information. In this example, the sorting should be based on the period field. This is where you can also filter information from the salesInLastYear entity.
• Step 5: Configure the continuous variable for the Horizontal Axis. In our case, this would be the period field. You can customize display options for the selected field and opt to show or hide grid lines as needed. Refer to the documentation for further details.
• Step 6: Customize settings for the Vertical Axis Settings, allowing adjustments to the vertical axis appearance. More information can be found in the documentation.
• Step 7: Under the Series node, you can add fields (series) representing measurement information. For instance, you can add a new series using the button in the secondary menu.
• Step 8: In the Model Settings, add the field representing the measure. In our example, this would be the totalSales field.
• Step 9: For the added series, you have the ability to customize colors for lines and points. Additionally, advanced options are available for more nuanced customization.

These steps guide you through the process of creating a line chart.