Skip to main content

ChartJS4 Integration

Introduction​

The ChartJS4 extension integrates Chart.js 4.x with Wisej.NET. It is a new extension with its own package, Wisej-4-ChartJS4, and its own namespace, Wisej.Web.Ext.ChartJS4; the existing ChartJS (Chart.js 2) and ChartJS3 (Chart.js 3) extensions are unchanged and keep working side by side with it. Its redesigned architecture adds improved serialization, inline JavaScript, automatic plugin discovery, and an extensible options model.

The full reference is in the Extensions API: Wisej.Web.Ext.ChartJS4 for the control and Wisej.Web.Ext.ChartJS4.Models for the options and dataset classes. The ChartJS page of the Extensions manual compares the three Chart.js extensions.

Technical Highlights​

Modern Serialization​

Each options class and dataset class exposes an ExtensionData dictionary that is serialized alongside all other properties. Any Chart.js option — including those from third-party plugins — can be passed through without modifying the library or subclassing anything.

// Pass any Chart.js option not yet covered by a first-class property
chart.ChartOptions.ExtensionData = new Dictionary<string, object>
{
    ["interaction"] = new { mode = "nearest", intersect = false },
    ["parsing"] = new { xAxisKey = "date", yAxisKey = "value" }
};

Inline Scripting and Widget Functions​

The extension supports server-defined JavaScript functions that are resolved client-side and bound to the Wisej widget context. Scriptable Chart.js options (per-point colors, dynamic labels, conditional formatting) can be expressed as named WidgetFunction references using the (ctx)=>functionName pattern, or as raw inline function strings assigned directly to any option.

// Named function — define once, reference anywhere
chart.WidgetFunctions = new[]
{
    new ChartJS4.WidgetFunction
    {
        Name = "barColor",
        Source = "function(ctx) { return ctx.parsed.y > 100 ? 'crimson' : 'steelblue'; }"
    }
};

ds.ExtensionData = new Dictionary<string, object>
{
    ["backgroundColor"] = "(ctx)=>barColor"
};

// Or just assign an inline function string directly — no registration needed
ds.ExtensionData = new Dictionary<string, object>
{
    ["borderColor"] = "ctx => ctx.dataIndex % 2 === 0 ? 'red' : 'blue'"
};

Automatic Plugin Discovery​

The extension scans all loaded assemblies at startup for embedded resources located in a folder named ChartJsPlugins. Any .js file placed there with Build Action → Embedded Resource is automatically registered and loaded — no code changes, no registration calls required.

MyApp/
├── ChartJsPlugins/
│   ├── chartjs-plugin-zoom.js        ← loaded automatically
│   └── chartjs-plugin-annotation.js  ← loaded automatically

Strongly Typed Options Model​

The extension provides dedicated C# classes for all major Chart.js options: scales, axes, plugins, legend, tooltip, animation, data labels, and all dataset types. [DefaultValue] attributes keep serialized payloads lean and the Visual Studio designer clean.

chart.ChartOptions.Plugins.Legend.Position = "bottom";
chart.ChartOptions.Plugins.Title.Display = true;
chart.ChartOptions.Plugins.Title.Text = "Monthly Revenue";
chart.ChartOptions.Scales.Y.BeginAtZero = true;
chart.ChartOptions.Scales.Y.Title.Display = true;
chart.ChartOptions.Scales.Y.Title.Text = "USD";

Full Chart.js API Surface​

The extension exposes the Chart.js runtime API as C# methods: UpdateData, UpdateChart, SetDatasetVisibility, Hide, Show, SetActiveElements, ToBase64Image, GetImageAsync, Resize, Destroy, and more. Methods that return a value from the browser are asynchronous: they either take a callback or, like GetImageAsync, return a task you can await.

// Smooth animated data refresh without re-rendering the whole chart
chart.UpdateData(duration: 400);

// Export the chart as a PNG image
var image = await chart.GetImageAsync();
image.Save("export.png");

// Hide a dataset and show it again
chart.Hide(datasetIndex: 1);
chart.Show(datasetIndex: 1);

Design-Time Support​

The extension renders a live preview chart in the Visual Studio designer with animations disabled, using a built-in sample dataset. All properties support full designer serialization and reset.

ChartValue.NaN​

ChartValue.NaN is a convenience value you can place into a dataset when you want Chart.js to treat a data point as missing. JSON has no representation for NaN, so the value is serialized as a special string that the client-side script converts back to a JavaScript NaN before the data reaches Chart.js.

In Chart.js, and therefore in Wisej.Web.Ext.ChartJS4, NaN values are skipped:

  • The point is not rendered.
  • For line charts, a NaN creates a gap in the line unless the dataset's SpanGaps option bridges it.

Use ChartValue.NaN when you need to:

  • represent missing measurements in a time series,
  • intentionally break a line between two sections,
  • hide individual points without changing the number of labels.

Example: Create a gap in a line chart​

The example below shows a line dataset with a gap at the 4th point by using ChartValue.NaN. With SpanGaps = false, Chart.js breaks the line at that point.

// Inside a Wisej form or page that contains a ChartJS4 control named "chartJS4".
using Wisej.Web.Ext.ChartJS4;
using Wisej.Web.Ext.ChartJS4.Models;

// Labels (x-axis)
chartJS4.Labels = new[] { "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun" };

// Dataset with a missing value on "Thu"
var ds = new LineDataSet
{
    Label = "Visitors",
    Data = new object[] { 10, 14, 12, ChartValue.NaN, 18, 16, 20 },
    SpanGaps = false // NaN creates a break in the line
};

// Apply
chartJS4.ChartType = ChartType.Line;
chartJS4.DataSets.Clear();
chartJS4.DataSets.Add(ds);

What you should see:

  • Points for Mon, Tue, Wed are connected.
  • Thu is skipped.
  • A new segment starts at Fri and continues to Sun.

Use Cases​

  • Business dashboards with dynamic, data-driven charts
  • Per-point conditional formatting using scriptable options
  • Embedding third-party Chart.js plugins without rebuilding the library
  • Real-time data visualization with smooth animated updates
  • Exporting charts as PNG images server-side

The extension brings Chart.js 4.x customization into the Wisej.NET component model, including designer configuration, data updates, plugins, and image export.

Live Demo​

See charts powered by the ChartJS4 extension here: https://demo.wisej.net/#Preview/ChartJS4/Features