Maintainers:
Contributors:
- Jared Atchison // http://www.jaredatchison.com
- Bill Erickson // http://www.billerickson.net
- Andrew Norcross // http://reaktivstudios.com
- Gary Jones // http://gamajo.com
- Simon Fransson // http://dessibelle.se
- Leon Francis Shelhamer // http://211j.com
- senicar
- Scrent
- Patrick Forringer // http://patrick.forringer.com
- Brad Parbs // http://bradparbs.com
- Greg Rickaby // http://gregrickaby.com
- ArchCarrier
- Devin Walker // http://wordimpress.com
- Randy Hoyt // http://randyhoyt.com
- Doug Stewart // http://literalbarrage.org/blog
- Igor Jerosimić // http://igor.jerosimic.net
- Joe Hoyle // http://www.joehoyle.co.uk
- Tom Rhodes // http://www.madeinebor.com
- David O'Trakoun // http://davidosomething.com
- Phil Wylie // http://www.philwylie.co.uk
- Lisa Sabin-Wilson // http://webdevstudios.com
- Darlan ten Caten // http://i9solucoesdigitais.com.br
- Jan Willem
- Luiz Henrique Almeida da Silva // http://henriquealmeida.net
- TweetPJulien MauryressFr // http://tweetpressfr.github.io
- Gustave F. Gerhardt // http://ghosttoa.st
- greenbrook
- stellageo
- Patrick Garman // http://pmgarman.me
- Travis Smith // http://wpsmith.net
- Scott // http://scottkobewka.com
- Emanuele Feliziani // http://gravida.pro
- Cor van Noorloos // http://corvannoorloos.com
Version: 2.0.0-beta
WordPress minimum version: 3.8
WordPress version tested to: 4.0
License: GPLv2
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.
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.
- 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.
title
An arbitrary title field *text
text_small
text_medium
text_email
text_url
text_money
textarea
textarea_small
textarea_code
text_date
Date Pickertext_time
Time pickerselect_timezone
Time zone dropdowntext_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 pickerradio
*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 uploadoembed
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
More on field types (GitHub wiki)
-
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:
- 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
-
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.
All contributions welcome. If you would like to submit a pull request, please check out the trunk branch and pull request against it.
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'sfunctions.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.
- Detailed list to come
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
, andsave_button
. - Add support for
show_option_none
argument fortaxonomy_select
andtaxonomy_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)
Enhancements
- Add support for custom date/time formats. Props @Scrent. (#506)
- Simplify
wysiwyg
escaping and allow it to be overridden via theescape_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)
Bug Fixes
- Update
cmb_get_field_value
function as it was passing the parameters tocmb_get_field
in the wrong order. - Fix repeating fields not working correctly if meta key or prefix contained an integer. (#503)
Bug Fixes
- Fix issue with
cmb_Meta_Box_types.php
calling a missing method,image_id_from_url
. (#502)
Bug Fixes
- Radio button values were not showing saved value. (#500)
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 ofcmb_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
andcmb_get_field_value
for getting access to CMB's field object and/or value. - New JavaScript events,
cmb_add_row
andcmb_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)
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 (vsarray( 'name' => 'value', 'value' => 'key', )
). This effects the 'select', 'radio', 'radio_inline' field types. The 'multicheck' field type was already using thekey => 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 forfile_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__
, asdirname( __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 incmb_show_on
filter. @lauravaq, (#445) - Fix sanitization recursion memeory issues.
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
andcmb_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.
- 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 standalonetext_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 thecmb_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 @coreymcollinstext
,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
- 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
- Added field type and field id classes to each cmb table row, props @jtsternberg
- Added post type comparison to prevent storing null values for taxonomy selectors, props @norcross
- Added
oEmbed
field type with ajax display, props @jtsternberg
- 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
- 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
- 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
- Enabled the ability to define your own custom field types (issue #28). props @randyhoyt
- Added the ability to limit metaboxes to certain posts by id. props @billerickson
- 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
- Think we have a release that is mostly working. We'll say the initial release :)
- 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)
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