guicedee/jwebmp-agcharts

JWebMP AG Charts

Enterprise-grade charting library integration for JWebMP with AG Charts 13.1.0 and Angular 20.

Core Features

• Complete AG Charts 13.1.0 API — All 38 official chart options implemented
• CRTP Fluent Builders — Type-safe, self-referencing setters
• Angular 20 Integration — Seamless component integration
• TypeScript Type Generation — Automatic interface generation
• Reactive Data Binding — Real-time chart updates
• Multiple Chart Types — Line, Bar, Area, Scatter, Bubble, Pie, Donut, Histogram
• Advanced Axes — Number, Time, Log, Category, Grouped Category
• Rich Interactions — Tooltips, legends, zoom, pan, highlighting, animations

Quick Start

Basic Line Chart

@NgComponent
public class LineChartComponent implements INgComponent<LineChartComponent> {
    @Override
    public String render() {
        AgChartOptions<LineChartComponent> options = new AgChartOptions<>(this)
            .setData("""
                [
                    { month: 'Jan', sales: 100 },
                    { month: 'Feb', sales: 150 },
                    { month: 'Mar', sales: 130 }
                ]
                """)
            .setSeries(List.of(
                new AgLineSeriesOptions<>()
                    .setXKey("month")
                    .setYKey("sales")
                    .setYName("Sales")
            ))
            .setAxes(List.of(
                new AgCategoryAxisOptions<>()
                    .setType("category")
                    .setPosition(AgCartesianAxisPosition.BOTTOM),
                new AgNumberAxisOptions<>()
                    .setType("number")
                    .setPosition(AgCartesianAxisPosition.LEFT)
            ));

        return """
            <ag-charts-angular [options]="chartOptions">
            </ag-charts-angular>
            """;
    }
}

Chart Types

Cartesian Charts

Line Chart

new AgLineSeriesOptions<>()
    .setXKey("date")
    .setYKey("value")
    .setStroke("blue")
    .setStrokeWidth(2)
    .setMarker(new AgSeriesMarkerOptions<>()
        .setEnabled(true)
        .setShape(AgMarkerShape.CIRCLE));

Bar Chart

new AgBarSeriesOptions<>()
    .setXKey("category")
    .setYKey("amount")
    .setFill("steelblue")
    .setStroke("navy")
    .setStrokeWidth(1);

Area Chart

new AgAreaSeriesOptions<>()
    .setXKey("x")
    .setYKey("y")
    .setFill("rgba(0, 150, 136, 0.5)")
    .setStroke("rgb(0, 150, 136)")
    .setFillOpacity(0.7);

Scatter Chart

new AgScatterSeriesOptions<>()
    .setXKey("weight")
    .setYKey("height")
    .setMarker(new AgSeriesMarkerOptions<>()
        .setShape(AgMarkerShape.CIRCLE)
        .setSize(8)
        .setFill("red"));

Bubble Chart

new AgBubbleSeriesOptions<>()
    .setXKey("x")
    .setYKey("y")
    .setSizeKey("size")
    .setColorKey("category")
    .setMarker(new AgSeriesMarkerOptions<>()
        .setMaxSize(30));

Polar Charts

Pie Chart

new AgPieSeriesOptions<>()
    .setAngleKey("value")
    .setCalloutLabelKey("label")
    .setSectorLabelKey("value")
    .setInnerRadiusOffset(0);

Donut Chart

new AgDonutSeriesOptions<>()
    .setAngleKey("value")
    .setCalloutLabelKey("category")
    .setInnerRadiusRatio(0.7)
    .setInnerLabels(List.of(
        new AgDonutInnerLabel<>()
            .setText("Total")
            .setFontSize(24)
            .setFontWeight("bold")
    ))
    .setInnerCircle(new AgDonutInnerCircle<>()
        .setFill("white"));

Axes Configuration

Number Axis

new AgNumberAxisOptions<>()
    .setType("number")
    .setPosition(AgCartesianAxisPosition.LEFT)
    .setTitle(new AgAxisCaptionOptions<>()
        .setText("Revenue ($)")
        .setEnabled(true))
    .setLabel(new AgAxisLabelOptions<>()
        .setFormat(",.0f"))
    .setMin(0)
    .setMax(1000);

Category Axis

new AgCategoryAxisOptions<>()
    .setType("category")
    .setPosition(AgCartesianAxisPosition.BOTTOM)
    .setTitle(new AgAxisCaptionOptions<>()
        .setText("Quarter")
        .setFontSize(14));

