readme.md

CMB2

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.3.1
Stable tag: 2.1.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

Description

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.

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!

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)

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 CMB2 directory inside of your theme or plugin.
2. 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's functions.php file.
3. 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).
4. Profit.

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