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 Tablem_chart_pro()->themes()— Theme Builderm_chart_pro()->annotations()— Annotationsm_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, andm-chart-pro-tables. - Style handles:
m-chart-pro-datatables, the samem-chart-pro-datatables-…names for the extensions, andm-chart-pro-frontend. The DataTables styling shims add a-dtsuffix. m-chart-pro-iframe-resizeis enqueued site-wide when embeds are on.m-chart-pro-html-to-imageis 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 plusfonts.gstatic.com,fonts.googleapis.com,use.typekit.net,use.fontawesome.com, andcdn.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 (orfalse).M_Chart_Pro_Themes::build_theme_slug( $post_id )— builds them-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, andchartjsPluginGlobals, 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 them_chart_chartjs_pluginsfilter: 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. Default1000, minimum1.m_chart_pro_sql_max_cols(int) — Maximum result columns. Default50, minimum1.m_chart_pro_sql_max_bytes(int) — Maximum total result size in bytes. Default 8 MB, minimum1024.m_chart_pro_sql_max_cell_bytes(int) — Maximum bytes per cell. Default65536, minimum256.m_chart_pro_sql_timeout_ms(int) — Statement timeout in milliseconds. Default10000, minimum100.
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) —trueonce 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, ormysql_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.