BarTile Documentation

Overview

The BarTile component is designed for visualizing data in a bar chart format within the Vantage analytics platform. This visualization allows users to present comparative data, trends over time, or any categorical information in a clear and engaging manner. With its customizable options, users can easily adapt the BarTile to suit their specific data visualization needs.

Settings

1. Title

• Input Type: String
• Description: The main title displayed at the top of the bar chart. This text provides users with immediate context about the data being visualized.
• Default Value: undefined

2. Subtitle

• Input Type: String
• Description: A secondary line of text appearing under the title. It can offer additional context, highlight key metrics or provide explanations about the data visualized.
• Default Value: undefined

3. Footer Text

• Input Type: String
• Description: Text displayed at the bottom of the tile, which can be used for notes, citations, or additional information related to the data.
• Default Value: undefined

4. Footer Color

• Input Type: String (color code)
• Description: The color applied to the footer text. This setting allows customization of the appearance and usability for better visual impact.
• Default Value: undefined

5. Data

• Input Type: Array of objects
• Description: The primary data source for the bar chart, which should contain elements representing each bar's value and label. Each object should have a structure like { label: string, value: number }.
• Default Value: [] (empty array)

6. Data Ref IDs

• Input Type: Array of strings
• Description: References to the data sources used to fetch the underlying data. This is used in conjunction with data fetching hooks to retrieve dynamic datasets.
• Default Value: [] (empty array)

7. Show Grid

• Input Type: Boolean
• Description: Indicates whether grid lines should be displayed on the bar chart. Enabling this can enhance readability by allowing viewers to more easily gauge values against a scale.
• Default Value: true

8. Show Tooltip

• Input Type: Boolean
• Description: Determines if tooltips are displayed when hovering over the bars in the chart. Tooltips can show additional data points or context for each bar, increasing the chart's interactivity.
• Default Value: true

9. Show Legend

• Input Type: Boolean
• Description: Controls the visibility of the legend that identifies the different series represented in the bar chart. This is particularly useful when multiple data series are displayed.
• Default Value: true

10. Workflows

• Input Type: Array of objects
• Description: Optional workflows that affect data processing and display. These workflows can customize how data is managed before being visualized.
• Default Value: [] (empty array)

11. Series

• Input Type: Array of objects
• Description: A mapping of series attributes (like color and label) used in the bar chart. Each object typically contains a label and a color to identify distinct series visually.
• Default Value: [] (empty array)

12. Skip Animation

• Input Type: Boolean
• Description: If set to true, disables animations during chart updates. This is useful for performance optimization in certain scenarios, such as during rapid data changes.
• Default Value: false

13. Click URL

• Input Type: String
• Description: A URL that, if provided, allows users to navigate to a specified link when clicking on the bar chart. This can be used to create actionable insights linked to further information or dashboards.
• Default Value: undefined

How It Works

The BarTile component processes data through various hooks and functions that fetch, validate, and prepare the data for visualization. The following steps occur within the component:

1. Data Fetching: The component fetches initial data from defined sources using the useTileData and useFullDataset hooks based on the provided Data Ref IDs.
2. AI Integration: If AI workflows are defined, the useAIChartData hook generates additional series data that can override existing datasets. This allows dynamic and predictive modeling based on workflow outcomes.
3. Data Validation and Processing: The raw data is passed through the useTileProcessedData hook, which validates the configuration, transforming the data into a format suitable for the chart.
4. Dynamic Rendering: Depending on various states like loading and errors, the component conditionally renders loading indicators or error messages.
5. Chart Rendering: Finally, the data is displayed using the charting engine, including features like tooltips and grid lines based on user-configured settings.

Use Cases & Examples

Use Case 1: Sales Performance Tracking

A retail company can use the BarTile to visualize monthly sales performance across different regions. Each bar can represent sales figures, highlighting the most successful regions over time.

Use Case 2: Website User Engagement

A digital marketing team may configure a BarTile to display user engagement metrics over time. Metrics could include daily visits, bounce rates, and conversion rates, all represented in interactive bar formats for quick analysis.

Example Configuration

Consider a scenario where a company wants to track sales data for different product lines over a year. The configuration for the BarTile could be set as follows:

{
  "title": "Yearly Sales Performance",
  "subtitle": "Comparison across product lines",
  "footerText": "Data sourced from sales database",
  "footerColor": "#4A4A4A",
  "data": [
      { "label": "Product A", "value": 4000 },
      { "label": "Product B", "value": 3000 },
      { "label": "Product C", "value": 2000 },
      { "label": "Product D", "value": 5000 }
  ],
  "showGrid": true,
  "showTooltip": true,
  "showLegend": true,
  "series": [
      { "label": "Sales", "color": "#FF9500" }
  ],
  "clickUrl": "https://www.company.com/sales-details",
  "skipAnimation": false
}

This configuration will create a BarTile that visually represents the sales performance of different products, allowing stakeholders to make informed decisions based on clear, engaging data visualizations.