Admin UI JavaScript Hooks

Available since version 2.0. The React-based chart admin UI uses the WordPress wp.hooks API for extensibility. Library plugins (e.g. M Chart Highcharts Library) use these hooks to replace or augment the default Chart.js interface.

About the my-plugin/… strings in these examples

The second argument to wp.hooks.addFilter() / wp.hooks.addAction() is a namespace that identifies your handler so it can be removed or replaced later. WordPress requires the format <vendor>/<handler-name>.

my-plugin in every example below is a placeholder — replace it with your plugin or theme slug. If your plugin is called acme-charts, register handlers as acme-charts/render, acme-charts/settings, etc. Each registered handler in your code needs a unique string; the slash-separated shape isn't otherwise enforced.

Filter Hooks

m_chart.render_chart

Filters chart rendering in the admin preview. Return true to signal that your code has handled rendering, preventing the default Chart.js renderer from running. Return false (or the value of handled) to pass through to the next filter or to Chart.js.

wp.hooks.addFilter(
	'm_chart.render_chart',
	'my-plugin/render',
	( handled, canvas, chartArgs, onComplete, existingInstance ) => {
		if ( handled ) {
			return handled;
		}

		// Destroy the previous instance before creating a new one
		if ( existingInstance ) {
			existingInstance.destroy();
		}

		// Render your own chart on `canvas` using `chartArgs`, then call `onComplete`
		const instance = MyLibrary.render( canvas, chartArgs );
		onComplete( instance );

		return true; // Prevent Chart.js from also rendering
	}
);

Parameters passed to the filter:

  • handled (bool) — Whether a previous filter already handled rendering
  • canvas (HTMLCanvasElement) — The canvas element to render into
  • chartArgs (object) — The full chart arguments object from the server
  • onComplete (function) — Callback to invoke with the chart instance after rendering is complete; M Chart uses this to store the instance reference
  • existingInstance (object|null) — The previous chart instance, if any; call .destroy() on it before creating a new one to avoid memory leaks

m_chart.settings_component

Filters the React component rendered in the chart type/settings panel. Use this to replace the default Chart.js settings UI with a custom component (e.g. Highcharts-specific settings).

wp.hooks.addFilter(
	'm_chart.settings_component',
	'my-plugin/settings',
	( DefaultComponent ) => MySettingsComponent
);

Parameters:

  • DefaultComponent (React component) — The default Chart.js settings component

m_chart.spreadsheet_metabox_extension

Filters the content rendered between the sheet tabs and the spreadsheet grid in the spreadsheet meta box. Return a React element to inject custom UI into that area, or return null (the default) to render nothing.

wp.hooks.addFilter(
	'm_chart.spreadsheet_metabox_extension',
	'my-plugin/spreadsheet-extension',
	( content, context ) => {
		const { state, dispatch, getActiveWorksheet, setSheetDataOnWorksheet } = context;

		return wp.element.createElement(
			'div',
			{ className: 'my-plugin-extension' },
			'Custom content here'
		);
	}
);

Parameters passed to the filter:

  • content (null) — Default is null; return a React element or null
  • context (object) — Context object with the following properties:
    • state (object) — The full ChartAdminContext state
    • dispatch (function) — The ChartAdminContext dispatch function
    • getActiveWorksheet (function) — Returns the current active worksheet instance
    • setSheetDataOnWorksheet (function) — Updates the data on the active worksheet

m_chart.chart_metabox_extension

Filters the content rendered above the chart preview inside the chart meta box. Same pattern as m_chart.spreadsheet_metabox_extension, but targets the chart preview area instead of the data area. Return a React element to inject custom UI, or return null (the default) to render nothing.

wp.hooks.addFilter(
	'm_chart.chart_metabox_extension',
	'my-plugin/chart-extension',
	( content, context ) => {
		const { state, dispatch } = context;

		return wp.element.createElement(
			'div',
			{ className: 'my-plugin-chart-controls' },
			'Custom controls above the chart preview'
		);
	}
);

Parameters passed to the filter:

  • content (null) — Default is null; return a React element or null
  • context (object) — Context object with these properties:
    • state (object) — The full ChartAdminContext state
    • dispatch (function) — The ChartAdminContext dispatch function

Action Hooks

m_chart.chart_args_success

Fires after the admin successfully fetches new chart arguments from the server (after any spreadsheet or settings change).

wp.hooks.addAction(
	'm_chart.chart_args_success',
	'my-plugin/on-args',
	( chartArgs, postId ) => {
		console.log( 'New chart args for post', postId, chartArgs );
	}
);

Parameters:

  • chartArgs (object) — The chart arguments returned from the server
  • postId (int) — The chart post ID

m_chart.render_done

Fires after the chart instance has been created or updated in the admin preview.

wp.hooks.addAction(
	'm_chart.render_done',
	'my-plugin/render-done',
	( postId, instance, chart ) => {
		// `chart` is the chart instance for the active library
		console.log( 'Chart', postId, 'instance', instance, 'rendered', chart.data );
	}
);

Parameters:

  • postId (int) — The chart post ID
  • instance (int) — The chart instance counter (always 1 in the admin preview context)
  • chart (object) — The chart instance for the active library. This is a Chart.js instance when Chart.js is active, or a Highcharts instance when the M Chart Highcharts Library is active.

m_chart.form_disabled

