WordPress.org

CMB2 is a developer's toolkit for building metaboxes, custom fields, and forms for WordPress that will blow your mind.

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.

Features:

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

Translation

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

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

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

  1. 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
  2. The pw_multiselect field 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.

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

Other Helpful Resources

• Taxonomy_MetaData: WordPress Helper Class for saving pseudo-metadata for taxonomy terms. Includes an extended class for using CMB to generate the actual form fields.
• CMB2 Taxonomy from jcchavezs: Similar to Taxonomy_MetaData, but uses a custom table for taxonomy term meta storage.
• 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 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.

Contribution

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

Links

• Project Homepage
• Github project page
• Documentation (GitHub wiki)

Most Recent Changes

2.1.2

Bug Fixes

• Fixes back-compatibility issue when adding fields array to the metabox registration. (#472)

2.1.1

Enhancements

• Make all CMB2::save_fields arguments optional to fall-back to $_POST data. Props JPry.
• New filter, cmb2_non_repeatable_fields for adding additional fields to the blacklist of repeatable field-types. Props JPry (#430).
• New recommended hoook for adding metaboxes, cmb2_admin_init. Most metabox registration only needs to happen if in wp-admin, so there is no reason to register them when loading the front-end (and increase the memory usage). cmb2_init still exists to register metaboxes that will be used on the front-end or used on both the front and back-end. Instances of cmb2_init in example-functions.php have been switched to cmb2_admin_init.
• Add 'render_row_cb' field parameter for overriding the field render method.
• Add 'label_cb' field parameter for overriding the field label render method.
• Allow CMB2_Types::checkbox() method to be more flexible for extending by taking an args array and an $is_checked second argument.
• More thorough unit tests. Props pglewis, (#447,#448).
• Update CMB2_Utils::image_id_from_url to be more reliable. Props wpscholar, (#453).
• cmb2_get_option now takes a default fallback value as a third parameter.

Bug Fixes

• Address issue where 'file' and 'file_list' field results were getting mixed. Props augustuswm (#382, #250, #296).
• Fix long-standing issues with radio and multicheck fields in repeatable groups losing their values when new rows are added. (#341, #304, #263, #246, #150)
• Fixes issue where currently logged-in user's profile data would display in the "Add New User" screen fields. (#427)
• Fixes issue where radio values/selections would not always properly transfer when shifting rows (up/down). Props jamiechong (#429, #152).
• Fixes issue where repeatable groups display "Array" as the field values if group is left completely empty. (#332,#390).
• Fixes issue with 'file_list' fields not saving properly when in repeatable groups display. Props jamiechong (#433,#187).
• Update 'taxonomy_radio_inline' and 'taxonomy_multicheck_inline' fields sanitization method to use the same method as the non-inline versions. Props superfreund (#454).

View complete changelog

Known Issues

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