Box Properties

Justin Sternberg edited this page Jan 18, 2019 · 11 revisions

Table of Contents generated with DocToc

When registering a CMB2 metabox/instance, you will pass an array of properties to the new_cmb2_box() function. The possible properties in that array are documented here.

id


The id of metabox

'id' => 'my-metabox',


title


Metabox title. Title display in the admin metabox. Default is ''.

To keep from registering an actual post-screen metabox, omit the 'title' property from the metabox registration array. (WordPress will not display metaboxes without titles anyway)

This is a good solution if you want to handle outputting your metaboxes/fields elsewhere in the post-screen.

'title' => 'Title of the Metabox',


object_types


An array containing post type slugs, or 'user', 'term', 'comment', or 'options-page'. This property is required to have a value.

'object_types' => array( 'page' ),


context


The context within the screen where the boxes should display. Available contexts vary from screen to screen. Post edit screen contexts include 'normal', 'side', and 'advanced'. (More Info)

For placement in locations outside of a metabox (but in the post/custom-post-type screen), other options include: 'form_top', 'before_permalink', 'after_title', 'after_editor' (More Information) For these alternate locations, if it is preferred that the fields are output without the metabox, then omit the 'title' property from the metabox registration array, and instead add 'remove_box_wrap' => true,.

Comments screen contexts include 'normal' and 'side'. Default is 'normal'.

'context' => 'normal',


priority


Priority of the metabox in its context. Default is 'high'. (More Info)

'priority' => 'high',


show_names


Whether to show labels for the fields. Default is true. 'show_names' => false, // Hide the labels


classes


This property allows you to optionally add classes to the CMB2 wrapper. This property can take a string, or array.

'classes' => 'additional-class', OR
'classes' => array( 'additional-class', 'another-class' ),


classes_cb


Like the classes property, allows adding classes to the CMB2 wrapper, but takes a callback. That callback should return an array of classes. The callback gets passed the CMB2 $properties array as the first argument, and the CMB2 $cmb object as the second argument. Example: 'classes_cb' => 'yourprefix_function_to_add_classes',

/**
 * Add classes to the CMB2 wrapper.
 * @param  object $properties The CMB2 box properties.
 * @param  object $cmb        The CMB2 instance.
 */
function yourprefix_function_to_add_classes( $properties, $cmb ) {
	$classes = array(
		'class1',
		'class2',
		// etc...
	);

	return $classes;
}



show_on_cb


Callback to determine if metabox should display. The callback gets passed the CMB2 $cmb object. More info: Adding your own show_on filters

'show_on_cb' => 'yourprefix_only_show_for_user_1'

/**
 * Only display a box if the current user is 1
 * @param  object $cmb Current box object
 * @return bool          True if current user's ID is 1
 */
function yourprefix_only_show_for_user_1( $cmb ) {
	// Returns true if current user's ID is 1, else false
	return 1 === get_current_user_id();
}

'show_on_cb' => 'yourprefix_show_for_pages_without_template'

/**
 * Only display a box if on a page w/o a template assigned.
 * @param  object $cmb Current box object
 * @return bool          
 */
function yourprefix_show_for_pages_without_template( $cmb ) {
	$current_template = get_post_meta( $cmb->object_id(), '_wp_page_template', true );
	return empty( $current_template ) || 'default' === $current_template;
}



show_on


Post IDs or page templates to display this metabox. Overrides 'show_on_cb'. More info: Adding your own show_on filters

'show_on' => array( 'id' => 2 ), // Only show on the "about" page


cmb_styles


Whether to enqeue CMB2 stylesheet. Default is true.

'cmb_styles' => true,


enqueue_js


Whether to enqeue CMB2 Javascript files. Default is true.

'enqueue_js' => true,


fields


It is possible to pass an array of field arrays as a box property, but it is generally prefered to use the $cmb->add_field( ... ) method.

'fields' => array( array( ... ) ),


hookup


Handles hooking CMB2 forms/metaboxes into the post/attachement/user screens, and handles hooking in and saving those fields. Set to false if you plan on handling the form/field output/saving (via something like cmb2_metabox_form()). Default is true.

'hookup' => true,


save_fields


If false, will not save during hookup (see above). Default is true.

'save_fields' => true,


closed


Set to true to default metabox being closed. Default is false.

'closed' => false,


taxonomies


if object_types is set to 'term', it is required to provide a the taxonomies property, which should be an array of Taxonomies.

'taxonomies' => array( 'category', 'post_tag' ), // Tells CMB2 which taxonomies should have these fields.


new_user_section


