Best Practices

This article covers the best practices for building widgets in the widget builder and chart designer. Use this information to improve the widget’s ease of maintenance and updates in the Widget Builder, and optimize widget performance, visual impact, and usability on dashboards.

But First, Plan Your Custom Widgets

Before building your widget and designing its chart type, it’s important that you define:

• The problem you’re solving,

• The widget’s purpose,

• The target audience for choosing the right chart type.

For more information, see Planning Planning Custom Widgets - General Points.

Widget Building Best Practices

This section goes over the best practices for building widgets in the Widget Builder efficiently and effectively. These best practices enhance the widget’s performance in data fetching and facilitate future maintenance and updates.

These practices apply if you build your widget using the Widget Builder’s non-guided mode.

Build the Widget as You Would

Create the widget while learning, focusing on the functionality of the Widget Builder and without worrying about setting up the stages efficiently. You will revisit and optimize the widget’s stages later.

Preview Data at Each Stage

Before moving to the next stage, preview the data at the current stage to validate that expected results are generated.

Minimize Widget Stages Number

To optimize the widget’s performance in fetching and displaying data on a dashboard, it’s important to minimize the number of widget stages. To do so, look for repeated stages and consider combining them into a single stage.

The following sections outline the actions you can take to reduce the number of widget stages.

Remove Redundant Display Field Stages

If your widget has repeated Display Fields stages…

…ask yourself if you can create the calculated field in a single stage.

In this example, WORK_AGE is a calculated field created in the first Display Field stage; it’s used in the second Display Field stage in the expression of the calculated field AGE_GROUP:

• First Display Fields stage:

  

• Second Display Fields stage:

  

To combine both stages, replace the calculated field WORK_AGE with its corresponding expression in the expression of the calculated field AGE_GROUP:

This results in a single expression that calculates the AGE_GROUP:

Group without Fields for Total Records Count

If you want to get the total count of records in a dataset, do the following at the Group stage:

1. Don’t select any Group Fields.

2. Enter the desired caption for your grouping field.

3. In the code editor, enter sum(1), which will calculate the total number of records in the dataset.

Remove Consecutive Group Stages for Count Calculation

Adding a Group stage is often necessary to obtain counts of specific data fields, such as the number of open orders per warehouse, or the number of distinct physical pallets per area. It serves as a prerequisite step towards achieving that type of goal.

When consecutive Group stages are found to be contributing towards that goal, determine if a stage can be eliminated. To demonstrate this, let’s compare a bad practice with the good practice using the following example: the objective is to get the average number of lines per order number in warehouse 123ABC by manipulating this data collection:

ORDER_NUMBER	LINE_NUMBER	WAREHOUSE_CODE
A	1	123ABC
A	2	123ABC
A	3	123ABC
A	4	123ABC
B	1	123ABC
B	2	123ABC
B	3	123ABC
B	4	123ABC

Bad practice: The table shows a suboptimal approach in the widget builder stages, involving redundant group stages preceding the calculation of the average lines per order number.

Widget Builder Stages – Data Preview	Notes
Group	A first Group stage is added to group the data by WAREHOUSE_CODE and ORDER_NUMBER. The grouping NUMBER_OF_LINES gets the total number of lines per order number by using expression: sum(1)
Group	A second Group stage is added to group the records by WAREHOUSE_CODE. The groupings ORDER_COUNT and TOTAL_LINES get the total number of order numbers and lines respectively by using expression: sum(1)
Display Fields	The calculated field AVG_LINES_PER_ORDER gets the average number of lines per order number by using expression: divide(TOTAL_LINES,ORDER_COUNT)

Good practice: The table shows an improved approach in the widget builder stages, involving a single group stage that generates a list of unique order numbers for calculating the average lines per order number in the subsequent Display Fields stage.

Widget Builder Stages – Data Preview	Notes
Group	A Group stage is added to group the data by WAREHOUSE_CODE. The grouping ORDER_LIST creates a list of unique order numbers by using expression: buildArray(ORDER_NUMBER) The grouping NUMBER_OF_LINES gets the total number of lines of all orders by using expression: sum(1)
Display Fields	The calculated field DISTINCT_ORDERS gets the total number of distinct order numbers in the list (i.e., ORDER_LIST) by using expression: sizeOfArray(ORDER_LIST) The calculated field AVG_LINES_PER_ORDER gets the average number of lines per order by using expression: divide(NUMBER_OF_LINES,sizeOfArray(ORDER_LIST))

Key Takeaways

When building widgets, keep in mind the following three pillars of a minimized number of widget stages:

Join Collection: Bring the First Data Collection to its Final State Before the Join Operation

To join two data collections effectively, finish building the first collection based on your specifications before starting the join operation. For example, let’s say you have a collection of 100 order records and want to determine the number of orders per warehouse. However, the collection uses less informative warehouse codes like 123ABC, while another collection has more intuitive codes like REGION17. The goal is to join these collections, obtaining the desired number of orders per warehouse that are presented with intuitive names.

To achieve this goal, follow these steps:

1. Group the rows by warehouse in the first collection to obtain the total number of orders per warehouse.

2. Join the first collection with the second collection.

This practice ensures that the join operation is performed on a smaller subset of data, which results in an optimized widget performance.

Chart Design Best Practices

For certain chart types, follow these best practices to optimize their visual impact and usability.

GridBar Chart

Remove pagination Removing pagination enables infinite scrolling; it lets users move through the Grid quickly. For more information, see Removing Grid Pagination.

Rename columns based on target audience Renaming the field columns with names that your target audience uses can improve the widget’s readability. For more information, see Renaming Grid Columns.

Consider grouping rows by default Grouping rows by default can let users get the detailed information immediately. To determine if the grid should be configured this way and to set it up, see Grouping Rows by Default in Grid Widgets.