Registering standalone meta boxes for the Overview screen

This article outlines how to add standalone custom meta boxes to the Overview screen using the core meta box API introduced in AffiliateWP 1.9.

Below are detailed instructions that cover the following steps:

  1. Defining a display callback for the meta box
  2. Registering the custom meta box
  3. Hooking it up to WordPress

Defining a display callback for the meta box

The most important part of a meta box is the information it displays. When registering a standalone meta box for the Overview screen, a display callback function must be defined so that when the meta box is registered, AffiliateWP knows what to render.

Here is an example display callback for a meta box named 'My Custom Meta Box':

/**
 * Display callback for 'My Custom Meta Box'.
 */
function display_my_custom_overview_meta_box() {
	esc_html_e( 'Something goes here', 'textdomain' );
}

The example above is echoing some simple content to be displayed inside of the meta box container when it's rendered in the Overview screen. Once the meta box has been registered, AffiliateWP will rely on this callback to supply the content for display.

Registering the custom meta box

Once a display callback has been defined, it's time to actually register the meta box. This is fairly straightforward:

/**
 * Registers the 'My Custom Meta Box' meta box for the Overview screen.
 *
 * @see \AffWP\Admin\Meta_Box
 */
function my_custom_overview_meta_box() {
	new AffWP\Admin\Meta_Box( array(
		'meta_box_name'    => __( 'My Custom Meta Box', 'textdomain' ),
		'meta_box_id'      => 'overview-my-meta-box',
		'context'          => 'primary',
		'action'           => 'affwp_overview_meta_boxes',
		'display_callback' => 'display_my_custom_overview_meta_box',
	) );
}

The example above uses a core class, AffWP\Admin\Meta_Box, to register the meta box.

Within that, a number of required arguments have been defined:

  1. 'meta_box_name' – This is the translatable name of the meta box. It will be displayed in the header of the rendered meta box.
  2. 'meta_box_id' – The meta box ID. This should be a prefixed, unique ID assigned only to this meta box
  3. 'context' – The context, or display column, under which to display the meta box. This value can be 'primary', 'secondary', or 'tertiary'.
  4. 'action' – The action upon which the meta box will be registered. In the case of our example, the 'affwp_overview_meta_boxes' action is used because it specifically fires on the Overview screen.
  5. 'display_callback' – This is the display callback function used to render the contents of the meta box. You can see we've used the name of display callback we created in the first step.

Hooking it up to WordPress

In order to ensure the AffWP\Admin\Meta_Box class is available for registering AffWP meta boxes, it's necessary to hook the function that registers the meta box to the core 'plugins_loaded' action:

add_action( 'plugins_loaded', 'my_custom_overview_meta_box' );

That's it!


Review: Registering a standalone meta box

As outlined above, here is the complete code for registering a standalone meta box for the Overview screen:

/**
 * Registers the 'My Custom Meta Box' meta box for the Overview screen.
 *
 * @see \AffWP\Admin\Meta_Box
 */
function my_custom_overview_meta_box() {
	new AffWP\Admin\Meta_Box( array(
		'meta_box_name'    => __( 'My Custom Meta Box', 'textdomain' ),
		'meta_box_id'      => 'overview-my-meta-box',
		'context'          => 'primary',
		'action'           => 'affwp_overview_meta_boxes',
		'display_callback' => 'display_my_custom_overview_meta_box',
	) );
}
add_action( 'plugins_loaded', 'my_custom_overview_meta_box' );


/**
 * Display callback for 'My Custom Meta Box'.
 */
function display_my_custom_overview_meta_box() {
	esc_html_e( 'Something goes here', 'textdomain' );
}