CMB 2.0 (beta)

Maintainers:

Contributors:

Version: 2.0.0-beta
WordPress minimum version: 3.8
WordPress version tested to: 4.0
License: GPLv2

Description

CMB2 will create metaboxes and forms with custom fields that will blow your mind.

Plugin now available on wordpress.org

CMB2 is in beta and is a complete rewrite of Custom Metaboxes and Fields for WordPress. Much of the documentation available in the wiki is inaccurate. Please follow the examples in example-functions.php and if you need assistance with beta-testing, please ping me.

Notable Changes in CMB2 (from original CMB)

Change 1: Hooks/filters work nearly the same (if not the same), but you'll be required to use the cmb2_ instead of the original cmb_. This includes the main filter for adding metaboxes, 'cmb2_meta_boxes'. The cmb2_render{$custom_field_type} action no longer passes the unescaped value as the first parameter.

Change 2: The old method for including the CMB core files is no longer applicable and you're simply required to include it directly.

Change 3: The 'pages' metabox parameter has been changed to 'object_types' to more accurately reflect its purpose.

Features:

Create metaboxes to be used on post edit screens.
Create forms to be used on 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 and are listed below.
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.

Field Types:

title An arbitrary title field *
text
text_small
text_medium
text_email
text_url
text_money
textarea
textarea_small
textarea_code
text_date Date Picker
text_time Time picker
select_timezone Time zone dropdown
text_date_timestamp Date Picker (UNIX timestamp)
text_datetime_timestamp Test Date/Time Picker Combo (UNIX timestamp)
text_datetime_timestamp_timezone Test Date/Time Picker/Time zone Combo (serialized DateTime object)
colorpicker Color picker
radio *
radio_inline *
taxonomy_radio *
taxonomy_radio_inline *
select
taxonomy_select *
checkbox *
multicheck
taxonomy_multicheck *
taxonomy_multicheck_inline
wysiwyg (TinyMCE) *
file Image/File upload *†
file_list Image/File list upload
oembed Converts oembed urls (instagram, twitter, youtube, etc. oEmbed in the Codex)
group Hybrid field that supports adding other fields as a repeatable group. *
Create your own custom field type

* Not available as a repeatable field
† Use file_list for repeatable

3rd Party Resources

CMB Attached Posts Field from coreymcollins: Custom field type for attaching posts to a page.
CMB2 Post Search field: Custom field type, post_search_text which adds a post-search dialog for searching/attaching other post IDs.
CMB 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.
CMB 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
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.
CMB Field Type: Gallery from mustardBees: Adds a WordPress gallery field.
WordPress Shortcode Button: Uses CMB2 fields to generate fields for shortcode input modals.

Contribution

All contributions welcome. If you would like to submit a pull request, please check out the trunk branch and pull request against it.

Installation

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 CMB directory inside of your theme or plugin.
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.
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).
Profit.

Changelog

2.0.0

Detailed list to come

1.3.0

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

Fixed typo in closing </th> tag. Props @CivicImages. (#616)

1.2.0

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

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

Bug Fixes

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

1.1.1

Bug Fixes

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

1.1.0

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 diplayed. props @mustardBees, (#486)

1.0.2

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 memeory issues.

1.0.1

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

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

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

Known Issues

Problem inserting file url inside field for image with caption (issue #50) May be fixed, needs testing.
CMB_META_BOX_URL does not define properly in WAMP/XAMP (Windows) (issue #31) May be fixed, needs testing.
Metabox containing WYSIWYG editor cannot be moved (this is a TinyMCE issue)

To-do

Enhancements

Fix known issues (above)
move timepicker and datepicker jQuery inline
support for multiple configurable timepickers/datepickers
add ability to save fields in a single custom field
add ability to mark fields as required
repeatable fields (halfway there)
look at possiblity of tabs
look at preserving taxonomy hierarchies
Add input attributes filter
Always load newest version of CMB
Helper function to easily get oembed from stored oEmbed field

thanhluu/CMB2

CMB 2.0 (beta)

Description

Notable Changes in CMB2 (from original CMB)

Features:

Field Types:

3rd Party Resources

Contribution

Links

Installation

Changelog

2.0.0

1.3.0

1.2.0

1.1.3

1.1.2

1.1.1

1.1.0

1.0.2

1.0.1

1.0.0

0.9.4

0.9.3

0.9.2

0.9.1

0.9

0.8

0.7

0.6.1

0.6

0.5

0.4

Known Issues

To-do