Time line chart widget

This section display settings available for time line chart widget that can be used in dashboard views.

A line chart presents data points on a continuous line, often used to display trends or compare two datasets.

There are three types of line charts:

  • Category: The horizontal axis features labels (categories) for each value. This chart type is defined from a single entity.
  • Linear: Numeric 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 determines the positioning of values on the axis.
  • Time: A point is defined using a date-number pair. The time scale displays date types. It dynamically calculates the most suitable time unit based on the axis scale.

Time chart

A time chart is defined using date-number pairs. The time scale is utilized for displaying date types. The chart automatically determines the most suitable time unit for creating ticks based on the scale size.

This type of chart is designed for a list of series. Each series is based on an independent data source, with date-number points specified for the axis.

Label

This is a user-readable name for the view. You can utilize spaces, special characters, and a mix of uppercase and lowercase letters.

This label will appear at the top of the widget view, so ensure it is easily understandable to users.

Name

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

You’ll often use the view’s name in scripts and the REST API. Changing it may impact your app, requiring manual adjustments.

Description

This is a user-readable description for the widget. You can include spaces, special characters, and a mix of uppercase and lowercase letters. Internationalization is supported.

This description will be displayed at the top of the added widget on your dashboard.

Auto refresh

Toggle this option to show or hide the refresh button. Enabling it allows updating the widget’s information. It’s true by default.

Horizontal axis settings

Label

This is a user-readable name for the view. You can use spaces, special characters, and a mix of uppercase and lowercase letters.

This label will appear below the horizontal axis.

Grid lines

Toggle grid line visibility for this axis.

Vertical axis settings

Label

This is a user-readable name for the view. You can use spaces, special characters, and a mix of uppercase and lowercase letters.

This label will appear next to the vertical axis.

Ticks suggested Min/Max

The suggestedMax and suggestedMin settings alter the data values used to scale the axis. They expand the axis range while maintaining automatic fitting behavior.

Grid lines

Toggle grid line visibility for this axis.

Series

Dataset

These settings determine how the data source collects information.

Entity: This is the entity the view references. Only records from this entity will be listed to define the horizontal and vertical axes.

Filter Type: Can be expression or script. For expressions, set record filters. For scripts, return the query parameter.

Filters: Specify which records will be listed. Only records matching the given expression will appear in the table widget view.

Script: Return query parameter or query map. The query map object is used to filter records. Check the Query Language documentation for query map details.

Size: The maximum number of records fetched when the view is loaded or when clicking “More” to load more records.

Sort Field: Default sorting field for the listing. Users might change default sorting if enabled in any column.

Sort Type: Sorting direction. Users might change default sorting if enabled in any column.

Point settings

Horizontal value

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

Entity Field: Select an existing entity field. The value is metadata referenced and updated with changes.

Calculated Field: Value generated by script for the horizontal axis.

Vertical value

View Type: Represents the field type used to generate vertical axis values. It can be an entity field or a calculated field.

Entity Field: Select an existing entity field. The value is metadata referenced and updated with changes.

Calculated Field: Value generated by script for the vertical axis.

Point styling settings

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

Background Color: Fill color for points in hexadecimal.

Style: Point style, such as circle, cross, rect, star, etc.

Radius: Radius of the point shape.

Hover Background Color: Point background color when hovered.

Border Width: Point border width in pixels.

Border Color: Point border color.

Line styling settings

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

Color: Line color in hexadecimal.

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

Background Color: Line fill color in hexadecimal.

Border Width: Line width in pixels.

Border Dash: Length and spacing of dashes.

Stepped Line: Supported values: None, Before, Middle, After.

Example

Use case

This chart type is ideal for illustrating trends in various diseases over time, such as salmonella and campylobacter occurrences in the past year.

Precondition

You need entities to set up information for each series. Calculated entities are necessary for aggregated information. For instance, entities like salmonella and campylobacter with fields like period (date-year) and quantity (integer).

Creating a line chart

Here are the steps to create a line chart:

  1. Access the root layout of the desired dashboard, either in columns or rows, and go to Assign Widget.
  2. Choose an existing widget or create a new one. In this case, let’s create a new widget.
  3. Enter the label and name for the new widget, set the widget type as Line Chart, and subtype as Linear. Save changes to proceed to widget configurations.
  4. Customize the axis settings under Horizontal and Vertical Axis Settings as needed.
  5. Add new series for each disease. Define the label to identify the disease and configure the dataset source. For instance, configure the entity source like salmonella, and set filter and order conditions.
  6. Define the date-number point. For horizontal value, select period entity field; for vertical value, select quantity entity field. Customize point style.
  7. Customize the line style or use default values.
  8. Repeat steps 5, 6, and 7 to add a new series for campylobacter.

UI Messages

Widgets can react to UI messages, commonly used for refreshing data or applying filters.

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 include a filter parameter to be applied to the data query. This query can be a [query]({{site.baseurl}}/app

-development-js-api-data.html#sys.data.Query) object or a query map. The filter is applied only if the entity matches the widget’s entity. Refer to the Query Language for details.

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

For line charts with multiple series from different entities, the filter parameter is an array of objects, each describing the series name and the filter to apply exclusively to that series.

Example

In the following example, you refresh and apply a filter by sending the filter parameter to the given widget container. Note how each series defines its own query and applies it to a specific entity.


var query = sys.data.createQuery('chinaInfo');
query.field('date').greaterOrEquals('2020-01-28');

var query2 = sys.data.createQuery('chinaInfo');
query2.field('date').greaterOrEquals('2020-01-28');

sys.ui.sendMessage({
  scope: 'view',
  name: 'refresh',
  views: ['technicalDashboard'],
  widgetContainers: [
    {
      name: 'chinaInfo',
      filter: [
        {
          name: 'cases',
          filter: query
        },
        {
          name: 'deaths',
          filter: query2
        }
      ]
    }
  ]
});
Edit this page on GitHub
← Linear line chart widget
Bar chart widget →