## Overview

The cplaceJS based Line Chart widget enables configuration of a line chart using cplaceJS. It creates custom time-series visualizations by executing JavaScript code to transform page data into chart series. It bridges configuration-based widgets and fully custom implementations, allowing developers to apply business logic, aggregations, and calculations while leveraging the robust Highcharts rendering engine and built-in UI components.

## Use Cases

### When to Use This Widget

- **Custom Data Transformation**: When you need to aggregate, calculate, or transform page data before visualizing it as a line chart
- **Complex Business Logic**: When chart data requires logic that cannot be expressed through configuration alone
- **Dynamic Series Generation**: When the number or nature of chart series depends on runtime data
- **Advanced Calculations**: When computing trends, moving averages, or other derived metrics
- **Multi-Source Data**: When combining data from multiple page types or attributes into a single visualization

### Example Scenarios

- Project timeline visualization showing milestone progress over time
- Resource utilization tracking across multiple projects
- Performance metrics dashboards with computed KPIs
- Budget burn-down charts with custom calculation logic
- Status change trend analysis over time

### When NOT to Use This Widget

- **Simple Attribute Visualization**: Use the Tuple Line Chart widget (`cf.cplace.visualizations.tupleLineChart`) if you only need to display attribute values from tuple data without transformation
- **No Scripting Requirement**: Prefer configuration-based widgets when they meet your needs for better maintainability
- **Limited JavaScript Knowledge**: This widget requires cplaceJS expertise

## Design Considerations

### Script-Based Architecture

The widget executes custom cplaceJS code server-side to generate chart series data. Scripts receive:
- `pages`: Iterable of pages from the configured search results
- `messages`: Message provider for internationalization support

Scripts must return data in Highcharts series format, with each series containing an ID, name, and array of timestamp-value pairs.

### Timeframe Filtering

The widget includes built-in timeframe filtering capabilities:
- Client-side filtering by timeframe (all, 3, 6, or 12 months)
- Scripts should include all data; frontend handles timeframe selection
- Timeframe selector buttons can be shown or hidden via configuration

### Performance Implications

- Scripts execute server-side on each widget load
- Performance monitoring is enabled for detailed logging
- Optimize scripts when processing large datasets
- Consider data volume when designing search queries

## Common Pitfalls

- **Incorrect Series Format**: Scripts must return a JSONArray in Highcharts format with proper timestamp-value pairs
- **Missing Series IDs**: Each series needs a unique ID for proper rendering
- **Unsorted Data**: Pre-sort data points by timestamp for optimal chart performance
- **Script Errors**: Thoroughly test scripts with various data scenarios as exceptions will display as widget errors
- **Date Format**: Use timestamps in milliseconds since epoch for x-axis data points

## Alternatives to Consider

| Widget | When to Choose |
|--------|----------------|
| **Tuple Line Chart** (`cf.cplace.visualizations.tupleLineChart`) | Simple visualization of tuple attributes without transformation |
| **cplaceJS based Highcharts** (`cf.cplace.visualizations.scriptingHighcharts`) | Need full control over any Highcharts chart type, not just line charts |

## Related Patterns

- **Master-Detail with Charts**: Use a table widget as master to filter which pages are visualized in the line chart
- **Dashboard KPI Display**: Combine with other visualization widgets for comprehensive dashboards
- **Time-Based Trend Analysis**: Pair with search filters to analyze trends across different time periods