Action and filter hooks - methnen/m-chart GitHub Wiki

M Chart has a number of filter/action hooks as well as some Javascript events that you can use to integrate M Chart into your website.

This is an action that is triggered whenever someone updates a chart's post meta.

The meta array has already been cleaned and validated at the time the action is triggered.

• Arguments
  • $post_id
    • The WP ID of the chart post
  • $parsed_meta
    • The cleaned and parsed meta array for the chart

This is an action that is triggered at the very start of chart being retrieved.

• Arguments
  • $post_id
    • The WP ID of the chart post
  • $args
    • An array of base args that are used in the get_chart function

This is an action that is triggered at the very end of a chart being retrieved and the code necessary to display the chart has been built.

• Arguments
  • $post_id
    • The WP ID of the chart post
  • $args
    • An array of base args that are used in the get_chart function

This is an action that is triggered when generating the Javascript and HTML used to render a chart.

Potentially this could be used to include some Javascript code that would run after a chart has finished rendering. This is great spot to add a watermark via an SVG file.

The Javascript should have the Highcharts chart object available to it and can also access to the chart args for the current chart since you know the ID of the post.

• Arguments
  • $post_id
    • The WP ID of the chart post
  • $args
    • The arguments that were passed to the get_chart method
  • $instance
    • Available in M Chart v.1.4.1+
    • The instance (integer) of the current chart used with the $post_id value to build the ID of the current chart (e.g. '#m-chart-' . $post_id . '-' + $instance)

Example:

function action_m_chart_post_render_javascript( $post_id, $args, $instance ) {
	?>
	chart.renderer.image('http://domain.com/img/logo.svg', 11, 10, 106, 16).add();
	<?php
}

add_action( 'm_chart_post_render_javascript', 'action_m_chart_post_render_javascript', 10, 3 );

Available in M Chart v.1.1+

This is an action that is triggered in the footer of a chart post edit page.

Potentially this could be used to include some Javascript code that would affect anything that happens during the chart edit process.

Example (See the canvas_done Javascript event which is used in this example.):

function action_m_chart_admin_footer_javascript() {
	?>
	(function( $ ) {
		$( '.m-chart' ).on( 'canvas_done', function() {
			m_chart_admin.canvas_context.drawSvg(
				'<svg>...</svg>',
				m_chart_admin.canvas.width,
				m_chart_admin.canvas.height,
				170,
				30
			);
		});
	})( jQuery );
	<?php
}

add_action( 'm_chart_admin_footer_javascript', 'action_m_chart_admin_footer_javascript' );

This filter hook is triggered after all of the Highcharts/Chart.js chart args for a given chart have been generated.

This hook is useful for changing the behavior of the plugin in regards to how it displays/functions.

You could reformat the tooltips for instance, or you could modify axis title text. You could also add arguments to the chart args that M Chart doesn't use by default like change the colors used to render the chart.

See the Highcharts API and Chart.js Docs references for all the possibilities.

• Arguments
  • $chart_args
    • The Highcharts/Chart.js chart args for the chart
  • $post
    • The WP post object for the chart
  • $post_meta
    • The WP post_meta for the chart
  • $args
    • The args passed to the get_chart method

Example:

function filter_m_chart_chart_args( $chart_args, $post, $post_meta, $args ) {
	$chart_args['colors'] = array(
		'#2f7ed8',
		'#0d233a',
		'#8bbc21',
		'#910000',
		'#1aadce',
		'#492970',
		'#f28f43',
		'#77a1e5',
		'#c42525',
		'#a6c96a',
	);

	return $chart_args;
}

add_filter( 'm_chart_chart_args', 'filter_m_chart_chart_args', 10, 4 );

This filter hook is triggered when retreiving the chart template used to build the code needed to display a chart.

• Arguments
  • $template
    • The template used to build the code needed to display a chart
  • $library
    • The active library

This filter hook is triggered when retreiving the chart template used to display a sharing embed version of a chart.

• Arguments
  • $template
    • The template used to build the code needed to display a chart
  • $library
    • The active library

This filter hook is triggered when displaying an iframe embed of a chart and lets you load additional scripts that might be needed to properly display a given chart

• Arguments
  • $scripts
    • An array of handles that match enqueued scripts that you want loaded in the iframe
  • $post_id
    • The WP ID of the chart post

This filter hook is triggered after all of the Highcharts chart options have been generated.

Chart options are library wide settings that you may want to change or override. M Chart uses them to set some USA standard formatting and numeric abbreviations.

This hook is useful for changing the behavior of Highcharts.