Time Axis

new AgTimeAxisOptions<>()
    .setType("time")
    .setPosition(AgCartesianAxisPosition.BOTTOM)
    .setInterval(new AgAxisTimeIntervalOptions<>()
        .setTimeUnit(AgTimeIntervalUnit.MONTH)
        .setStep(1))
    .setLabel(new AgAxisLabelOptions<>()
        .setFormat("%b %Y"));

Log Axis

new AgLogAxisOptions<>()
    .setType("log")
    .setPosition(AgCartesianAxisPosition.LEFT)
    .setBase(10)
    .setMin(1)
    .setMax(10000);

Grouped Category Axis

new AgGroupedCategoryAxisOptions<>()
    .setType("grouped-category")
    .setPosition(AgCartesianAxisPosition.BOTTOM);

Legend Configuration

new AgChartLegendOptions<>()
    .setEnabled(true)
    .setPosition(new AgChartLegendPositionOptions<>()
        .setPosition("bottom"))
    .setSpacing(20)
    .setItem(new AgChartLegendItemOptions<>()
        .setMarker(new AgChartLegendItemMarkerOptions<>()
            .setShape(AgMarkerShape.CIRCLE)
            .setSize(12))
        .setLabel(new AgChartLegendItemLabelOptions<>()
            .setFontSize(12)))
    .setPagination(new AgChartLegendPaginationOptions<>()
        .setMarker(new AgChartLegendPaginationButtonOptions<>()
            .setSize(15)));

Tooltip Configuration

new AgChartTooltipOptions<>()
    .setEnabled(true)
    .setMode(AgTooltipMode.GROUPED)
    .setPosition(new AgTooltipPositionOptions<>()
        .setType("pointer")
        .setXOffset(10)
        .setYOffset(10))
    .setInteraction(new AgTooltipInteractionOptions<>()
        .setEnabled(true))
    .setDelay(0);

Theming

Built-in Themes

options.setTheme(AgChartThemeName.AG_MATERIAL);
// Or: AG_POLYCHROME, AG_VIVID, AG_SOLAR, AG_DEFAULT

Custom Theme

AgChartTheme theme = new AgChartTheme()
    .setPalette(new AgChartThemePalette()
        .setFills(List.of("#5470C6", "#91CC75", "#FAC858"))
        .setStrokes(List.of("#5470C6", "#91CC75", "#FAC858")))
    .setOverrides(new AgChartThemeParams()
        .setCommon(new AgChartThemeCommonOptions()
            .setBackground(new AgChartBackground()
                .setFill("#FFFFFF"))));

options.setTheme(theme);

Animation

options.setAnimation(new AgAnimationOptions()
    .setEnabled(true)
    .setDuration(1000));

Zoom & Pan

options.setZoom(new AgZoomOptions()
    .setEnabled(true)
    .setEnableAxisDragging(true)
    .setEnableScrolling(true)
    .setEnableSelecting(true));

Navigator Component

Mini-chart for large datasets:

options.setNavigator(new AgNavigatorOptions()
    .setEnabled(true)
    .setHeight(30)
    .setMin(0.2)
    .setMax(0.8));

Gradient Legend

For heatmaps and continuous scales:

options.setGradientLegend(new AgGradientLegendOptions()
    .setEnabled(true)
    .setPosition("right")
    .setGradient(new AgGradientLegendGradientOptions()
        .setPreferredLength(200)));

Context Menu

options.setContextMenu(new AgContextMenuOptions()
    .setEnabled(true));

Multi-Series Example

AgChartOptions<MyComponent> options = new AgChartOptions<>(this)
    .setTitle(new AgChartCaptionOptions<>()
        .setText("Quarterly Sales by Region")
        .setEnabled(true))
    .setData(salesData)
    .setSeries(List.of(
        new AgBarSeriesOptions<>()
            .setXKey("quarter")
            .setYKey("north")
            .setYName("North Region")
            .setFill("#4285F4"),
        new AgBarSeriesOptions<>()
            .setXKey("quarter")
            .setYKey("south")
            .setYName("South Region")
            .setFill("#34A853"),
        new AgLineSeriesOptions<>()
            .setXKey("quarter")
            .setYKey("average")
            .setYName("Average")
            .setStroke("#EA4335")
            .setStrokeWidth(3)
    ))
    .setAxes(List.of(
        new AgCategoryAxisOptions<>()
            .setType("category")
            .setPosition(AgCartesianAxisPosition.BOTTOM),
        new AgNumberAxisOptions<>()
            .setType("number")
            .setPosition(AgCartesianAxisPosition.LEFT)
            .setTitle(new AgAxisCaptionOptions<>().setText("Sales ($)"))
    ))
    .setLegend(new AgChartLegendOptions<>()
        .setEnabled(true)
        .setPosition(new AgChartLegendPositionOptions<>()
            .setPosition("bottom")));

