WaterfallTile Documentation

Overview

The WaterfallTile component is a visualization tool designed for displaying cumulative data changes over time, highlighting increases and decreases. This visualization is particularly useful for understanding how different components contribute to a total by illustrating the sequential impacts on a starting point—ideal for financial data, project progress tracking, and similar applications.

Settings

height

• Input Type: Numeric
• Description: Specifies the height of the tile. Adjusting this value will directly affect the vertical space the tile occupies, impacting visibility, especially in a dashboard setting.
• Default Value: Not specified (must be provided in the configuration).

width

• Input Type: Numeric
• Description: Defines the width of the tile. This setting controls the horizontal layout within the dashboard, affecting how compact or spacious the displayed data will be.
• Default Value: Not specified (must be provided in the configuration).

data

• Input Type: Array
• Description: The dataset used to populate the waterfall chart. The data should consist of objects with specific fields mapped for labels and values. If the primary data source is unavailable, this static data is utilized.
• Default Value: An empty array [].

title

• Input Type: String
• Description: The main heading displayed at the top of the tile. This typically describes the data being shown and helps users quickly understand the focus of the visualization.
• Default Value: Not specified (must be provided in the configuration).

subtitle

• Input Type: String
• Description: A secondary text line under the title that can provide additional context or information about the displayed data.
• Default Value: Not specified (optional).

footerText

• Input Type: String
• Description: Text shown in the footer of the tile, allowing for additional notes, references, or source information.
• Default Value: Not specified (optional).

footerColor

• Input Type: String (Hex Color Code)
• Description: Defines the background color of the footer area of the tile. This can enhance visual hierarchy and improve readability by differentiating sections.
• Default Value: Not specified (optional).

dataRefIds

• Input Type: Array
• Description: An array of references used for fetching data from workflows. These reference IDs help in locating the necessary datasets, especially in cases where the data is dynamically sourced.
• Default Value: An empty array [].

fieldMapping

• Input Type: Object
• Description: Maps fields in the dataset to corresponding properties expected by the waterfall logic. This is crucial for extracting correct labels and values from the input data.
  • Sub-properties:
    • _series: An array of series items with configurations for labels and values.
• Default Value: An empty object {}.

waterfallMode

• Input Type: Dropdown
• Description: Allows the user to select the mode of visualization:
  • Options: delta, balance
  • Effect: Changes the aggregation logic of the displayed data to represent either cumulative differences or a balanced view of overall value changes.
• Default Value: delta.

sentiment

• Input Type: Dropdown
• Description: Determines the color scheme for increases and decreases in values:
  • Options: standard, inverted
  • Effect: In standard mode, increases are marked in blue and decreases in red, while inverted changes this palette.
• Default Value: standard.

Data Expectations

The WaterfallTile expects the data to adhere to a specific structure to effectively generate visual output. Each data point should ideally contain a name (string) and value (number). When the dataset is populated dynamically, the mapping configurations must correctly align with the available fields in the sourced dataset.

Use Cases & Examples

Use Cases

1. Financial Reporting: Tracking monthly financial performance across different revenue streams, showing gains and losses relative to a base figure.
2. Project Management: Visualizing progress on project timelines, with distinct markers for phases where time or resources were added or removed.
3. Sales Analysis: Presenting cumulative sales figures over a quarter, identifying which products contributed positively or negatively to overall sales.

Example Configuration

Use Case: Financial Reporting for a Quarterly Review

To illustrate the performance of various product lines over a quarter, the WaterfallTile can be configured as follows:

{
  "config": {
    "height": 400,
    "width": 600,
    "dataRefIds": ["financial_workflow_id"],
    "fieldMapping": {
      "_series": [
        {
          "label": { "field": "product_name" },
          "value": { "field": "sales_amount" }
        }
      ]
    },
    "waterfallMode": "delta",
    "sentiment": "standard"
  },
  "title": "Quarterly Sales Analysis",
  "subtitle": "Tracking performance of product lines",
  "footerText": "Data sourced from financial database.",
  "footerColor": "#F3F4F6"
}

In this configuration:

• The height and width define how prominently the chart will display within the dashboard.
• The usage of dataRefIds connects the component with dynamic datasets reflecting live sales.
• The mapping ensures that the product_name and sales_amount fields are correctly interpreted, generating a clear and informative waterfall effect.