if object_types is set to 'user', will determine where fields are output in the new-user screen. Options are 'add-existing-user' and 'add-new-user'. Default is 'add-new-user'.

'new_user_section' => 'add-existing-user',


new_term_section


if object_types is set to 'term', and set to false, will remove the fields from the new-term screen. Default is true.

'new_term_section' => false,


show_in_rest


Determines if/how fields/metabox are available in the REST API. Default is false. (More info)

'show_in_rest' => WP_REST_Server::READABLE, // or WP_REST_Server::ALLMETHODS/WP_REST_Server::EDITABLE


remove_box_wrap


This parameter is for post alternate-context metaboxes only. To output the fields 'naked' (without a postbox wrapper/style):

'remove_box_wrap' => true,


menu_title


This parameter is for options-page metaboxes only, and is sent along to add_menu_page()/add_submenu_page() to define the menu title.

'menu_title' => 'Site Options',


message_cb


This parameter is for options-page metaboxes only, and allows specifying a custom callback for seting the error/success messages. An example has been added to example-functions.php.

'message_cb' => 'yourprefix_options_page_message_callback',

/**
 * Callback to define the optionss-saved message.
 *
 * @param CMB2  $cmb The CMB2 object.
 * @param array $args {
 *     An array of message arguments
 *
 *     @type bool   $is_options_page Whether current page is this options page.
 *     @type bool   $should_notify   Whether options were saved and we should be notified.
 *     @type bool   $is_updated      Whether options were updated with save (or stayed the same).
 *     @type string $setting         For add_settings_error(), Slug title of the setting to which
 *                                   this error applies.
 *     @type string $code            For add_settings_error(), Slug-name to identify the error.
 *                                   Used as part of 'id' attribute in HTML output.
 *     @type string $message         For add_settings_error(), The formatted message text to display
 *                                   to the user (will be shown inside styled `<div>` and `<p>` tags).
 *                                   Will be 'Settings updated.' if $is_updated is true, else 'Nothing to update.'
 *     @type string $type            For add_settings_error(), Message type, controls HTML class.
 *                                   Accepts 'error', 'updated', '', 'notice-warning', etc.
 *                                   Will be 'updated' if $is_updated is true, else 'notice-warning'.
 * }
 */
function yourprefix_options_page_message_callback( $cmb, $args ) {
	if ( ! empty( $args['should_notify'] ) ) {

		if ( $args['is_updated'] ) {

			// Modify the updated message.
			$args['message'] = sprintf( esc_html__( '%s &mdash; Updated!', 'cmb2' ), $cmb->prop( 'title' ) );
		}

		add_settings_error( $args['setting'], $args['code'], $args['message'], $args['type'] );
	}
}



parent_slug


This parameter is for options-page metaboxes only, and is sent along to add_submenu_page() to define the parent-menu item slug.

'parent_slug' => 'tools.php',


capability


This parameter is for options-page metaboxes only, and is sent along to add_menu_page()/add_submenu_page() to define the capability required to view the options page.

'capability' => 'edit_posts',


icon_url


This parameter is for options-page metaboxes only, and is sent along to add_menu_page() to define the menu icon. Only applicable if parent_slug is left empty.

'icon_url' => 'dashicons-chart-pie',


position


This parameter is for options-page metaboxes only, and is sent along to add_menu_page() to define the menu position. Only applicable if parent_slug is left empty.

'position' => 1,


admin_menu_hook


This parameter is for options-page metaboxes only and defaults to 'admin_menu', to register your options-page at the network level:

'admin_menu_hook' => 'network_admin_menu',


display_cb


This parameter is for options-page metaboxes only and allows overriding the options page form output.

'display_cb' => 'my_callback_function_to_display_output',


save_button


This parameter is for options-page metaboxes only and defines the text for the options page save button. defaults to 'Save'.

'save_button' => 'Save Settings',

Documentation:

  1. Home

  2. Installation
    Installation instructions for various environments

  3. Basic Usage
    Get up and running

  4. Advanced Usage
    Not for the faint of heart

  5. Field Types
    Breakdown of field types

  6. Examples
    Examples for registering fields

  7. Field Parameters
    Breakdown of common field parameters

  8. Display Options
    Limit display of boxes

  9. Box Properties
    Breakdown of box properties

  10. Troubleshooting
    Common issues & how to deal with them

  11. Notable Changes in CMB2 (from original CMB)
    CMB2 — a complete re-write

  12. Tips & Tricks
    10x your CMB2 skills

  13. REST API
    CMB2 data through WordPress REST API

  14. Javascript API
    Work with CMB2 JS events & hooks

Advanced tutorials:

External Resources:

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.