M ChartM Chart
Users
Pro
Developers
Download
GitHub
Users
Pro
Developers
Download
GitHub
  • Developer Guide

    • Developer Guide
    • PHP Hooks & Filters
    • JavaScript Events
    • Admin UI JavaScript Hooks
    • Custom Chart.js Themes
    • M Chart Pro
    • Migrating to v2

M Chart Pro

M Chart Pro builds on the core hooks documented on the other pages in this section. This page lists what Pro adds for developers: its own hooks, PHP access, stored meta, markup, and JavaScript APIs. M Chart Pro 1.2 requires M Chart 2.4 or later and PHP 8.1 or later.

Components

m_chart_pro() returns the plugin instance. Each feature is a component with its own accessor:

  • m_chart_pro()->tables() — Display as Table
  • m_chart_pro()->themes() — Theme Builder
  • m_chart_pro()->annotations() — Annotations
  • m_chart_pro()->chart_source() — the Another Chart data source

Display as Table

Display as Table adds no PHP hooks of its own. It works through core hooks, including three additions in M Chart 2.4: the m_chart_render_uses_chartjs filter, the $uses_chartjs argument of m_chart_get_chart_begin, and the $context argument of m_chart_validate_post_meta.

Template

Pro returns its own template from the m_chart_chart_template filter at priority 10 when the table is on. Hook the same filter at a later priority to replace it. The m_chart_table_template filter is for show="table" and is not used here.

PHP access

m_chart_pro()->tables() returns the tables component. is_enabled( $post_id ) says whether a chart is in table mode, get_meta( $post_id ) returns its validated settings, and build_table() builds the table markup and config.

Stored settings

The settings live in post meta m-chart-pro-table, also exposed as m_chart_pro_table in m_chart()->get_post_meta(). Keys: enabled, header_row, header_column, pagination, rows_per_page, rows_per_page_menu, row_name_singular, row_name_plural, summary, search, searchable_columns, sorting, sort_column, sort_direction, sortable_columns, column_menu, filtering, filterable_columns, zebra_stripes, hover_highlight, sort_column_highlight, borders, color_scheme, compact, no_wrap, sticky_header, pinned_columns, horizontal_scroll, vertical_scroll, responsive, always_visible_columns, and chart_height, the chart height stored when the toggle was turned on. Column lists are ['all'] or arrays of rendered column indexes.

The settings are written to their hidden input on core's m_chart.before_submit action, not on every change.

Markup and styling

figure.m-chart-container.m-chart-pro-table-container wraps div.m-chart-pro-table-wrap, which carries the config as JSON in data-m-chart-pro-table and holds table.m-chart-pro-table. The figure also gets m-chart-pro-scheme-light, m-chart-pro-scheme-dark, or m-chart-pro-scheme-auto for the non-inherit color schemes. Settings add stripe, hover, order-column, row-border or cell-border, compact, and nowrap to the table. The source line is p.m-chart-source. The figure's id is m-chart-container-{post}-{instance} and the table's id is m-chart-{post}-{instance}.

The scheme classes re-declare the DataTables CSS variables (--dt-*, --dtcc-*, --dtfc-*, --dtr-*), so you can override colors by setting those variables on the figure. Inside an iframe embed your page's CSS does not apply; add styles through the m_chart_iframe_styles filter.

Scripts and styles

Pro returns false from m_chart_render_uses_chartjs, so core leaves Chart.js and its plugins out on the page and in the iframe.

  • Script handles: m-chart-pro-datatables, m-chart-pro-datatables-fixedheader, m-chart-pro-datatables-fixedcolumns, m-chart-pro-datatables-responsive, m-chart-pro-datatables-columncontrol, and m-chart-pro-tables.
  • Style handles: m-chart-pro-datatables, the same m-chart-pro-datatables-… names for the extensions, and m-chart-pro-frontend. The DataTables styling shims add a -dt suffix.
  • m-chart-pro-iframe-resize is enqueued site-wide when embeds are on. m-chart-pro-html-to-image is enqueued only in the admin.

