(this page was created automatically. In case of formatting issues, please visit the official Wiki Page)

Stacked Bar Chart

Overview

• The Dynamic Stacked Bar Chart Component visualizes data as horizontal bars stacked on top of each other.
• It helps compare contributions of categories to a total and shows the composition of each entity.
• The component connects to data sources for dynamic data retrieval.
• It offers multiple configuration options for appearance and behavior.

Specs

Tokens

Structure

• Data is displayed as horizontal bars, each bar representing a category placed along the vertical axis.
• Bars are divided into stacked segments that together show the category’s total, with each segment representing a series.
• A legend can be included to explain the colors and meaning of each series.

(Configured in General Properties)

• displayName – Sets the display name of the component shown in the structure panel. For example, "Regional Sales Breakdown" clearly identifies the purpose of this specific chart in the component structure.

(Configured in Visibility)

• displayConditions – Defines conditions under which the chart is displayed. This allows for context-aware visibility, showing the chart only when certain conditions are met (e.g., when a specific product category is selected).

• Data Format Requirements

• The Stacked Bar Chart component expects data in the following format:

  [
    { 
      "region": "North America", 
      "product1": 10000, 
      "product2": 5000, 
      "product3": 15000 
    },
    { 
      "region": "Europe", 
      "product1": 12000, 
      "product2": 8000, 
      "product3": 10000 
    },
    { 
      "region": "Asia", 
      "product1": 8000, 
      "product2": 9000, 
      "product3": 6000 
    }
  ]
  

• chartConfiguration – Configures the series and visual aspects of the chart. This includes settings for each data series, colors, tooltips, and more. This property uses a detailed configuration object to control how data is mapped to visual elements.
  (Configured in Visual Properties)

• Series: Define which data fields should be represented as stacked bars

• Category field: Specify which field contains the category labels (displayed on the y-axis)

• Series colors: Customize the color of each series for better visual distinction

• Tooltip templates: Customize what information appears when hovering over bars

Datasource

(Configured in Datasource)

• useMockData – Determines whether sample data is used instead of an actual data source. When enabled, the chart displays pre-defined sample data, which is useful for design and testing purposes.
• dataSourceId – Specifies the data source ID for retrieving chart data. For example, "api/sales-by-region" connects the chart to an endpoint that provides the appropriate data structure for visualization.
• getEntityCollectionHttpRequestParametersMap – Configures HTTP request parameters for fetching data. This allows for customizing query parameters, path variables, or body parameters that are sent when requesting data from the specified source.

Styling

(Configured in Visual Properties)

• showLegend – Determines whether the legend is displayed alongside the chart. When enabled, a legend with all series names and their corresponding colors will be displayed, providing context for the data representation.
• barPadding – Sets the padding between bars in the chart, specified as a number. For example, setting this to "5" adds moderate spacing between bars for better visual separation.
• barWidth – Defines the width of individual bars in the chart, specified as a number. For example, setting this to "30" creates bars with a width of 30 pixels, allowing for control over the chart's density.
• ignoreEmptyPoints – Determines whether empty or null data points are displayed in the chart. When enabled, missing data points are omitted rather than shown as zeros, helping focus on actual data.
• paddingClass – Configures the padding around the component using CSS classes. For example, "p-3" adds medium padding on all sides of the chart component.

Actions & Variants

(Configured in Events)

• events – Configures events that the component can trigger and respond to.
• ON_INIT – Triggered when the component is initialized. This event can be used to perform setup operations or initial data processing.
• ON_DESTROY – Triggered when the component is removed from the DOM. This event can be used for cleanup operations or resource release.

Tests

(Configured in Testing Hooks)

• id – Specifies a unique identifier for the component, useful for programmatic access in testing or custom code.
• dataTestId – Sets a testing hook ID for automated testing, allowing test scripts to reliably identify this chart component.
• enableAsHotspot – Enables the component as a guided tour hotspot. When enabled, this chart can be highlighted during onboarding tours.
• guidedTourHotSpotTitle – Sets the title text displayed when this component is highlighted in a guided tour, with support for translations.
• guidedTourHotSpotDescription – Sets the descriptive text explaining the chart's purpose during a guided tour, with support for translations.

Authorization

(Configured in Authorization)

• visibilityPolicySetId – Determines the visibility of the component based on user permissions and policy sets. For example, setting to "salesTeamPolicy" restricts the chart to users with sales team privileges.

Guidelines

Usage

• Use to compare each category’s part-to-whole composition with horizontal stacks by mapping fields in chartConfiguration (Series, Category field).
• Name the component clearly for authors via displayName so it’s identifiable in the structure panel.

Sizing & Layout

• Control visual density with barWidth (thicker bars for short category lists, thinner for long lists).
• Improve legibility between categories with barPadding.
• Add outer breathing room around the component using paddingClass.

Color & Contrast

• Assign distinct colors per segment using chartConfiguration → Series colors to differentiate series.
• Ensure adjacent stacks are distinguishable by picking sufficiently contrasting Series colors.
• Avoid color-only meaning by combining showLegend with descriptive Tooltip templates.

Tooltips

• Provide concise, structured details for each segment using chartConfiguration → Tooltip templates.
• Keep tooltips supplemental; ensure essential identifiers are visible through showLegend and the axis labels given by Category field.
• Localize or format values inside the template directly in Tooltip templates (e.g., units/percentages).

Data-Driven / Conditional Behavior

• Map the categorical axis using chartConfiguration → Category field and define all stack contributors in chartConfiguration → Series.
• Keep stacks comparable by using consistent series keys across categories in chartConfiguration.Series.
• Prefer omitting missing values to avoid misleading totals by enabling ignoreEmptyPoints.
• Parameterize data retrieval with getEntityCollectionHttpRequestParametersMap for predictable filtering/slicing.

Visibility & Authorization

• Gate visibility by role/policy with visibilityPolicySetId.
• Show or hide the chart based on runtime rules using displayConditions.

Content & Localization

• Provide guided tour copy per locale with guidedTourHotSpotTitle and guidedTourHotSpotDescription.
• Use displayName for authoring clarity without affecting end-user labels.

Dos & Don’ts

Accessibility

• Convey series meaning textually by enabling the legend (showLegend) with clear series names in chartConfiguration.Series, and pair with concise Tooltip templates; choose high-contrast Series colors.
• Reduce misinterpretation by omitting missing data points with ignoreEmptyPoints.
• Offer guided assistance during onboarding with localized guidedTourHotSpotTitle and guidedTourHotSpotDescription.
• Keep tooltip content short and localized in Tooltip templates; never rely on tooltips as the sole source of critical information.
• Maintain consistent series order using chartConfiguration.Series so users don’t have to relearn mappings per view.