Most of the options involve localization stuff. For instance you could change the decimal indicator to a comma which is used in some European contries.

See the Highcharts API reference for all the possibilities.

• Arguments
  • $chart_options
    • The Highcharts options
  • $library
    • The active library

Example:

function filter_m_chart_chart_options( $chart_options, $library ) {
	$chart_options['lang']['decimalPoint'] = ',';

	return $chart_options;
}

add_filter( 'm_chart_chart_options', 'filter_m_chart_chart_options', 10, 2 );

Available in M Chart v.1.8+

This is a filter that is triggered when building a Chart.js chart's args and happens immediately after the theme's colors are pulled and allows you to override the colors.

• Arguments
  • $colors
    • The array of colors
  • $post
    • The post object of the current chart

function filter_m_chart_chartjs_colors( $colors, $post ) {
	if ( 45 != $post->ID ) {
		return $colors;
	}
	
	return array(
		'#59a80f',
		'#9ed54c',
		'#c4ed68',
		'#e2ff9e',
		'#f0F2dd',
	);
}

add_action( 'm_chart_chartjs_colors', 'filter_m_chart_chartjs_colors', 10, 2 );

Available in M Chart v.1.8+

This is a filter that is triggered when building a Chart.js chart's args and happens immediately after the theme's points are pulled and allows you to override the points.

See the Chart.js Docs references for all the possibilities.

• Arguments
  • $points
    • The array of points
  • $post
    • The post object of the current chart

function filter_m_chart_chartjs_points( $points, $post ) {
	if ( 45 != $post->ID ) {
		return $points;
	}
	
	return array(
		array(
			'point' => array(
				// Circle
				'pointStyle' => 'circle',
			),
		),
		array(
			'point' => array(
				// Square
				'pointStyle' => 'rect',
			),
		),
		array(
			'point' => array(
				// Triangle
				'pointStyle' => 'triangle',
			),
		),
	);
}

add_action( 'm_chart_chartjs_points', 'filter_m_chart_chartjs_points', 10, 2 );

Available in M Chart Highcharts Library v.1.2.3+

The Highcharts Accessibility module is disabled by default. You can use this filter hook to enable it.

This is a filter that is triggered when rendering a Highcharts chart and the return value determines if the accessibility module will be loaded.

• Arguments
  • $enabled
    • The boolean to determine if the accessibility module will be loaded
  • $post_id
    • The WP ID of the chart post
  • $context
    • Contains 'iframe' when called while rendering a chart embed; Otherwise it is ''.
• Return value: boolean

function filter_m_chart_enable_highcharts_accessibility( $enabled, $post_id, $context ) {

	// always make the chart accessible
	return true;

}

add_filter( 'm_chart_enable_highcharts_accessibility', 'filter_m_chart_enable_highcharts_accessibility', 10, 3 );

Available in M Chart Highcharts Library v.1.2.3+

The Highcharts Export module is disabled by default. You can use this filter hook to enable it.

This filter is triggered when rendering a Highcharts chart and the return value determines if the export module will be loaded.

• Arguments
  • $enabled
    • The boolean to determine if the export module will be loaded
  • $post_id
    • The WP ID of the chart post
  • $context
    • Contains 'iframe' when called while rendering a chart embed; Otherwise it is ''.
• Return value: boolean

function filter_m_chart_enable_highcharts_export( $enabled, $post_id, $context ) {

	// don't show export options when embedded
	if ( $context != 'iframe' ) {
		$enabled = true;
	}

	return $enabled;

}

add_filter( 'm_chart_enable_highcharts_export', 'filter_m_chart_enable_highcharts_export', 10, 3 );

Available in M Chart Highcharts Library v.1.2.3+

This filter is triggered when building the list of themes available for Highcharts charts. Allows one to programmatically add to, remove from or even modify an existing theme in the list of themes. If adding a theme, the file attribute is optional and the slug must be unique between all themes.

• Arguments
  • $themes
    • The array of themes
    • Each theme is an object with the following attributes:
      • slug => unique label (filename without path/extension)
      • name => display name
      • file => filename without path
      • options => array of options for theme
• Return value: array of theme objects

function filter_m_chart_highcharts_available_themes( $themes ) {
	foreach ( $themes as $key => $theme ) {
		if ( $theme->slug != 'the-one-and-only-theme' ) {
			unset( $themes[$key] );
		}
	}

	return $themes;
}

add_filter( 'm_chart_highcharts_available_themes', 'filter_m_chart_highcharts_available_themes', 10, 1 );