On the front end the table scripts and styles are enqueued from m_chart_get_chart_begin when its $uses_chartjs argument is false. In the iframe, m_chart_iframe_scripts adds m-chart-pro-tables and m_chart_iframe_styles adds the stylesheets.

JavaScript

window.mChartProTables exposes init( tableEl, config ), destroy( tableEl ), initAll( root ), buildOptions, resolveSettings, fitScrollBody, and options, the map from setting keys to DataTables options. There is no filter for the DataTables options. To change them, read the config from the wrapper, edit it, and re-initialize:

document.querySelectorAll( '.m-chart-pro-table-wrap[data-m-chart-pro-table]' ).forEach( ( wrap ) => {
	const config = JSON.parse( wrap.dataset.mChartProTable );
	config.settings.rows_per_page = 25;
	window.mChartProTables.init( wrap.querySelector( 'table' ), config );
} );

DataTable.defaults also works if set before m-chart-pro-tables runs. Inside the iframe, inline scripts are blocked by its Content Security Policy.

Events

m_chart.render_done (and the deprecated render_done) fire on the <table> element, not on a canvas. They bubble, and event.detail is { post_id, instance }. See JavaScript Events.

Iframe height

The table inside an iframe posts { type: 'm-chart-pro:table-height', height } to the parent window. The parent, on the same origin only, resizes the iframe and replies with { type: 'm-chart-pro:table-height-ack' }. Until the reply arrives the table is capped at the saved height.

Admin preview

In table mode the m_chart.render_chart filter returns { isMChartProTable: true, dt, destroyed, naturalHeight(), captureImage( { width, multiplier } ), destroy(), destroyTable() } instead of a Chart.js instance. The same object reaches m_chart.render_done as detail.instance in its fourth argument. Core calls captureImage() for the image version and then fires m_chart.image_capture_done( postId, instance, img ). Check isMChartProTable before calling Chart.js methods.

Theme Builder

Theme Builder themes are stored as a custom post type, m-chart-pro-theme. They are applied to Chart.js charts through the m_chart_chart_args filter.

m_chart_pro_font_face_src_hosts

