Basic Usage
Table of Contents generated with DocToc
- Quick Start
- Getting Started
- Create a metabox
- Creating the metabox using a plugin
- Display the Metadata
- Adding metaboxes to user profile
- Caveats for bundling and including CMB2.
This code is designed to be run inside themes and plugins. Proper structure would look like:
/my-theme
/cmb2
functions.php
index.php
screenshot.png
styles.css
Open example-functions.php and copy/paste all of the code into functions.php
. Create a new page and you should see all the example metaboxes in the page editor. Use get_post_meta() to get/use the data.
First, you need to get the bootstrap and start the engine. To do so, add the following code to functions.php
. There are some caveats to including CMB2 in your plugin or theme. Please review them below.
Note: If you are installing the plugin from WordPress.org, you can skip this step as it is handled by the plugin.
/**
* Get the bootstrap!
* (Update path to use cmb2 or CMB2, depending on the name of the folder.
* Case-sensitive is important on some systems.)
*/
require_once __DIR__ . '/cmb2/init.php';
Notes:
-
init.php
needs to be required outside any hook. It needs to be loaded as early as possible. - Do not do any kind of conditional loading, e.g.
if ( ! class_exists....
. CMB2 will handle that.
Now that you've included the CMB2 engine, you can start adding metaboxes with the following code inside functions.php
:
add_action( 'cmb2_admin_init', 'cmb2_sample_metaboxes' );
/**
* Define the metabox and field configurations.
*/
function cmb2_sample_metaboxes() {
/**
* Initiate the metabox
*/
$cmb = new_cmb2_box( array(
'id' => 'test_metabox',
'title' => __( 'Test Metabox', 'cmb2' ),
'object_types' => array( 'page', ), // Post type
'context' => 'normal',
'priority' => 'high',
'show_names' => true, // Show field names on the left
// 'cmb_styles' => false, // false to disable the CMB stylesheet
// 'closed' => true, // Keep the metabox closed by default
) );
// Regular text field
$cmb->add_field( array(
'name' => __( 'Test Text', 'cmb2' ),
'desc' => __( 'field description (optional)', 'cmb2' ),
'id' => 'yourprefix_text',
'type' => 'text',
'show_on_cb' => 'cmb2_hide_if_no_cats', // function should return a bool value
// 'sanitization_cb' => 'my_custom_sanitization', // custom sanitization callback parameter
// 'escape_cb' => 'my_custom_escaping', // custom escaping callback parameter
// 'on_front' => false, // Optionally designate a field to wp-admin only
// 'repeatable' => true,
) );
// URL text field
$cmb->add_field( array(
'name' => __( 'Website URL', 'cmb2' ),
'desc' => __( 'field description (optional)', 'cmb2' ),
'id' => 'yourprefix_url',
'type' => 'text_url',
// 'protocols' => array('http', 'https', 'ftp', 'ftps', 'mailto', 'news', 'irc', 'gopher', 'nntp', 'feed', 'telnet'), // Array of allowed protocols
// 'repeatable' => true,
) );
// Email text field
$cmb->add_field( array(
'name' => __( 'Test Text Email', 'cmb2' ),
'desc' => __( 'field description (optional)', 'cmb2' ),
'id' => 'yourprefix_email',
'type' => 'text_email',
// 'repeatable' => true,
) );
// Add other metaboxes as needed
}
Note: For more metabox examples, see example-functions.php
Here is a cool video overview of what you will get with the example-functions.php
file:
You can also create the metabox by creating a standard WordPress plugin and simply pasting the above code below the header of the plugin.
Finally, you need to be able to extract the metadata and put it to work. In your theme or plugin file, use the get_post_meta() function to display your metadata. Remember, you must pass the post ID!
<?php
// Grab the metadata from the database
$text = get_post_meta( get_the_ID(), 'yourprefix_text', true );
// Echo the metadata
echo esc_html( $text );
?>
Let's assume you created a metabox with the field outlined above, and want to display this on the single page template:
<?php
/**
* The template for displaying all pages.
*
* This is the template that displays all pages by default.
* Please note that this is the WordPress construct of pages
* and that other 'pages' on your WordPress site will use a
* different template.
*
* @package WordPress
* @subpackage Twenty_Eleven
* @since Twenty Eleven 1.0
*/
get_header(); ?>
<div id="primary">
<div id="content" role="main">
<?php while ( have_posts() ) : the_post(); ?>
<?php get_template_part( 'content', 'page' ); ?>
<?php
$text = get_post_meta( get_the_ID(), 'yourprefix_text', true );
$email = get_post_meta( get_the_ID(), 'yourprefix_email', true );
$url = get_post_meta( get_the_ID(), 'yourprefix_url', true );
echo esc_html( $text );
echo is_email( $email );
echo esc_url( $url );
?>
<?php comments_template( '', true ); ?>
<?php endwhile; // end of the loop. ?>
</div><!-- #content -->
</div><!-- #primary -->
<?php get_footer(); ?>
For more information on working with post meta, see the Codex page for get_post_meta(), or check out the Post Meta Bootcamp. Remember, to escape any and all data! Using proper data validation when working with post meta is the right thing to do. Trust no one!
For more example code, see example-functions.php
To add custom metaboxes to the user profile page, you can set the object_types
parameter to array( 'user' )
to indicate that the metaboxes should be displayed on the user profile (rather than a specific post type) and that the meta information should be stored against user_meta, rather than post_meta.
An example metabox can be seen in example-functions.php
Note that the Metabox description
and name
parameters will not display. You can label your user settings section by adding a title
field as the first field.
This section is to highlight some dos/don'ts for including CMB2. CMB2 has an intelligent method for loading only one version of itself and only the newest version (we also have a strict commitment to backwards-compatibility so that newer versions won't break code which was built with previous versions). If you do not include it properly, it will likely result in unintended consequences. For more background info about how/why CMB2 does it this way, read this post.
-
Do: Include the files directly from your theme or plugin. E.g.:
require_once __DIR__ . '/includes/cmb2/init.php';
-
Don't: Include the files from a hook. E.g.:
// DON'T DO THIS add_action( 'init', 'wprpt_initialize_cmb_init', 10 ); function wprpt_initialize_cmb_init() { require_once __DIR__ . '/includes/cmb2/init.php'; }
-
Do: Use case-sensitive paths to the include file. E.g.:
require_once __DIR__ . '/includes/CMB2/init.php';
or
require_once __DIR__ . '/includes/cmb2/init.php';
If you download CMB2 from the WordPress plugin repo, it will be a lowercase directory,
cmb2
. However, due to Github's naming conventions, if you clone this repo, or download it, or download a release on the releases page, it will be an uppercase directory,CMB2
. Obviously, you can name the directory anything you want, when you're bundling/including it in your theme or plugin. -
Don't: Use a
class_exists()
check before including. (CMB2 handles that magic on it's own.)// DON'T DO THIS if ( ! class_exists( 'Some_CMB2_Class' ) ) { require_once __DIR__ . '/includes/cmb2/init.php'; }
-
Do: Use the proper CMB2 package. Composer is a good recommended way, but if you're going to bundle CMB2 in your theme/plugin, download the zip file from the WordPress plugin repo.
-
Don't: Clone the repo into your project. You'll clone down all the development-only files/folders. If submitted your theme to the WordPress theme repo with CMB2 bundled, you may be rejected for including these development files.
Documentation:
-
Installation
Installation instructions for various environments -
Basic Usage
Get up and running -
Advanced Usage
Not for the faint of heart -
Field Types
Breakdown of field types -
Examples
Examples for registering fields -
Field Parameters
Breakdown of common field parameters -
Display Options
Limit display of boxes -
Box Properties
Breakdown of box properties -
Troubleshooting
Common issues & how to deal with them -
Notable Changes in CMB2 (from original CMB)
CMB2 — a complete re-write -
Tips & Tricks
10x your CMB2 skills -
REST API
CMB2 data through WordPress REST API -
Javascript API
Work with CMB2 JS events & hooks
Advanced tutorials:
- Adding your own field types
- Adding your own show_on filters
- Displaying boxes on the front-end
- Using CMB to create an Admin Theme Options Page
- Create New Posts (or Custom Post Type) Entries Using A Front End Form
- Disable CMB2 Styles on Front End Forms
External Resources: