## Overview

Visualizes an attribute of a table or a search configurable in the widget as a bar chart.

The Connected Bar Chart widget displays the frequency distribution of values for a selected attribute across a dataset. It aggregates data by counting occurrences of each distinct value and renders the results as vertical bars (columns) using Highcharts. The chart is interactive, supporting Y-axis zoom for detailed inspection of data.

## Use Cases

### Status Distribution Analysis
Visualize how many items exist in each status state (e.g., "Open", "In Progress", "Done"). This is particularly useful for project management dashboards to identify bottlenecks where items accumulate in certain statuses.

### Category Distribution
Display the distribution of items across categories, types, or priority levels. Examples include showing products by category or issues by priority (Low, Medium, High, Critical).

### Workload Analysis
Visualize how many items are assigned to each person to identify unbalanced workloads. Useful for resource planning and capacity management.

### Enumeration Value Distribution
Any enumeration or reference attribute can be visualized to show value distribution across a dataset, helping identify the most and least common values.

## Operating Modes

### Connected Table Mode (Recommended)
Links to an existing table widget on the same page. The chart inherits the table's search configuration and filters, automatically updating when the table data changes. This mode is ideal for interactive dashboards where users filter data in the table and see the chart update accordingly.

### Standalone Search Mode (Fallback)
Defines a search directly in the widget configuration, operating independently from other widgets. **Use only when no table on the page holds the data to visualize.** This mode is useful for fixed visualizations where the underlying data is not represented by any table widget.

> **Best Practice**: Always prefer connecting to a table widget. The table provides synchronized filtering, dynamic updates, and a consistent user experience. Only use standalone search mode when the data to visualize is not represented by any table on the page.

## Design Considerations

### When to Use Bar Chart
- Showing distribution across discrete categories
- Comparing frequencies of different values
- Working with attributes that have a reasonable number of distinct values (fewer than 50)
- Needing vertical/column representation for clarity

### When to Consider Alternatives
- **Too many values**: When the attribute has many distinct values, the chart becomes cluttered and hard to read
- **Proportional data**: When showing percentages or proportions is more important than absolute counts, consider a pie chart
- **Multi-dimensional analysis**: When comparing two attributes simultaneously, consider the Connected Matrix widget
- **Continuous data**: For time-series or continuous numerical data, line charts may be more appropriate

### Chart Characteristics
- Vertical column chart with distinct colors for each bar
- Y-axis zoom enabled for detailed inspection
- Data labels showing count values on each bar
- Tooltips on hover for additional detail
- No legend (each bar represents a unique category)

## Common Pitfalls

- **Selecting attributes with too many distinct values**: Results in an unreadable, cluttered chart. Pre-filter data or choose attributes with limited cardinality.
- **Not specifying a data source**: The widget requires either a connected table widget or a standalone search configuration.
- **Standalone search targeting multiple types**: When using standalone search mode, the search must return entities of a single type for attribute selection to work.

## Alternatives to Consider

| Widget | When to Use Instead |
|--------|---------------------|
| `cf.platform.connectedPieChart` | When showing proportions/percentages is more important than absolute counts |
| `cf.platform.connectedMatrix` | When analyzing relationships between two attributes |
| `cf.platform.connectedNumberOfResults` | When only the total count matters, not distribution |

## Related Patterns

### Dashboard Pattern
Multiple chart widgets (bar, pie, matrix) connected to the same table widget. The table provides interactive filtering, and all connected charts update together to reflect the filtered data.

### Fixed Report Pattern
Standalone charts with predefined searches, creating consistent visualizations that are not affected by user interactions. Useful for standardized reports and executive dashboards.