Filters the allow-list of host names permitted in custom @font-face src: URLs for Theme Builder themes. When a theme's custom font CSS is parsed, each src: URL is checked against this list: URLs whose host isn't allow-listed (and aren't HTTPS same-origin) are dropped. The filter only fires when parsing custom @font-face CSS.

add_filter( 'm_chart_pro_font_face_src_hosts', function( $hosts ) {
	// Allow fonts served from a custom CDN
	$hosts[] = 'fonts.mycdn.example.com';
	return $hosts;
} );

Parameters:

  • $hosts (array) — Lower-case host names. Default includes the site's own host plus fonts.gstatic.com, fonts.googleapis.com, use.typekit.net, use.fontawesome.com, and cdn.jsdelivr.net. Return the modified array.

PHP access

  • M_Chart_Pro_Themes::parse_theme_slug( $slug ) — converts a theme slug back to its post ID (or false).
  • M_Chart_Pro_Themes::build_theme_slug( $post_id ) — builds the m-chart-pro-theme-{post_id} slug for a theme post.
  • m_chart_pro()->themes()->get_elements( $post_id ) — returns a theme's array of element objects (or []). get_elements_for_chart_type( $post_id, $chart_type ) narrows that to the elements that apply to a given chart type.

The Boxplot element's mean point and sample point controls read the chart's own mean_point and sample_points meta. They have no effect on a chart with those options off.

Admin and front end

  • m_chart_pro_theme_builder.coreDefaults — the editor's localized data carries core's chart types, colors, heightRange, nativeTypes, typeTraits, and chartjsPluginGlobals, so the preview matches the installed core version.
  • MChartProThemeHelper — the front-end script that draws theme elements Chart.js has no option for. It loads through the m_chart_chartjs_plugins filter: always in the admin, and on a page only when the chart's theme has an element the helper draws.

Annotations

Annotations are drawn by Chart.js plugins that M Chart Pro registers through the m_chart_chartjs_plugins filter: the Chart.js annotation plugin for Cartesian charts, and Pro's own renderers for polar, treemap, and venn charts. In the admin all four load. On a page or in an embed, only the renderer for the chart's coordinate system loads, and only when a matching annotation exists.

Pro's renderers are exposed on window as MChartProPolarAnnotationBridge, MChartProTreemapAnnotationBridge, and MChartProVennAnnotationBridge. The older names m-chart-pro-polar-annotation-bridge, m-chart-pro-treemap-annotation-bridge, and m-chart-pro-venn-annotation-bridge are kept for one release. m_chart_pro()->annotations()->coord_space_for_type( $type ) returns the coordinate system a chart type uses: cartesian, polar, treemap, or venn.

External Data

m_chart_pro_sql_* limit filters

Five filters that adjust the caps applied to MySQL Data Source queries and their results. Each filter receives and returns a single integer. They fire when a chart syncs a Local or Remote MySQL source; the timeout also applies to Test Connection sessions. The row and byte caps are a memory guarantee: results are read in a streaming fashion and cut off the instant a cap trips, so raise them with your server's PHP memory limit in mind.

// Allow larger result sets and slower queries
add_filter( 'm_chart_pro_sql_max_rows', fn() => 2500 );
add_filter( 'm_chart_pro_sql_timeout_ms', fn() => 20000 );

Filters:

  • m_chart_pro_sql_max_rows (int) — Maximum result rows. Default 1000, minimum 1.
  • m_chart_pro_sql_max_cols (int) — Maximum result columns. Default 50, minimum 1.
  • m_chart_pro_sql_max_bytes (int) — Maximum total result size in bytes. Default 8 MB, minimum 1024.
  • m_chart_pro_sql_max_cell_bytes (int) — Maximum bytes per cell. Default 65536, minimum 256.
  • m_chart_pro_sql_timeout_ms (int) — Statement timeout in milliseconds. Default 10000, minimum 100.

m_chart_pro_chart_source_max_children

Filters how many dependent charts M Chart Pro pushes data to when a source chart is saved, for the Another Chart data source. Default 100, minimum 1. Charts past the limit update on their own refresh schedule.

add_filter( 'm_chart_pro_chart_source_max_children', fn( $max ) => 250 );

m_chart_pro_chart_source_is_readable

Filters whether a chart may be used as an Another Chart source. Pro checks that the chart is published and has no password. This filter runs after those checks, so membership or visibility plugins can block a chart they restrict in other ways. Return false to refuse the chart. Its dependents then fail to sync with the message "The source chart is not available as a source."

add_filter( 'm_chart_pro_chart_source_is_readable', function( $readable, $post ) {
	return $readable && ! has_term( 'internal', 'category', $post );
}, 10, 2 );

Parameters:

  • $readable (bool) — true once Pro's own checks have passed
  • $post (WP_Post) — The proposed source chart

m_chart_pro_external_data_synced

Fires after an External Data source writes new data to a chart. The Another Chart source listens here to push the data on to the charts that use it. The push itself runs from core's m_chart_update_post_meta action at priority 20.

add_action( 'm_chart_pro_external_data_synced', function( $post_id, $source_key ) {
	// $source_key names the source type, for example 'chart' for Another Chart
}, 10, 2 );

Parameters:

  • $post_id (int) — The chart that received new data
  • $source_key (string) — The source type's key: google_sheets, csv, chart, mysql_local, or mysql_remote

Each dependent chart stores its source chart's ID in the post meta _m_chart_pro_source_chart. m_chart_pro()->chart_source() returns the component.

Last Updated: 11/7/26, 6:48 PM
Contributors: Jamie Poitra
Prev
Custom Chart.js Themes
Next
Migrating to v2