## Overview

The cplaceJS based Highcharts Visualization widget enables the configuration of Highchart diagrams using cplaceJS. It serves as the escape hatch when standard chart widgets cannot meet visualization requirements.

**Use when**:
- Standard chart widgets (pie, bar, line) lack required customization
- You need complex chart types like Gantt charts, mixed-type charts, or specialized layouts
- Visualization logic requires conditional formatting, custom tooltips, or dynamic data transformations
- Charts must respond to specific business rules or calculations

**Alternatives**:
- **Connected Pie Chart** - Simpler pie/donut charts without scripting
- **Connected Bar Chart** - Standard bar/column visualizations
- **Scripting Line Chart** - When only line charts are needed with simpler scripting

## Use Cases

### Timeline and Scheduling Visualizations
Gantt charts displaying projects, tasks, or activities across time. These require mapping start/end dates to horizontal bars, applying status-based coloring, and often include clickable elements linking to detail pages.

### Status Distribution Displays
Donut or pie charts showing how items distribute across different states (open/in progress/done, risk levels, categories). Useful for dashboards where stakeholders need quick visual summaries.

### Trend Analysis with Comparisons
Mixed chart types combining stacked columns with overlaid line series. Common for comparing actual values against targets, demand versus capacity, or historical trends against forecasts.

### Resource and Capacity Views
Visualizations aggregating time-bounded data across periods (monthly, quarterly). Often requires processing complex reference chains and calculating derived metrics.

## Behavior and Capabilities

### Data Source Modes

The widget supports two fundamentally different data retrieval approaches:

**Connected Table Mode**: The chart receives its data from a table widget on the same page. This creates a tight coupling where the chart always reflects what the table shows, including any filters or sorting the user has applied. Users can optionally restrict the chart to only selected rows, enabling interactive exploration.

**Search Mode**: The chart queries for data independently using cplace's search filters. This provides flexibility when the chart needs different data than surrounding widgets, or when there is no table to connect to.

### Scripting Capabilities

Scripts receive page data and must return a valid Highcharts configuration object. Within the script, you can:

- Access page attributes including references and their nested properties
- Perform aggregations and calculations across the dataset
- Apply conditional logic for colors, labels, and formatting
- Generate clickable elements linking to pages
- Handle localization based on user language
- Implement empty-state handling when no data matches criteria

### Highcharts Integration

The widget supports the full range of Highcharts chart types and configurations:
- Standard charts (column, bar, line, pie, area)
- Gantt charts with timeline axes
- Mixed-type charts combining multiple series types
- Custom tooltips, data labels, and legends
- Interactive features like zoom and click handlers

## Design Considerations

### When Scripting is Worth the Complexity

Scripting adds maintenance overhead and requires JavaScript knowledge. Choose this widget when:

- The visualization logic cannot be expressed through configuration alone
- You need to combine or transform data from multiple attributes
- Status-to-color mapping requires business logic beyond simple lookups
- The chart type or layout is not available in standard widgets

For straightforward distributions or comparisons, standard chart widgets are preferable.

### When NOT to Use This Widget

**For simple number displays (KPI cards, metric counts), use `demoRichString` instead:**

- No Highcharts configuration needed
- Full CSS control over card styling
- Lower complexity for basic number + label displays
- Platform widget - always available

| Need | Better Choice |
|------|---------------|
| Single number with label (KPI card) | `demoRichString` |
| Styled metric with custom colors | `demoRichString` |
| Count from search query | `demoRichString` with embedded Low-Code widget |

Use this widget only when you need actual charts (bar, pie, line, Gantt, gauge).

### Data Volume Implications

Scripts execute on page load and process data client-side. For large datasets:
- Consider server-side aggregation before visualization
- Use specific search filters to limit returned data
- Avoid complex nested reference traversals on large result sets

### Empty State Handling

Scripts should always handle the case where no data matches the search criteria. Returning a centered message rather than a broken or empty chart improves user experience significantly.

### Mixed Chart Considerations

When combining series types (e.g., columns with a line overlay), layer ordering matters. Line series typically need higher z-index values to appear above filled series. Step-style lines often work better than smooth curves when overlaying discrete column data.

### Localization

Charts displayed to international users should detect user language and provide localized labels, titles, and messages. This includes both static text and dynamically generated content like tooltips.

## Related Widgets

**Data Source Widgets**: Works with **Table Widget** or **Connected Table** when using connected table mode. The table defines what data flows into the chart.

**Alternative Chart Widgets**: Consider **Connected Pie Chart** and **Connected Bar Chart** for simpler requirements. These offer less flexibility but require no scripting.

**Sibling Scripting Widget**: **Scripting Line Chart** provides similar scripting capabilities but optimized specifically for line chart rendering.

**Dashboard Context**: Often appears alongside summary widgets, KPI displays, and tables to provide complementary visualizations of the same underlying data from different perspectives.