Contributors: webdevstudios, jtsternberg, gregrickaby, tw2113, patrickgarman, JPry
Donate link: http://webdevstudios.com
Tags: metaboxes, forms, fields, options, settings
Requires at least: 3.8.0
Tested up to: 4.4.2
Stable tag: 2.2.2
License: GPLv2 or later
License URI: http://www.gnu.org/licenses/gpl-2.0.html
Complete contributors list found here: github.com/WebDevStudios/CMB2/graphs/contributors
CMB2 is a developer's toolkit for building metaboxes, custom fields, and forms for WordPress that will blow your mind.
Download plugin on wordpress.org
CMB2 is a complete rewrite of Custom Metaboxes and Fields for WordPress. To get started, please follow the examples in the included example-functions.php
file and have a look at the basic usage instructions.
You can see a list of available field types here.
If you are coming from the original "Custom Metaboxes and Fields for WordPress" plugin, please read this post for the CMB2 background story.
- Create metaboxes to be used on post edit screens.
- Create forms to be used on an options pages.
- 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.
- Several field types are included.
- Custom API hook that allows you to create your own field types.
- 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.
- Thanks to many in the CMB2 community and to our friends at wp-translations.org, we have a good start on several translations for CMB2. Please feel free to work with wp-translations.org to provide even more!
-
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_text
adds a post-search dialog for searching/attaching other post IDs. -
CMB2 Field Type: CMB2 User Search field from Mte90:
user_search_text
adds a user-search dialog for searching/attaching other User IDs. -
CMB2 Field Type: CMB2 RGBa Colorpicker from JayWood:
rgba_colorpicker
adds 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_map
field 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 field
acts much like the default select field. However, it adds typeahead-style search allowing you to quickly make a selection from a large list - The
pw_multiselect
field allows you to select multiple values with typeahead-style search. The values can be dragged and dropped to reorder
- The
-
CMB Field Type: Slider from mattkrupnik: Adds a jQuery UI Slider field.
-
WDS CMB2 Date Range Field from dustyf of WebDevStudios: Adds a date range 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
-
CMB2 Term Select: Special CMB2 Field that allows users to define an autocomplete text field for terms. Note: this will set the taxonomy terms, but has the option (
'apply_term' => false
) to disable and save the term ids as data instead (like for options pages, etc). -
CMB2 Related Links: Allows users to add a related links via a repeating field group. Field inputs are powered by the CMB2 Field Type: CMB2 Post Search field documented above, and so each link can be populated with existing WordPress content by clicking on the search button. Note: this is not a standard field type, but instead a function you use in combination with CMB2::add_field().
- 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-grid from origgami: A grid system for WordPress CMB2 library that allows the creation of columns for a better layout in the admin.
- 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 willthemoor: Skip the boring bits. Use this generator to create fully functional CMB2 metaboxes easily. Now with bulk entry!
All contributions welcome. If you would like to submit a pull request, please check out the trunk branch and pull request against it. Please read the CONTRIBUTING doc for more details.
A complete list of all our awesome contributors found here: github.com/WebDevStudios/CMB2/graphs/contributors
If installing the plugin from wordpress.org:
- Upload the entire
/CMB2
directory to the/wp-content/plugins/
directory. - Activate CMB2 through the 'Plugins' menu in WordPress.
- Copy (and rename if desired)
example-functions.php
into to your theme or plugin's directory. - Edit to only include the fields you need and rename the functions.
- Profit.
If including the library in your plugin or theme:
- Place the CMB2 directory inside of your theme or plugin.
- Copy (and rename if desired)
example-functions.php
into a folder above the CMB2 directory OR copy the entirety of its contents to your theme'sfunctions.php
file. - Edit to only include the fields you need and rename the functions (CMB2 directory should be left unedited in order to easily update the library).
- Profit.
- You can now set admin post-listing columns with an extra field parameter,
'column' => true,
. If you want to dictate what position the column is, use'column' => array( 'position' => 2 ),
. If you want to dictate the column title (instead of using the field'name'
value), use'column' => array( 'name' => 'My Column' ),
. If you need to specify the column display callback, set the'display_cb'
parameter to a callback function. Columns work for post (all post-types), comment, user, and term object types. - Updated Datepicker styles using JJJ's "jQuery UI Datepicker CSS for WordPress", so props Props @stuttter, @johnjamesjacoby. Also cleaned up the timepicker styles (specifically the buttons) to more closely align with the datepicker and WordPress styles.
- CMB2 is now a lot more intelligent about where it is located in your installation. This update should solve almost all of the reasons to use the
'cmb2_meta_box_url'
filter (thought it will continue to work as expected). (#27, #118, #432, related wiki item) - Implement CMB2_Ajax as a singleton. Props jrfnl (#602).
- Add
classes
andclasses_cb
CMB2 box params which allows you to add additional classes to the cmb-wrap. Theclasses
parameter can take a string or array, and theclasses_cb
takes a callback which returns a string or array. The callback will receive$cmb
as an argument. These classes are also passed through a new filter,'cmb2_wrap_classes'
, which receives the array of classes as the first argument, and the CMB2 object as the second. Reported/requested in #364. - Make the
'title'
field type accept extra arguments. Props @vladolaru, @pixelgrade (#656). - Updated
cmb2_get_oembed()
function to NOT return the "remove" link, as it's intended for outputting the oembed only. This is a backwards-compatibility concern. If you were depending on the "remove" link, usecmb2_ajax()->get_oembed( $args )
instead. - New function,
cmb2_do_oembed()
', which is hooked to'cmb2_do_oembed'
, so you can usedo_action( 'cmb2_do_oembed', $args )
in your themes withoutfunction_exists()
checks. - New method,
CMB2:set_prop( $property, $value )
, for setting a CMB2 metabox object property. - The
CMB2_Field
object instances will now have acmb_id
property and aget_cmb
method to enable access to the field'sCMB2
parent object's instance, in places like field callbacks and filters (e.g.$cmb = $field->get_cmb();
). - Add a
data-fieldtype
attribute to the field rows for simpler identification in Javascript. - Moved each type in
CMB2_Types
to it's own class so that each field type can handle it's own field display, and added the infrastructure to maintainn back-compatibility. - New
CMB2_Utils
methods,notempty()
andfilter_empty()
, both of which considernull
,''
andfalse
as empty, but allow0
(for saving0
as a field value). - New
CMB2_Utils
public methods,get_url_from_dir()
,get_file_ext()
,get_file_name_from_path()
, andwp_at_least()
. - Add a
cmb_pre_init
Javascript event to allow overriding CMB2 defaults via JS.
- Fix issue with 'default' callback not being applied in all instances. Introduced new
CMB2_Field::get_default()
method, and'default_cb'
field parameter. Using the'default'
field parameter with a callback will be deprecated in the next few releases. (#572). - Be sure to call
CMB2_Field::row_classes()
for group field rows. Also, update CSS to use the "cmb-type-group" classname instead of "cmb-repeat-group-wrap". - Introduce new
'text'
and'text_cb'
field parameters for overriding CMB2 text strings instead of using the'options'
array. (#630) - Fix bug where the value of '0' could not be saved in group fields.
- Fix bug where a serialized empty array value in the database for a repeatable field would output as "Array".
- Allow for optional/empty money field. Props @jrfnl (#577).
- The
CMB2::$updated
parameter (which contains field ids for all fields updated during a save) now also correctly adds group field ids to the array.
- The CMB2 url (for css/js resources) does not define properly in all WAMP/XAMP (Windows) environments.
- Metabox containing WYSIWYG editor cannot be moved or used in a repeatable way at this time (this is a TinyMCE issue).
- Not all fields work well in a repeatable group.