CRTP Pattern

All options classes use CRTP for type-safe fluent builders:

public class AgChartOptions<J extends AgChartOptions<J>>
        extends ChartOptionsBase<J> {

    public J setTitle(AgChartCaptionOptions<?> title) {
        this.title = title;
        return (J) this;
    }

    public J setSeries(List<AgSeriesBaseOptions<?>> series) {
        this.series = series;
        return (J) this;
    }
}

Method chaining returns correct type:

AgChartOptions<MyComponent> options = new AgChartOptions<>(this)
    .setTitle(title)    // Returns AgChartOptions<MyComponent>
    .setSeries(series)  // Still AgChartOptions<MyComponent>
    .setLegend(legend); // Type-safe throughout

Complete Chart Options (38)

Core Elements (19)

• axes, series, legend, tooltip, theme
• locale, background, seriesArea, overlays, navigator
• gradientLegend, width, height, minWidth, minHeight
• padding, title, subtitle, footnote

Interactions & Features (19)

• highlight, animation, zoom, ranges, sync
• contextMenu, dataSource, keyboard, touch, listeners
• formatter, container, data, annotations, initialState
• misc

NPM Dependencies

{
  "dependencies": {
    "ag-charts-angular": "^13.1.0",
    "ag-charts-community": "^13.1.0"
  }
}

Common Patterns

Dynamic Data Updates

@NgDataService
public class ChartDataService implements INgDataService<ChartDataService> {
    @Override
    public Object getData(AjaxCall<?> call, AjaxResponse<?> response) {
        return repository.getChartData();
    }
}

Responsive Charts

options
    .setWidth(null)  // Auto-width
    .setHeight(400)
    .setMinWidth(300)
    .setMinHeight(200);

Event Handling

Use Angular event bindings in template:

<ag-charts-angular
    [options]="chartOptions"
    (chartReady)="onChartReady($event)"
    (seriesNodeClick)="onNodeClick($event)">
</ag-charts-angular>

JPMS Module

module com.jwebmp.plugins.agcharts {
    requires transitive com.jwebmp.core;
    requires transitive com.jwebmp.core.angular;
    requires com.fasterxml.jackson.annotation;

    exports com.jwebmp.plugins.agcharts;
    exports com.jwebmp.plugins.agcharts.options;
    exports com.jwebmp.plugins.agcharts.options.axes;
    exports com.jwebmp.plugins.agcharts.options.series;
    exports com.jwebmp.plugins.agcharts.options.legend;
    exports com.jwebmp.plugins.agcharts.options.tooltip;
    exports com.jwebmp.plugins.agcharts.options.theme;
}

Installation

<dependency>
  <groupId>com.jwebmp.plugins</groupId>
  <artifactId>agcharts</artifactId>
</dependency>

Exported Packages

• com.jwebmp.plugins.agcharts — Core plugin
• com.jwebmp.plugins.agcharts.options — Main options
• com.jwebmp.plugins.agcharts.options.axes — Axis configuration
• com.jwebmp.plugins.agcharts.options.series — Series types
• com.jwebmp.plugins.agcharts.options.legend — Legend configuration
• com.jwebmp.plugins.agcharts.options.tooltip — Tooltip configuration
• com.jwebmp.plugins.agcharts.options.theme — Theme support
• com.jwebmp.plugins.agcharts.options.navigator — Navigator component
• com.jwebmp.plugins.agcharts.options.animation — Animation control
• com.jwebmp.plugins.agcharts.options.zoom — Zoom/pan control

Best Practices

• Use CRTP pattern correctly — Always use generic type <J extends YourClass<J>>
• Set required fields — Ensure type, xKey, yKey for series
• Leverage themes — Use built-in themes for consistency
• Handle null data — Check for null/undefined before rendering
• Optimize updates — Batch data updates to minimize re-renders
• Follow Angular patterns — Use observables for reactive data
• Test with real data — Use production-like datasets

References

• Module: com.jwebmp.plugins.agcharts
• AG Charts: 13.1.0
• Angular: 20
• Java: 25+
• License: Apache 2.0
• AG Charts Documentation
• AG Charts API Reference