CMB2

Downloads:

CMB2 is a developer’s toolkit for building metaboxes, custom fields, and forms for WordPress that will blow your mind. Easily manage meta for posts, terms, users, comments, or create custom option pages.

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.

Contribution

Development occurs on Github, and all contributions welcome. Please read the CONTRIBUTING doc for more details.

A complete list of all our awesome contributors found here: github.com/CMB2/CMB2/graphs/contributors

Features:

Translation

If you are looking to provide language translation files, Please do so via WordPress Plugin Translations.

Documentation

  • CMB2 documentation can be found at the CMB2 wiki on github. Also, If you’re into reading code and inline documentation, we tried to keep all functions and methods fully inline-documented.

3rd Party Resources

Custom Field Types

Other Helpful Resources

Links

View CHANGELOG

Known Issues

  • 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.

View plugin listing on wordpress.org →

Download

Latest version: Download CMB2 v2.10.1 [zip]

Installation

If installing the plugin from wordpress.org:

  1. Upload the entire /CMB2 directory to the /wp-content/plugins/ directory.
  2. Activate CMB2 through the ‘Plugins’ menu in WordPress.
  3. Copy (and rename if desired) example-functions.php into to your theme or plugin’s directory.
  4. Edit to only include the fields you need and rename the functions.
  5. Profit.

If including the library in your plugin or theme:

  1. Place the CMB directory inside of your theme or plugin.
  2. Copy (and rename if desired) example-functions.php into a folder above the CMB directory OR copy the entirety of its contents to your theme’s functions.php file.
  3. Edit to only include the fields you need and rename the functions (CMB directory should be left unedited in order to easily update the library).
  4. Profit.

Changelog

Bug Fixes

  • Fix back-compatibility when adding group field sub-fields via old array method (vs using the CMB2:add_group_field() method). Thanks to norcross for reporting.
  • Fix occasional jQuery issues with group-field indexes.

2.0.3 – 2015-03-15

