AggregatedBarTile Documentation

Overview

The AggregatedBarTile is a versatile component designed for rendering bar charts based on aggregated or pivoted data. This component is ideal for visualizing grouped data in both stacked and grouped bar layouts, making it suitable for various analytical scenarios. It provides dynamic chart rendering and incorporates pagination capabilities to handle large datasets.

Purpose

The primary purpose of the AggregatedBarTile is to provide an intuitive visualization of aggregated data. It is designed to work seamlessly with the output from an aggregation workflow node and supports both simple groupBy results (category to value mappings) and more complex pivoted data structures with multiple series.

Settings

The AggregatedBarTile comes with several configurable settings that cater to different use cases. Below is a detailed breakdown of each setting:

Tile Properties

• title

  • Type: String
  • Description: The title of the tile. It appears prominently at the top of the component.
  • Default Value: None

• subtitle

  • Type: String
  • Description: A secondary description or context for the tile. It is typically displayed beneath the title.
  • Default Value: None

• footerText

  • Type: String
  • Description: Text displayed at the bottom of the tile, useful for annotations or additional information.
  • Default Value: None

• footerColor

  • Type: String
  • Description: Specifies the color of the footer text.
  • Default Value: None

• data

  • Type: Array
  • Description: Incoming data passed directly into the tile. This can be raw dataset arrays that meet the expected structure.
  • Default Value: [] (empty array)

• dataRefId

  • Type: String
  • Description: Identifier for fetching data via a DataRef hook, enabling dynamic data retrieval from backend services.
  • Default Value: None

• config

  • Type: Object
  • Description: Contains specific configurations for the bar chart.
  • Default Value: {} (empty object)

Configuration Properties

• labelField

  • Type: String
  • Description: Specifies the field used for the X-axis labels (e.g., 'category'). If not provided, it will auto-detect the first string-like field from the data.
  • Default Value: None

• valueFields

  • Type: Array
  • Description: An array of fields corresponding to the values for the bars (e.g., ['totalSales', 'avgQuantity']). If not specified, it will auto-detect numeric fields.
  • Default Value: [] (empty array)

• stacked

  • Type: Boolean
  • Description: Determines whether bars should be stacked or grouped on the chart. When set to true, it stacks the values on top of each other.
  • Default Value: false

• showGrid

  • Type: Boolean
  • Description: Controls the visibility of the grid lines on the chart. A grid can help in reading the values quickly and accurately.
  • Default Value: true

• showTooltip

  • Type: Boolean
  • Description: Enables or disables the tooltip that appears on hovering over bars. Tooltips provide detailed value information.
  • Default Value: true

• showLegend

  • Type: Boolean
  • Description: Controls whether the legend displays for identifying multiple series in the chart. Useful when using more than one value field.
  • Default Value: true

• colorScheme

  • Type: Array
  • Description: Allows customization of the colors used for the bars in the chart. If not provided, it will default to a predefined color palette.
  • Default Value: COLORS (a predefined array of color values)

• pageSize

  • Type: Numeric
  • Description: Limits the number of entries displayed in the chart to maintain readability, especially with large datasets.
  • Default Value: 50

How It Works

1. Data Initialization: The component begins by checking for data either received via props (propData) or dynamically fetched using dataRefId through the useDataRefPagination hook. This hook enables pagination, improving performance with large data sets.

2. Field Detection: The component uses the computed values hook to automatically detect the label and value fields if they are not specified. It searches for string fields for the label and numeric fields for the value bars.

3. Chart Data Preparation: It prepares the final chart data by mapping through the primary data structure, organizing it into usable objects that the chart component can render.

4. Rendering States: Three states (loading, error, and no data) are checked to provide appropriate feedback to the user before rendering the actual bar chart.

5. Rendering the Chart: the bar chart component is used to visualize the data, with customizable properties such as margins, formatting, legends, tooltips, and color schemes.

Use Cases & Examples

Use Cases

1. Sales Performance Dashboard: A business can use the AggregatedBarTile to illustrate sales performance across various categories over time. This visual can help managers quickly identify high-performing categories and areas needing improvement.

2. Inventory Analysis: Retailers can visualize their inventory levels over time with stacked bars showing the quantities of different items across multiple regions, facilitating better stock management.

3. Marketing Campaign Effectiveness: Marketing teams can analyze the effectiveness of different campaigns by displaying key metrics like total leads generated, conversion rates, and average order value in a grouped, comparative manner.

Example Configuration

Use Case: Sales Performance Dashboard

For a dashboard illustrating monthly sales performance across different product categories, the AggregatedBarTile may be configured as follows:

<AggregatedBarTile
    title="Monthly Sales Performance"
    subtitle="Comparison of Sales across Categories"
    footerText="Data sourced from sales database"
    footerColor="#666"
    dataRefId="sales-data"
    config={{
        labelField: 'month',
        valueFields: ['totalSales', 'avgOrderValue'],
        stacked: false,
        showGrid: true,
        showTooltip: true,
        showLegend: true,
        colorScheme: ['#3b82f6', '#10b981', '#f59e0b'],
        pageSize: 12
    }}
/>

In this example:

• title: Indicates what the users are viewing.
• subtitle: Provides context on the comparison being made.
• valueFields: Includes totalSales and avgOrderValue to deliver insightful metrics.
• colorScheme: Custom colors are specified for better aesthetics and differentiation among data series.

This configuration ensures that users can easily assess sales trends and adjust strategies accordingly.