Liquid Fill Gauge


A liquid fill gauge shows progress towards a specified range as a liquid level: the higher the level, the larger the value, and the liquid carries a wave animation. Once a comparison field is added, several liquid fills can be arranged side by side to compare multiple groups of data.


../_images/liquid_fill_blue.gif


This topic describes the configuration items specific to the liquid fill. For the items common to all charts, such as the Basic tab and the Filter tab, see Common Configurations for Charts.

Types of Liquid Fill Gauge


When adding a widget, the Liquid Fill Gauge group provides the following options:

Preset

Style

Description

Recommended scenario

Basic Liquid Fill

 ../_images/basic_liquid_fill.png

A single liquid fill showing the progress of one measurement as a level.

Showing a water tank level, the remaining volume of a single tank, or the achievement rate of one project.

With Metric Card

 ../_images/liquid_fill_with_metric_card.png

A liquid fill combined with up to two metric cards. For the configuration method, see Donut Gauge with Metric Card.

Showing a level alongside a few key values.

With Comparison

 ../_images/liquid_fill_with_comparison.png

Split into several liquid fills by comparison field and shown side by side.

Comparing the remaining volume of each tank or the share of water use in each workshop.


The configuration panels of Basic Liquid Fill and With Comparison are identical; the only difference is that the latter comes with a Comparison data field preconfigured. You can add or remove the comparison field at any time after creating one, so the two presets convert into each other. The rest of this topic applies to both.


Note

With Metric Card is listed in this group, but it is the same widget as With Metric Card in the donut gauge group, only with Type preset to the liquid fill. Its configuration panel is entirely different from the liquid fill and the data and style descriptions here do not apply. See Donut Gauge with Metric Card.

Data of Liquid Fill Gauge


In a liquid fill, Measurement determines the liquid level and Comparison splits the widget into several liquid fills.

For common configuration such as the data source, category, data source parameters, aggregation, sorting, alias, and unit, see Common Configurations for Charts > Configuring Data.

Measurement


Measurement determines the height of the liquid level, and exactly 1 field is required. The measurement value is converted proportionally into a level between the minimum and maximum of the Axis Range: at the minimum the ball is empty, at the maximum it is full, and anything outside the range is clamped to empty or full.

Comparison


Comparison is optional and accepts up to 1 field. Once added, the data is grouped by the values of that field, each value produces its own liquid fill, and they are arranged side by side according to the rows and columns set in Layout.

Without a comparison field, the widget shows a single liquid fill and the Comparison Style section is hidden.

Style of Liquid Fill Gauge


The Style tab is organized into two sections, comparison style and metric style; there is no separate gauge style section. For common styles such as the title, widget padding, and background, see Common Configurations for Charts > Configuring Style.

Once the data fields are configured, the titles of the Comparison and Metric collapsible panels show the names of the selected fields automatically, which makes it easy to confirm which field you are configuring.

Comparison Style


This section is shown only once a comparison field has been added, and contains a Comparison collapsible panel with three items: Layout, Show “Expand”, and Value Font. Their meanings, defaults, and value ranges match the donut gauge. See Style of Donut Gauge > Comparison Style.

Metric Style


This section is shown only once a measurement field has been added, and contains one collapsible panel.

The following items have the same meaning and defaults as in the donut gauge and are not repeated here:


Only the items specific to the liquid fill, or those that differ, are described below.

Border


Controls the style of the outer ring of the liquid fill. Cleared by default.

  • Cleared: the outer ring is a 1 pixel thin line whose color comes from the page theme, sitting right against the ball.

  • Selected: the outer ring thickens to 3 pixels, takes the same color as the liquid, and leaves a 7 pixel gap from the ball, forming an outlined ring visually.

The liquid fill always has an outer ring; this option switches its thickness, color, and gap rather than showing or hiding it.

Axis Range


Min and Max specify the data range the liquid level corresponds to, with a default of 0 to 100. The measurement value is converted into a level within that range. The rules for empty boxes and boundary cases match the donut gauge. See Style of Donut Gauge > Axis Range.

Both boxes are text boxes, so besides a fixed number you can enter a placeholder and have the range controlled dynamically by parameters. For more information, see Configuring Dynamic Parameters.

Show As Percentage


Selected by default. When selected, the center shows the current value as a percentage of the axis range and the unit is replaced by a percent sign; when cleared, the raw measurement value and its unit are shown. It also determines the matching basis of Color Rules. See Style of Donut Gauge > Show As Percentage.

This option only changes the text at the center, not the liquid level, which is always converted from the axis range.

Fixed Water Level at 40%


When selected, the liquid level is fixed at 40% regardless of the measurement value, and the wave animation still plays. This suits scenarios where color alone conveys the status and the level does not need to express the value. Cleared by default.

This option only fixes the level; the value shown at the center is still the real data. Once selected, the level no longer reflects the measurement value.

Color Rules


Assigns a liquid color per value range, with solid and gradient colors supported. The rule structure is the same as Common Configurations for Charts > Color Rules. There are no rules by default, in which case the liquid uses the system default color.

Color rules apply to both wave layers of the liquid (the lower layer semi-transparent, the upper layer opaque). Once Border is selected, the outer ring takes the same color.


Note

The color of the center value is determined by Value Font and the background of the ball is always transparent; neither is affected by color rules.

Interactions at Runtime


The liquid fill behaves as follows at runtime:

  • Wave animation: The liquid rises and falls continuously, and it plays in the editor too. When the derived level is 0 and Fixed Water Level at 40% is cleared, the amplitude is 0 and the surface stays flat.

  • No counting up: The center value shows the final value directly, with no count-up animation.

  • Data retrieval: Without a comparison field, only the last record in the returned data is shown; with a comparison field, the last record under each comparison value is taken, and the liquid fills are arranged in the order the comparison values first appear in the returned data.

  • Multiple liquid fill arrangement: The liquid fills are arranged by the rows and columns of Layout and collapsed by default; when Show “Expand” is selected, the overflow can be viewed with Expand.

  • Hover tooltip: When the comparison label, value, unit, or name is too long it is truncated, and hovering the mouse shows the full text.

  • Value jump: Once Interaction Settings is configured, the center value becomes clickable; the comparison label does not support click interaction.

  • Adaptive size: The ball is always rendered as a perfect circle, with the diameter taken from the smaller of the available widget width and height, leaving room for the comparison label and the name.

  • Empty state: When no measurement field has been added or no data is returned, an empty-state prompt is shown.

  • Invalid value: When the measurement value is not a number, the center shows -- and the ball is drawn with a 20% gray level (a 15% dark cyan level under the green theme) to distinguish it from a real 0.


Note