CMB2
Wiki: https://github.com/webdevstudios/CMB2/wiki
CMB2 - Custom Meta Boxes for
theme framework - theme settings, options, and meta
conditional code based on theme options
meta boxes and fields for theme options
meta boxes and fields for pages and posts
meta boxes and fields for custom post types
front end form submissions for user submitted content
CMB2 is used for creating Theme Options pages in wordpress themes. It also includes a library to be able to create custom field and meta boxes for posts and pages based on WPAlchemy.
Main Github page: https://github.com/WebDevStudios/CMB2
CMB Code snippet Library: https://github.com/WebDevStudios/CMB2-Snippet-Library
Tips and tricks: https://github.com/WebDevStudios/CMB2/wiki/Tips-&-Tricks
Example functions.php: https://github.com/WebDevStudios/CMB2/blob/master/example-functions.php
TutsPlus getting started: http://code.tutsplus.com/tutorials/toolbox-of-the-smart-wordpress-developer-cmb2--cms-24090
Features:
Create metaboxes to be used on post edit screens.
Create forms to be used on an options pages.link
Create forms to handle user meta and display them on user profile add/edit pages.
Flexible API that allows you to use CMB forms almost anywhere, even on the front-end. link
Several field types are included.link
Custom API hook that allows you to create your own field types.link
There are numerous hooks and filters, allowing you to modify many aspects of the library (without editing it directly).
Repeatable fields for most field types are supported, as well as repeatable field groups.
CMB2 is safe to bundle with any project. It will only load the newest version in the system.
Welcome to the CMB2 wiki! This is a code library for WordPress themes and plugins that makes it easy to add metaboxes, fields, and forms to WordPress.
The best way to get started is look at [example-functions.php](https://github.com/WebDevStudios/CMB2/blob/master/example-functions.php) and read the [Basic Usage](https://github.com/WebDevStudios/CMB2/wiki/Basic-Usage) tutorial.
Documentation:
1. Basic Usage(https://github.com/WebDevStudios/CMB2/wiki/Basic-Usage) Get up and running
1. Field Types(https://github.com/WebDevStudios/CMB2/wiki/Field-Types) A breakdown of each of the field types included with CMB2 as well as documentation for special field parameters.
1. Display Options(https://github.com/WebDevStudios/CMB2/wiki/Display-Options) Limit the display of your metaboxes
1. Troubleshooting(https://github.com/WebDevStudios/CMB2/wiki/Troubleshooting) Some common issues and how to deal with them
1. Notable Changes in CMB2 (from original CMB)(https://github.com/WebDevStudios/CMB2/wiki/Notable-Changes-in-CMB2) CMB2 is a complete re-write
1. Tips & Tricks(https://github.com/WebDevStudios/CMB2/wiki/Tips-&-Tricks) 10x your CMB2 skills.
Advanced tutorials:
1. Adding your own field types(https://github.com/WebDevStudios/CMB2/wiki/Adding-your-own-field-types) There's no limit to the kinds of fields you can make with CMB2
1. Adding your own show_on filters(https://github.com/WebDevStudios/CMB2/wiki/Adding-your-own-show_on-filters) Even more ways to limit the display of your metaboxes
3. Displaying metaboxes on the front-end(https://github.com/WebDevStudios/CMB2/wiki/Bringing-Metaboxes-to-the-Front-end) Let's take this outside wp-admin
4. Using CMB to create an Admin Theme Options Page(https://github.com/WebDevStudios/CMB2/wiki/Using-CMB-to-create-an-Admin-Theme-Options-Page) Optional replacement for the WordPress Settings API
External Resources:
1. CMB2 Metabox Code Generator(https://github.com/hasinhayder/cmb2-metabox-generator) - Generate CMB2 Metabox code with this visual form builder and save your time
2. Adding interactivity in metaboxes with javascript(http://hasin.me/2013/10/26/improving-ux-in-the-wordpress-admin-panel-with-interactive-meta-boxes/)
3. CMB2 Snippet Library(https://github.com/WebDevStudios/CMB2-Snippet-Library)
4. Basic CMB2 qTranslate-X integration plugin https://wordpress.org/plugins/integration-cmb2-qtranslate/
Even More Awesomeness
- CMB2 Snippet Library, a page that contains some very useful code snippets
Custom Field Types
- CMB2 Field Type: CMB Attached Posts Field from coreymcollins:
custom_attached_posts, for attaching posts to a page. - CMB2 Field Type: CMB2 Post Search field:
post_search_textadds a post-search dialog for searching/attaching other post IDs. - CMB2 Field Type: CMB2 User Search field from Mte90:
user_search_textadds a user-search dialog for searching/attaching other User IDs. - CMB2 Field Type: CMB2 RGBa Colorpicker from JayWood:
rgba_colorpickeradds a color picker that supports RGBa, (RGB with transparency (alpha) value). - CMB2 Field Type: Google Maps from mustardBees: Custom field type for Google Maps. The
pw_mapfield stores the latitude/longitude values which you can then use to display a map in your theme. - CMB2 Field Type: Select2 from mustardBees: Custom field types which use the Select2 script: The
pw_select fieldacts much like the default select field. However, it adds typeahead-style search allowing you to quickly make a selection from a large list Thepw_multiselectfield allows you to select multiple values with typeahead-style search. The values can be dragged and dropped to reorder - CMB Field Type: Slider from mattkrupnik: Adds a jQuery UI Slider field.
- CMB2 Remote Image Select from JayWood of WebDevStudios: Allows users to enter a URL in a text field and select a single image for use in post meta. Similar to Facebook's featured image selector.
- CMB Field Type: Sorter: This plugin gives you two CMB field types based on the Sorter script.
- CMB Field Type: Tags: WordPress-Tags-like field type for CMB2. note: this does not set the post tags, but simply provides a unique text input
Other Helpful Resources
- WordPress Shortcode Button: Uses CMB2 fields to generate fields for shortcode input modals.
- WDS-Simple-Page-Builder: Uses existing template parts in the currently-active theme to build a customized page with rearrangeable elements. Built with CMB2.
- CMB2 Example Theme: Demonstrate how to include CMB2 in your theme, as well as some cool tips and tricks.
- facetwp-cmb2: FacetWP integration with CMB2.
- CMB2 Metatabs Options from rogerlos: CMO makes it easy to create options pages with multiple metaboxes–and optional WordPress admin tabs.
- CMB2 Conditionals from jcchavezs: Allows developers to relate fields so the display of one is conditional on the value of another.
- CMB2 Metabox Code Generator from hasinhayder: Use this code generator to generate fully functional CMB2 metaboxes by visually adding fields in the designer.
How to make Theme options page
/**
* Silence is golden; exit if accessed directly
*/
if ( ! defined( 'ABSPATH' ) ) {
exit;
}
/**
* Bootstrap CMB2
*/
require_once 'inc/cmb2/init.php';
/**
* Load the CMB2 powered theme options page
*/
require_once 'inc/theme-options.php';
if ( ! function_exists( 'cmb2_example_theme_setup' ) ) :
/**
* Include and setup custom metaboxes and fields. (make sure you copy this file to outside the CMB2 directory)
*
* Be sure to replace all instances of 'yourprefix_' with your project's prefix.
* http://nacin.com/2010/05/11/in-wordpress-prefix-everything/
*
* @category YourThemeOrPlugin
* @package Demo_CMB2
* @license http://www.opensource.org/licenses/gpl-license.php GPL v2.0 (or later)
* @link https://github.com/WebDevStudios/CMB2
*/
/**
* Get the bootstrap! If using the plugin from wordpress.org, REMOVE THIS!
*/
if ( file_exists( dirname( __FILE__ ) . '/cmb2/init.php' ) ) {
require_once dirname( __FILE__ ) . '/cmb2/init.php';
} elseif ( file_exists( dirname( __FILE__ ) . '/CMB2/init.php' ) ) {
require_once dirname( __FILE__ ) . '/CMB2/init.php';
}
/**
* Hook in and register a metabox to handle a theme options page
*/
function yourprefix_register_theme_options_metabox() {
// Start with an underscore to hide fields from custom fields list
$option_key = '_yourprefix_theme_options';
/**
* Metabox for an options page. Will not be added automatically, but needs to be called with
* the `cmb2_metabox_form` helper function. See wiki for more info.
*/
$cmb_options = new_cmb2_box( array(
'id' => $option_key . 'page',
'title' => __( 'Theme Options Metabox', 'cmb2' ),
'hookup' => false, // Do not need the normal user/post hookup
'show_on' => array(
// These are important, don't remove
'key' => 'options-page',
'value' => array( $option_key )
),
) );
/**
* Options fields ids only need
* to be unique within this option group.
* Prefix is not needed.
*/
$cmb_options->add_field( array(
'name' => __( 'Site Background Color', 'cmb2' ),
'desc' => __( 'field description (optional)', 'cmb2' ),
'id' => 'bg_color',
'type' => 'colorpicker',
'default' => '#ffffff',
) );
}
/**
* CMB2 Theme Options
* @version 0.1.0
*/
class Myprefix_Admin {
/**
* Option key, and option page slug
* @var string
*/
private $key = 'myprefix_options';
/**
* Options page metabox id
* @var string
*/
private $metabox_id = 'myprefix_option_metabox';
/**
* Options Page title
* @var string
*/
protected $title = '';
/**
* Options Page hook
* @var string
*/
protected $options_page = '';
/**
* Constructor
* @since 0.1.0
*/
public function __construct() {
// Set our title
$this->title = __( 'Site Options', 'myprefix' );
}
/**
* Initiate our hooks
* @since 0.1.0
*/
public function hooks() {
add_action( 'admin_init', array( $this, 'init' ) );
add_action( 'admin_menu', array( $this, 'add_options_page' ) );
add_action( 'cmb2_admin_init', array( $this, 'add_options_page_metabox' ) );
}
/**
* Register our setting to WP
* @since 0.1.0
*/
public function init() {
register_setting( $this->key, $this->key );
}
/**
* Add menu options page
* @since 0.1.0
*/
public function add_options_page() {
$this->options_page = add_menu_page( $this->title, $this->title, 'manage_options', $this->key, array( $this, 'admin_page_display' ) );
// Include CMB CSS in the head to avoid FOUC
add_action( "admin_print_styles-{$this->options_page}", array( 'CMB2_hookup', 'enqueue_cmb_css' ) );
}
/**
* Admin page markup. Mostly handled by CMB2
* @since 0.1.0
*/
public function admin_page_display() {
?>
<div class="wrap cmb2-options-page <?php echo $this->key; ?>">
<h2><?php echo esc_html( get_admin_page_title() ); ?></h2>
<?php cmb2_metabox_form( $this->metabox_id, $this->key ); ?>
</div>
<?php
}
/**
* Add the options metabox to the array of metaboxes
* @since 0.1.0
*/
function add_options_page_metabox() {
// hook in our save notices
add_action( "cmb2_save_options-page_fields_{$this->metabox_id}", array( $this, 'settings_notices' ), 10, 2 );
$cmb = new_cmb2_box( array(
'id' => $this->metabox_id,
'hookup' => false,
'cmb_styles' => false,
'show_on' => array(
// These are important, don't remove
'key' => 'options-page',
'value' => array( $this->key, )
),
) );
// Set our CMB2 fields
$cmb->add_field( array(
'name' => __( 'Test Text', 'myprefix' ),
'desc' => __( 'field description (optional)', 'myprefix' ),
'id' => 'test_text',
'type' => 'text',
'default' => 'Default Text',
) );
$cmb->add_field( array(
'name' => __( 'Test Color Picker', 'myprefix' ),
'desc' => __( 'field description (optional)', 'myprefix' ),
'id' => 'test_colorpicker',
'type' => 'colorpicker',
'default' => '#bada55',
) );
}
/**
* Register settings notices for display
*
* @since 0.1.0
* @param int $object_id Option key
* @param array $updated Array of updated fields
* @return void
*/
public function settings_notices( $object_id, $updated ) {
if ( $object_id !== $this->key || empty( $updated ) ) {
return;
}
add_settings_error( $this->key . '-notices', '', __( 'Settings updated.', 'myprefix' ), 'updated' );
settings_errors( $this->key . '-notices' );
}
/**
* Public getter method for retrieving protected/private variables
* @since 0.1.0
* @param string $field Field to retrieve
* @return mixed Field value or exception is thrown
*/
public function __get( $field ) {
// Allowed fields to retrieve
if ( in_array( $field, array( 'key', 'metabox_id', 'title', 'options_page' ), true ) ) {
return $this->{$field};
}
throw new Exception( 'Invalid property: ' . $field );
}
}
/**
* Helper function to get/return the Myprefix_Admin object
* @since 0.1.0
* @return Myprefix_Admin object
*/
function myprefix_admin() {
static $object = null;
if ( is_null( $object ) ) {
$object = new Myprefix_Admin();
$object->hooks();
}
return $object;
}
/**
* Wrapper function around cmb2_get_option
* @since 0.1.0
* @param string $key Options array key
* @return mixed Option value
*/
function myprefix_get_option( $key = '' ) {
return cmb2_get_option( myprefix_admin()->key, $key );
}
// Get it started
myprefix_admin();
GROUP FIELDS
Now you can setup rows and columns even on group fields too. First Create your cmb2 metabox with group fields like you are used to:
<?php
$prefix = '_yourprefix_group_';
$cmb_group = new_cmb2_box(array(
'id' => $prefix . 'metabox',
'title' => __('Repeating Field Group', 'cmb2'),
'object_types' => array('page',),
));
$field1 = $cmb_group->add_field(array(
'name' => __('Test Text', 'cmb2'),
'desc' => __('field description (optional)', 'cmb2'),
'id' => $prefix . 'text',
'type' => 'text',
));
$field2 = $cmb_group->add_field(array(
'name' => __('Test Text Small', 'cmb2'),
'desc' => __('field description (optional)', 'cmb2'),
'id' => $prefix . 'textsmall',
'type' => 'text',
));
// $group_field_id is the field id string, so in this case: $prefix . 'demo'
$group_field_id = $cmb_group->add_field(array(
'id' => $prefix . 'demo',
'type' => 'group',
'options' => array(
'group_title' => __('Entry {#}', 'cmb2'), // {#} gets replaced by row number
'add_button' => __('Add Another Entry', 'cmb2'),
'remove_button' => __('Remove Entry', 'cmb2'),
'sortable' => true,
),
));
$gField1 = $cmb_group->add_group_field($group_field_id, array(
'name' => __('Entry Title', 'cmb2'),
'id' => 'title',
'type' => 'text',
));
$gField2 = $cmb_group->add_group_field($group_field_id, array(
'name' => __('Description', 'cmb2'),
'description' => __('Write a short description for this entry', 'cmb2'),
'id' => 'description',
'type' => 'textarea_small',
));
Now pay attention to the addCmb2GroupGrid() method
if (!is_admin()) {
return;
}
//Create a default grid
$cmb2Grid = new \Cmb2Grid\Grid\Cmb2Grid($cmb_group);
//Create now a Grid of group fields
$cmb2GroupGrid = $cmb2Grid->addCmb2GroupGrid($group_field_id);
$row = $cmb2GroupGrid->addRow();
$row->addColumns(array(
$gField1, $gField2
));
//Now setup your columns like you generally do, even with group fields
$row = $cmb2Grid->addRow();
$row->addColumns(array(
$field1, $field2
));
$row = $cmb2Grid->addRow();
$row->addColumns(array(
$cmb2GroupGrid // Can be $group_field_id also
));
?>