Enhancements

  • New constant, CMB2_DIR, which stores the file-path to the CMB2 directory.
  • text_date, text_time, text_date_timestamp, text_datetime_timestamp, and text_datetime_timestamp_timezone field types now take an arguments array so they can be extended by custom field types.
  • Removed auto-scroll when adding groups. To re-add the feature, use the snippet/plugin here. (#205)
  • Updated Timepicker utilizing the @trentrichardson jQuery Timepicker add-on (https://github.com/trentrichardson/jQuery-Timepicker-Addon), and updated Datepicker styles. Props JonMasterson. (#204, #206, #45).
  • Added a callback option for the field default value. The callback gets passed an array of all the field parameters as the first argument, and the field object as the second argument. (which means you can get the post id using $field->object_id). (#233).
  • New CMB2::get_field() method and cmb2_get_field helper function for retrieving a CMB2_Field object from the array of registered fields for a metabox.
  • New CMB2::get_sanitized_values() method and cmb2_get_metabox_sanitized_values helper function for retrieving sanitized values from an array of values (usually $_POST data).
  • New 'save_fields' metabox property that can be used to disable (by setting 'save_fields' => false) the automatic saving of the fields when the form is submitted. These can be useful when you want to handle the saving of the fields yourself, or want to use submitted data for other purposes like generating new posts, or sending emails, etc.

Bug Fixes

  • Fix commented out text_datetime_timestamp_timezone field registration example in example-functions.php. Props cliffordp, (#203).
  • Fix sidebar styling for money fields and fields with textareas. (#234)
  • Fix CMB2_Sanitize class to properly use the stripslashed value (which was added in #162 but never used). Props dustyf, (#241).

2.0.2 – 2015-02-15

Enhancements

  • Use the more appropriate add_meta_boxes hook for hooking in metaboxes to post-edit screen. Thanks @inspiraaz for reporting. (#161)
  • Add a row_classes field param which allows you to add additional classes to the cmb-row wrap. This parameter can take a string, or array, or can take a callback that returns a string or array. The callback will receive $field_args as the first argument, and the CMB2_Field $field object as the second argument. Reported/requested in #68.
  • New constant, CMB2_LOADED, which you can use to check if CMB2 is loaded for your plugins/themes with CMB2 dependency.
  • New hooks, cmb2_init_before_hookup and cmb2_after_init.
  • New API for adding metaboxes and fields, demonstrated in example-functions.php. In keeping with backwards-compatibility, the cmb2_meta_boxes filter method will still work, but is not recommended. New API includes new_cmb2_box helper function to generate a new metabox, and returns a $cmb object to add new fields (via the CMB2::add_field() and CMB2::add_group_field() methods).
  • New CMB2 method, CMB2::remove_field().
  • New CMB2_Boxes method, CMB2_Boxes::remove().
  • When clicking on a file/image in the file, or file_list type, the media modal will open with that image selected. Props johnsonpaul1014, (#120).

2.0.1 – 2015-02-02

2.0.1 is the official version after beta, and includes all the changes from 2.0.0 (beta).

2.0.0(beta) – 2014-08-16

2.0.0 is the official version number for the transition to CMB2, and 2.0.1 is the official version after beta. It is a complete rewrite. Improvements and fixes are listed below. Note: This release requires WordPress 3.8+

Enhancements

Bug Fixes

  • New mechanism to ensure CMB2 only loads the most recent version of CMB2 in your system. This fixes the issue where another bundled version could conflict or take precendent over your up-to-date version.
  • Fix issue with field labels being hidden. Props mustardBees, (#48).
  • Address issues with autoloading before autoloader is setup. Props JPry, (#56).
  • Fixed ‘show_on_cb’ for field groups. Props marcusbattle, (#98).
  • Make get_object_terms work with and without object caching. Props joshlevinson, (#105).
  • Don’t use __DIR__ in example-functions.php to ensure PHP 5.2 compatibility. Props bryceadams, (#129).
  • Added support for radio input swapping in repeatable fields. Props DevinWalker, (#138, #149).
  • Fix metabox form not being returned to caller. Props akshayagarwal, (#145).
  • Run stripslashes before saving data, since WordPress forces magic quotes. Props clifgriffin, (#162).

1.3.0 – (never released, merged into CMB2)

Enhancements

  • Localize Date, Time, and Color picker defaults so that they can be overridden via the cmb_localized_data filter. (#528)
  • Change third parameter for ‘cmb_metabox_form’ to be an args array. Optional arguments include echo, form_format, and save_button.
  • Add support for show_option_none argument for taxonomy_select and taxonomy_radio field types. Also adds the following filters: cmb_all_or_nothing_types, cmb_taxonomy_select_default_value, cmb_taxonomy_select_{$this->_id()}_default_value, cmb_taxonomy_radio_{$this->_id()}_default_value, cmb_taxonomy_radio_default_value. Props @pmgarman, (#569).
  • Make the list items in the file_list field type drag & drop sortable. Props twoelevenjay, (#603).

Bug Fixes

1.2.0 – 2014-05-03

Enhancements

  • Add support for custom date/time formats. Props @Scrent. (#506)
  • Simplify wysiwyg escaping and allow it to be overridden via the escape_cb parameter. (#491)
  • Add a ‘Select/Deselect all’ button for the multicheck field type.
  • Add title option for repeatable groups. Title field takes an optional replacement hash, “{#}” that will be replaced by the row number.
  • New field parameter, show_on_cb, allows you to conditionally display a field via a callback. (#47)
  • Unit testing (the beginning). Props @brichards and @camdensegal.

Bug Fixes

  • Fixed issue where remove file button wouldn’t clear the url field. (#514)
  • wysiwyg fields now allow underscores. Fixes some wysiwyg display issues in WordPress 3.8. Props @lswilson. (#491)
  • Nonce field should only be added once per page. (#521)
  • Fix in_array issue when a post does not have any saved terms for a taxonomy multicheck. (#527)
  • Fixed error: ‘Uninitialized string offset: 0 in cmb_Meta_Box_field.php…`. Props @DevinWalker. (#539, #549))
  • Fix missing file field description. (#543, #547)

1.1.3 – 2014-04-07

Bug Fixes

  • Update cmb_get_field_value function as it was passing the parameters to cmb_get_field in the wrong order.
  • Fix repeating fields not working correctly if meta key or prefix contained an integer. (#503)

1.1.2 – 2014-04-05

Bug Fixes

  • Fix issue with cmb_Meta_Box_types.php calling a missing method, image_id_from_url. (#502)

1.1.1 – 2014-04-03

Bug Fixes

  • Radio button values were not showing saved value. (#500)

1.1.0 – 2014-04-02

Enhancements

  • Repeatable groups
  • Support for more fields to be repeatable, including oEmbed field, and date, time, and color picker fields, etc.
  • Codebase has been revamped to be more modular and object-oriented.
  • New filter, "cmb_{$element}_attributes" for modifying an element’s attributes.
  • Every field now supports an attributes parameter that takes an array of attributes. Read more.
  • Removed cmb_std_filter in favor of cmb_default_filter. THIS IS A BREAKING CHANGE
  • Better handling of labels in sidebar. They are now placed on top of the input rather than adjacent.
  • Added i18n compatibility to text_money. props @ArchCarrier, (#485)
  • New helper functions: cmb_get_field and cmb_get_field_value for getting access to CMB’s field object and/or value.
  • New JavaScript events, cmb_add_row and cmb_remove_row for hooking in and manipulating the new row’s data.
  • New filter, cmb_localized_data, for modifiying localized data passed to the CMB JS.

Bug Fixes

  • Resolved occasional issue where only the first character of the label/value was displayed. props @mustardBees, (#486)

1.0.2 – 2014-03-03

Enhancements

  • Change the way the 'cmb_validate_{$field['type']}' filter works.
    It is now passed a null value vs saved value. If null is returned, default sanitization will follow. THIS IS A BREAKING CHANGE. If you’re already using this filter, take note.
  • All field types that take an option array have been simplified to take key => value pairs (vs array( 'name' => 'value', 'value' => 'key', )). This effects the ‘select’, ‘radio’, ‘radio_inline’ field types. The ‘multicheck’ field type was already using the key => value format. Backwards compatibility has been maintained for those using the older style.
  • Added default value option for taxonomy_select field type. props @darlantc, (#473)
  • Added preview_size parameter for file_list field type. props @IgorCode, (#471)
  • Updated file_list images to be displayed horizontally instead of vertically. props @IgorCode, (#467)
  • Use get_the_terms where possible since the data is cached.

Bug Fixes

  • Fixed wysiwyg escaping slashes. props @gregrickaby, (#465)
  • Replaced __DIR__, as dirname( __FILE__ ) is easier to maintain back-compatibility.
  • Fixed missing table styling on new posts. props @mustardBees, (#438)
  • Fix undeclared JS variable. @veelen, (#451)
  • Fix file_list errors when removing all files and saving.
  • Set correct object_id to be used later in cmb_show_on filter. @lauravaq, (#445)
  • Fix sanitization recursion memory issues.

1.0.1 – 2014-01-24

Enhancements

  • Now works with option pages and site settings. (view example in wiki)
  • two filters to override the setting and getting of options, cmb_override_option_get_$option_key and cmb_override_option_save_$option_key respectively. Handy for using plugins like WP Large Options (also here).
  • Improved styling on taxonomy (*tease*) and options pages and for new 3.8 admin UI.
  • New sanitization class to sanitize data when saved.
  • New callback field parameter, sanitization_cb, for performing your own sanitization.
  • new cmb_Meta_Box_types::esc() method that handles escaping data for display.
  • New callback field parameter, escape_cb, for performing your own data escaping, as well as a new filter, "cmb_types_esc_{$field_type}".

Bug Fixes

  • Fixed wysiwyg editor button padding. props @corvannoorloos, (#391)
  • A few php < 5.3 errors were addressed.
  • Fields with quotation marks no longer break the input/textarea fields.
  • metaboxes for Attachment pages now save correctly. Thanks @nciske for reporting. (#412)
  • Occasionally fields wouldn’t save because of the admin show_on filter.
  • Smaller images loaded to the file field type will no longer be blown up larger than their dimensions.

1.0.0 – 2013-11-30

  • Added text_datetime_timestamp_timezone type, a datetime combo field with an additional timezone drop down, props @dessibelle
  • Added select_timezone type, a standalone time zone select dropdown. The time zone select can be used with standalone text_datetime_timestamp if desired. Props @dessibelle
  • Added text_url type, a basic url field. Props @dessibelle
  • Added text_email type, a basic email field. Props @dessibelle
  • Added ability to display metabox fields in frontend. Default is true, but can be overriden using the cmb_allow_frontend filter. If set to true, an entire metabox form can be output with the cmb_metabox_form( $meta_box, $object_id, $echo ) function. Props @dessibelle, @messenlehner & @jtsternberg.
  • Added hook cmb_after_table after all metabox output. Props @wpsmith
  • file_list now works like a repeatable field. Add as many files as you want. Props @coreymcollins
  • text, text_small, text_medium, text_url, text_email, & text_money fields now all have the option to be repeatable. Props @jtsternberg
  • Custom metaboxes can now be added for user meta. Add them on the user add/edit screen, or in a custom user profile edit page on the front-end. Props @tw2113, @jtsternberg

0.9.4

  • Added field “before” and “after” options for each field. Solves issue with ‘$’ not being the desired text_money monetary symbol, props @GaryJones
  • Added filter for ‘std’ default fallback value, props @messenlehner
  • Ensure oEmbed videos fit in their respective metaboxes, props @jtsternberg
  • Fixed issue where an upload field with ‘show_names’ disabled wouldn’t have the correct button label, props @jtsternberg
  • Better file-extension check for images, props @GhostToast
  • New filter, cmb_valid_img_types, for whitelisted image file-extensions, props @jtsternberg

0.9.3

  • Added field type and field id classes to each cmb table row, props @jtsternberg

0.9.2

  • Added post type comparison to prevent storing null values for taxonomy selectors, props @norcross

0.9.1

  • Added oEmbed field type with ajax display, props @jtsternberg

0.9

  • Note: This release requires WordPress 3.3+
  • Cleaned up scripts being queued, props @jaredatch
  • Cleaned up and reorganized jQuery, props @GaryJones
  • Use $pagenow instead of custom $current_page, props @jaredatch
  • Fixed CSS, removed inline styles, now all in style.css, props @jaredatch
  • Fixed multicheck issues (issue #48), props @jaredatch
  • Fixed jQuery UI datepicker CSS conflicting with WordPress UI elements, props @jaredatch
  • Fixed zeros not saving in fields, props @GaryJones
  • Fixed improper labels on radio and multicheck fields, props @jaredatch
  • Fixed fields not rendering properly when in sidebar, props @jaredatch
  • Fixed bug where datepicker triggers extra space after footer in Firefox (issue #14), props @jaredatch
  • Added jQuery UI datepicker packaged with 3.3 core, props @jaredatch
  • Added date time combo picker, props @jaredatch
  • Added color picker, props @jaredatch
  • Added readme.md markdown file, props @jaredatch

0.8 – 2012-01-19

  • Added jQuery timepicker, props @norcross
  • Added ‘raw’ textarea to convert special HTML entities back to characters, props @norcross
  • Added missing examples on example-functions.php, props @norcross

0.7

  • Added the new wp_editor() function for the WYSIWYG dialog box, props @jcpry
  • Created ‘cmb_show_on’ filter to define your own Show On Filters, props @billerickson
  • Added page template show_on filter, props @billerickson
  • Improvements to the ‘file’ field type, props @randyhoyt
  • Allow for default values on ‘radio’ and ‘radio_inline’ field types, props @billerickson

0.6.1

  • Enabled the ability to define your own custom field types (issue #28). props @randyhoyt

0.6

  • Added the ability to limit metaboxes to certain posts by id. props @billerickson

0.5

  • Fixed define to prevent notices. props @destos
  • Added text_date_timestap option. props @andrewyno
  • Fixed WYSIWYG paragraph breaking/spacing bug. props @wpsmith
  • Added taxonomy_radio and taxonomies_select options. props @c3mdigital
  • Fixed script causing the dashboard widgets to not be collapsible.
  • Fixed various spacing and whitespace inconsistencies

0.4

  • Think we have a release that is mostly working. We’ll say the initial release 🙂

Enhancements

  • select, radio, radio_inline field types now all accept the 'show_option_none' field parameter. This parameter allows you to set the text to display for showing a ‘no selection’ option. Default will be false, which means a ‘none’ option will not be added. Set to true to use the default text, ‘None’, or specify another value, i.e. ‘No selection’.