Fires when the chart admin form is disabled mid-update — i.e. an AJAX refresh is in flight and the user shouldn't be able to save mid-cycle. Useful for plugins that want to show a "saving..." indicator or disable their own UI alongside the chart.

wp.hooks.addAction(
	'm_chart.form_disabled',
	'my-plugin/on-form-disabled',
	( postId ) => {
		console.log( 'Chart', postId, 'is mid-refresh' );
	}
);

Parameters:

  • postId (int) — The chart post ID

m_chart.form_enabled

Fires when the chart admin form transitions back to enabled — i.e. the user can save the post again. This is the universal "the chart is fully ready" signal, regardless of which code path got us there (image capture finished, image not needed, non-canvas library, etc.).

wp.hooks.addAction(
	'm_chart.form_enabled',
	'my-plugin/on-form-enabled',
	( postId ) => {
		console.log( 'Chart', postId, 'is ready to save' );
	}
);

Parameters:

  • postId (int) — The chart post ID

m_chart.image_capture_start

Fires immediately before the admin chart preview captures its canvas as a PNG. Only fires when image generation is actually going to run (the chart library uses canvas AND image support is enabled AND performance mode is default). Library plugins like Highcharts that have their own image flow won't trigger this event.

wp.hooks.addAction(
	'm_chart.image_capture_start',
	'my-plugin/on-capture-start',
	( postId, chart ) => {
		console.log( 'About to capture', postId );
	}
);

Parameters:

  • postId (int) — The chart post ID
  • chart (object) — The Chart.js chart instance

m_chart.image_capture_done

Fires immediately after the captured PNG data URL has been written to the hidden form textarea (#m-chart-img), but before the form is re-enabled for submission. This is the right hook for plugins that need access to the captured image data — the hidden textarea now contains the same base64 string.

wp.hooks.addAction(
	'm_chart.image_capture_done',
	'my-plugin/on-capture-done',
	( postId, chart, dataUrl ) => {
		console.log( 'Captured', dataUrl.length, 'bytes for post', postId );
	}
);

Parameters:

  • postId (int) — The chart post ID
  • chart (object) — The Chart.js chart instance
  • dataUrl (string) — Base64-encoded PNG data URL (the same value that was just written to the textarea)

Runtime Globals

The admin UI exposes two window globals that extensions can read alongside the hooks above.

window.m_chart

A small namespace exposing the shared React context hook and the built-in settings row components. The intent is to let library plugins implementing the m_chart.settings_component filter assemble a settings panel that matches the Chart.js look without bundling a duplicate copy of every component.

const { useChartAdmin, TypeAndThemeRow, ParseAndFlagsRow, AxisRows, SourceRow, ShortcodeAndImageRow } = window.m_chart;

function MyLibrarySettings() {
	const { state, dispatch } = useChartAdmin();

	return wp.element.createElement(
		wp.element.Fragment,
		null,
		wp.element.createElement( TypeAndThemeRow ),
		wp.element.createElement( ParseAndFlagsRow ),
		wp.element.createElement( AxisRows ),
		wp.element.createElement( SourceRow ),
		wp.element.createElement( ShortcodeAndImageRow )
	);
}

Properties:

  • useChartAdmin — The React hook that returns { state, dispatch } for the chart admin context. Use this inside components mounted via m_chart.settings_component / m_chart.chart_metabox_extension / m_chart.spreadsheet_metabox_extension to read post meta or dispatch updates.
  • TypeAndThemeRow — Chart type, theme, color-per-data-point, and chart height controls.
  • ParseAndFlagsRow — Parse-data-in selector and the Show labels / Show legend / Show mean point / Show sample points / Shared tooltip checkboxes.
  • AxisRows — Min/max controls, constrain-vertical-axis, and axis title / units fields.
  • SourceRow — Source, Source URL, and Include source in chart fields.
  • ShortcodeAndImageRow — The auto-generated shortcode display and image preview controls.

None of these components accept props — they all read directly from the shared ChartAdminContext via useChartAdmin(). Render them in the order shown above for the closest match to the built-in Chart.js settings panel layout.

window.m_chart_admin

Populated by wp_localize_script when the chart edit screen loads. Read it for chart-instance data and feature-detect support flags.

const { post_id, library, image_support, instant_preview_support, multi_sheet_types } = window.m_chart_admin;

if ( 'yes' === image_support ) {
	// Library supports image generation in this admin instance
}

Selected properties (the localize array has more — these are the values most useful to extensions):

  • post_id (int) — The chart post ID
  • library (string) — Active library slug ('chartjs', 'highcharts', etc.)
  • image_support (string) — 'yes' or 'no', as filtered through m_chart_image_support
  • instant_preview_support (string) — 'yes' or 'no', as filtered through m_chart_instant_preview_support
  • multi_sheet_types (array) — Chart type slugs that show the multi-sheet tab bar, as filtered through m_chart_multi_sheet_types
  • image_multiplier (int) — Retina/scale multiplier for captured chart images
  • image_width (int) — Default image width setting
  • post_meta (object) — The full chart post meta at page load
  • chart_args (object) — Initial chart-args payload built server-side
  • themes (array) — Theme entries available to the type/theme dropdown
  • csv_delimiters (object) / default_delimiter (string) — CSV import config

Treat m_chart_admin as read-only on page load — once React mounts, the source of truth lives inside ChartAdminContext. Use useChartAdmin() for state that may have changed after initial render.

Last Updated:
Contributors: Jamie Poitra