-
Notifications
You must be signed in to change notification settings - Fork 572
Field Types
Here's the built-in fields you can include in your metabox. You can also add your own field types.
Note that all the id fields should have proper prefixes. It's a good practice to create a unique prefix for your fields so you don't risk using the same id as another theme/plugin.
To see examples for how to define your prefixes, as well as examples of the field-types in use, please review the example-functions.php file. There is always a chance that the documentation is not 100% up-to-date, so reviewing this file is recommended.
Here is a cool video overview of what you will get with the example-functions.php
file:
-
title
An arbitrary title field * text
text_small
text_medium
text_email
text_url
text_money
textarea
textarea_small
textarea_code
-
text_time
Time picker -
select_timezone
Time zone dropdown -
text_date
Date Picker -
text_date_timestamp
Date Picker (UNIX timestamp) -
text_datetime_timestamp
Text Date/Time Picker Combo (UNIX timestamp) -
text_datetime_timestamp_timezone
Text Date/Time Picker/Time zone Combo (serialized DateTime object) -
hidden
Hidden input type -
colorpicker
Color picker -
radio
* -
radio_inline
* -
taxonomy_radio
* Default Category/Tag/Taxonomy metaboxes replacement. -
taxonomy_radio_inline
* Default Category/Tag/Taxonomy metaboxes replacement. -
taxonomy_radio_hierarchical
* Default Category/Tag/Taxonomy metaboxes replacement, displayed in a hierarchical fashion (indented). select
-
taxonomy_select
* Default Category/Tag/Taxonomy metaboxes replacement. -
checkbox
* multicheck
andmulticheck_inline
-
taxonomy_multicheck
* Default Category/Tag/Taxonomy metaboxes replacement. -
taxonomy_multicheck_inline
Default Category/Tag/Taxonomy metaboxes replacement. -
taxonomy_multicheck_hierarchical
Default Category/Tag/Taxonomy metaboxes replacement, displayed in a hierarchical fashion (indented). -
wysiwyg
(TinyMCE) * -
file
Image/File upload *† -
file_list
Image Gallery/File list management -
oembed
Converts oembed urls (instagram, twitter, youtube, etc. oEmbed in the Codex) -
group
Hybrid field that supports adding other fields as a repeatable group. *
* Not available as a repeatable field
† Use file_list
for repeatable
A large title (useful for breaking up sections of fields in metabox). Example:
$cmb->add_field( array(
'name' => 'Test Title',
'desc' => 'This is a title description',
'type' => 'title',
'id' => 'wiki_test_title'
) );
cmb-type-title
Standard text field (large). Example:
$cmb->add_field( array(
'name' => 'Test Text',
'desc' => 'field description (optional)',
'default' => 'standard value (optional)',
'id' => 'wiki_test_text',
'type' => 'text',
) );
cmb-type-text
Small text field. Example:
$cmb->add_field( array(
'name' => 'Test Text Small',
'desc' => 'field description (optional)',
'default' => 'standard value (optional)',
'id' => 'wiki_test_textsmall',
'type' => 'text_small'
) );
cmb-type-text-small
Medium text field. Example:
$cmb->add_field( array(
'name' => 'Test Text Medium',
'desc' => 'field description (optional)',
'default' => 'standard value (optional)',
'id' => 'wiki_test_textmedium',
'type' => 'text_medium'
) );
cmb-type-text-medium
Standard text field which enforces an email address. Example:
$cmb->add_field( array(
'name' => 'Test Text Email',
'id' => 'wiki_test_email',
'type' => 'text_email',
) );
cmb-type-text-email
Standard text field which enforces a url. Example:
$cmb->add_field( array(
'name' => __( 'Website URL', 'cmb2' ),
'id' => 'wiki_test_facebookurl',
'type' => 'text_url',
// 'protocols' => array( 'http', 'https', 'ftp', 'ftps', 'mailto', 'news', 'irc', 'gopher', 'nntp', 'feed', 'telnet' ), // Array of allowed protocols
) );
cmb-type-text-url
Standard text field with dollar sign in front of it (useful to prevent users from adding a dollar sign to input). Example:
$cmb->add_field( array(
'name' => 'Test Money',
'desc' => 'field description (optional)',
'id' => 'wiki_test_textmoney',
'type' => 'text_money',
// 'before_field' => '£', // Replaces default '$'
) );
cmb-type-text-money
Standard textarea. Example:
$cmb->add_field( array(
'name' => 'Test Text Area',
'desc' => 'field description (optional)',
'default' => 'standard value (optional)',
'id' => 'wiki_test_textarea',
'type' => 'textarea'
) );
cmb-type-textarea
Smaller textarea. Example:
$cmb->add_field( array(
'name' => 'Test Text Area Small',
'desc' => 'field description (optional)',
'default' => 'standard value (optional)',
'id' => 'wiki_test_textareasmall',
'type' => 'textarea_small'
) );
cmb-type-textarea-small
Code textarea. Example:
$cmb->add_field( array(
'name' => 'Test Text Area Code',
'desc' => 'field description (optional)',
'default' => 'standard value (optional)',
'id' => 'wiki_test_textareacode',
'type' => 'textarea_code'
) );
As of version 2.4.0, the 'textarea_code'
field type now uses CodeMirror that is used by WordPress (#1096). A field can opt-out to return to the previous behavior by specifying an 'options'
parameter: 'options' => array( 'disable_codemirror' => true )
As with the other javascript-enabled fields, the code-editor defaults can be overridden via a data-codeeditor
attribute. E.g:
// Make code be read-only css
$cmb->add_field( array(
// other field config ...
'type' => 'textarea_code'
'attributes' => array(
'readonly' => 'readonly',
'data-codeeditor' => json_encode( array(
'codemirror' => array(
'mode' => 'css',
'readOnly' => 'nocursor',
),
) ),
),
) );
The arguments are then passed to the WordPress wp.codeEditor
method. The top-level parameters to use are: 'codemirror'
, 'csslint'
, 'jshint'
, 'htmlhint'
.
cmb-type-textarea-code
Time picker field. Example:
$cmb->add_field( array(
'name' => 'Test Time Picker',
'id' => 'wiki_test_texttime',
'type' => 'text_time'
// Override default time-picker attributes:
// 'attributes' => array(
// 'data-timepicker' => json_encode( array(
// 'timeOnlyTitle' => __( 'Choose your Time', 'cmb2' ),
// 'timeFormat' => 'HH:mm',
// 'stepMinute' => 1, // 1 minute increments instead of the default 5
// ) ),
// ),
// 'time_format' => 'h:i:s A',
) );
cmb-type-text-time
-
time_format
, defaults to 'h:i A'. See php.net/manual/en/function.date.php.
Like the other picker fields, the default attributes sent to the javascript picker widget can be overridden using a data attribute on the field. The above example has the attributes commented out, but you can see an example for how that works.
Timezone field. Example:
$cmb->add_field( array(
'name' => 'Time zone',
'id' => 'wiki_test_timezone',
'type' => 'select_timezone',
) );
cmb-type-select-timezone
Date field. Stored and displayed according to the date_format
. Example:
$cmb->add_field( array(
'name' => 'Test Date Picker',
'id' => 'wiki_test_textdate_timestamp',
'type' => 'text_date',
// 'timezone_meta_key' => 'wiki_test_timezone',
// 'date_format' => 'l jS \of F Y',
) );
cmb-type-text-date
The CMB2 date-pickers use the jQuery UI Datepicker.
All of the default options in the jQuery UI Datepicker API Documentation are configurable within the CMB2 datepicker fields.
$cmb_demo->add_field( array(
'name' => __( 'Test Date Picker', 'cmb2' ),
'desc' => __( 'field description (optional)', 'cmb2' ),
'id' => '_yourprefix_demo_textdate',
'type' => 'text_date',
'attributes' => array(
// CMB2 checks for datepicker override data here:
'data-datepicker' => json_encode( array(
// dayNames: http://api.jqueryui.com/datepicker/#option-dayNames
'dayNames' => array( 'Dimanche', 'Lundi', 'Mardi', 'Mercredi', 'Jeudi', 'Vendredi', 'Samedi' ),
// monthNamesShort: http://api.jqueryui.com/datepicker/#option-monthNamesShort
'monthNamesShort' => explode( ',', 'En,Feb,Mar,Abr,May,Jun,Jul,Ago,Sep,Oct,Nov,Dic' ),
// yearRange: http://api.jqueryui.com/datepicker/#option-yearRange
// and http://stackoverflow.com/a/13865256/1883421
'yearRange' => '-100:+0',
// Get 1990 through 10 years from now.
// 'yearRange' => '1990:'. ( date( 'Y' ) + 10 ),
) ),
),
) );
Date field, stored as UNIX timestamp. Useful if you plan to query based on it (ex: events listing ). Example:
$cmb->add_field( array(
'name' => 'Test Date Picker (UNIX timestamp)',
'id' => 'wiki_test_textdate_timestamp',
'type' => 'text_date_timestamp',
// 'timezone_meta_key' => 'wiki_test_timezone',
// 'date_format' => 'l jS \of F Y',
) );
cmb-type-text-date-timestamp
-
timezone_meta_key
, Optionally make this field honor the timezone selected in theselect_timezone
field specified above. -
date_format
, defaults to 'm/d/Y'. See php.net/manual/en/function.date.php. PHP's strtotime is used internally to parse the date, this is not compatible with UK/European date formats.
Date and time field, stored as UNIX timestamp. Example:
$cmb->add_field( array(
'name' => 'Test Date/Time Picker Combo (UNIX timestamp)',
'id' => 'wiki_test_datetime_timestamp',
'type' => 'text_datetime_timestamp',
) );
cmb-type-text-datetime-timestamp
Date, time and timezone field, stored as serialized DateTime object. Example:
$cmb->add_field( array(
'name' => 'Test Date/Time Picker/Time zone Combo (serialized DateTime object)',
'id' => 'wiki_test_datetime_timestamp_timezone',
'type' => 'text_datetime_timestamp_timezone',
) );
cmb-type-datetime-timestamp-timezone
Adds a hidden
input type to the bottom of the CMB2 output. Example:
$cmb->add_field( array(
'id' => 'wiki_test_hidden',
'type' => 'hidden',
) );
not applicable to this field type.
A colorpicker field. Example:
$cmb->add_field( array(
'name' => 'Test Color Picker',
'id' => 'wiki_test_colorpicker',
'type' => 'colorpicker',
'default' => '#ffffff',
// 'options' => array(
// 'alpha' => true, // Make this a rgba color picker.
// ),
) );
Enable transparency (rgba) control by adding 'options' => array( 'alpha' => true )
to your field config array.
The CMB2 colorpicker uses the built in WordPress colorpicker, Iris [automattic.github.io/Iris/] (http://automattic.github.io/Iris/)
All of the default options in Iris are configurable within the CMB2 colorpicker field.
[Default Iris Options] (http://automattic.github.io/Iris/#options):
options = {
color: false,
mode: 'hsl',
controls: {
horiz: 's', // horizontal defaults to saturation
vert: 'l', // vertical defaults to lightness
strip: 'h' // right strip defaults to hue
},
hide: true, // hide the color picker by default
border: true, // draw a border around the collection of UI elements
target: false, // a DOM element / jQuery selector that the element will be appended within. Only used when called on an input.
width: 200, // the width of the collection of UI elements
palettes: false // show a palette of basic colors beneath the square.
}
$cmb->add_field( array(
'name' => 'Test Color Picker',
'id' => 'wiki_test_colorpicker',
'type' => 'colorpicker',
'default' => '#ffffff',
'attributes' => array(
'data-colorpicker' => json_encode( array(
// Iris Options set here as values in the 'data-colorpicker' array
'palettes' => array( '#3dd0cc', '#ff834c', '#4fa2c0', '#0bc991', ),
) ),
),
) );
cmb-type-colorpicker
Standard checkbox. Example:
$cmb->add_field( array(
'name' => 'Test Checkbox',
'desc' => 'field description (optional)',
'id' => 'wiki_test_checkbox',
'type' => 'checkbox',
) );
<?php if ( get_post_meta( get_the_ID(), 'wiki_test_checkbox', 1 ) ) : ?>
<div>Some HTML</div>
<?php endif; ?>
cmb-type-checkbox
A field with multiple checkboxes (and multiple can be selected). Example:
$cmb->add_field( array(
'name' => 'Test Multi Checkbox',
'desc' => 'field description (optional)',
'id' => 'wiki_test_multicheckbox',
'type' => 'multicheck',
'options' => array(
'check1' => 'Check One',
'check2' => 'Check Two',
'check3' => 'Check Three',
),
) );
cmb-type-multicheck
-
'select_all_button' => false
, Setting to false disables the 'Select All' button
Standard radio buttons. Example:
$cmb->add_field( array(
'name' => 'Test Radio',
'id' => 'wiki_test_radio',
'type' => 'radio',
'show_option_none' => true,
'options' => array(
'standard' => __( 'Option One', 'cmb2' ),
'custom' => __( 'Option Two', 'cmb2' ),
'none' => __( 'Option Three', 'cmb2' ),
),
) );
Set the optional parameter, show_option_none
, to true
to use the default text, 'None', or specify another value, i.e. 'No selection'. By default show_option_none
is false.
cmb-type-radio
Inline radio buttons. Example:
$cmb->add_field( array(
'name' => 'Test Radio inline',
'id' => 'wiki_test_radio_inline',
'type' => 'radio_inline',
'options' => array(
'standard' => __( 'Option One', 'cmb2' ),
'custom' => __( 'Option Two', 'cmb2' ),
'none' => __( 'Option Three', 'cmb2' ),
),
'default' => 'standard',
) );
cmb-type-radio-inline
Standard select dropdown. Example:
$cmb->add_field( array(
'name' => 'Test Select',
'desc' => 'Select an option',
'id' => 'wiki_test_select',
'type' => 'select',
'show_option_none' => true,
'default' => 'custom',
'options' => array(
'standard' => __( 'Option One', 'cmb2' ),
'custom' => __( 'Option Two', 'cmb2' ),
'none' => __( 'Option Three', 'cmb2' ),
),
) );
Set the optional paremeter, show_option_none
, to true
to use the default text, 'None', or specify another value, i.e. 'No selection'. By default show_option_none
is false.
cmb-type-select
- All the types that take an
'options'
parameter can be replaced with an'options_cb'
parameter that allows you to specify a callback. This callback will receive the field object which you can use to check the object ID ($field->object_id
). This can be handy if you need to build options based on the current post or context. The callback should return an array of options in the format displayed in these examples.
Example:
// in the field array..
'options_cb' => 'show_cat_or_dog_options',
// Callback function
function show_cat_or_dog_options( $field ) {
if ( has_tag( 'cats', $field->object_id ) ) {
return array(
'tabby' => __( 'Tabby', 'cmb2' ),
'siamese' => __( 'Siamese', 'cmb2' ),
'calico' => __( 'Calico', 'cmb2' ),
);
} else {
return array(
'german-shepherd' => __( 'German Shepherd', 'cmb2' ),
'bulldog' => __( 'Bulldog', 'cmb2' ),
'poodle' => __( 'Poodle', 'cmb2' ),
);
}
}
If you need the label value wherever you are using the select field's value (vs just the value), you can define your options in a function, and get the label by comparing the value against the array given by the function. Example here.
You can write conditional blocks in your code depending on the value of the selected option with something like this:
$select_value = get_post_meta( get_the_ID(), 'wiki_test_select', true ) );
// If (Option 2 True)
if ( 'custom' === $select_value ) {
// some PHP code
} else {
// some other PHP code
}
Radio buttons pre-populated with taxonomy terms. Example:
$cmb->add_field( array(
'name' => 'Test Taxonomy Radio',
'desc' => 'Description Goes Here',
'id' => 'wiki_test_taxonomy_radio',
'taxonomy' => '', // Enter Taxonomy Slug
'type' => 'taxonomy_radio',
// Optional :
'text' => array(
'no_terms_text' => 'Sorry, no terms could be found.' // Change default text. Default: "No terms"
),
'remove_default' => 'true', // Removes the default metabox provided by WP core.
// Optionally override the args sent to the WordPress get_terms function.
'query_args' => array(
// 'orderby' => 'slug',
// 'hide_empty' => true,
),
) );
cmb-type-taxonomy-radio
Inline radio buttons pre-populated with taxonomy terms. Example:
cmb-type-taxonomy-radio-inline
Radio buttons pre-populated with taxonomy terms, displayed in a hierarchical fashion (indented). Example:
cmb-type-taxonomy-radio-hierarchical
A select field pre-populated with taxonomy terms. Example:
$cmb->add_field( array(
'name' => 'Test Taxonomy Select',
'desc' => 'Description Goes Here',
'id' => 'wiki_test_taxonomy_select',
'taxonomy' => 'category', //Enter Taxonomy Slug
'type' => 'taxonomy_select',
'remove_default' => 'true', // Removes the default metabox provided by WP core.
// Optionally override the args sent to the WordPress get_terms function.
'query_args' => array(
// 'orderby' => 'slug',
// 'hide_empty' => true,
),
) );
cmb-type-taxonomy-select
A field with checkboxes with taxonomy terms, and multiple terms can be selected. Example:
$cmb->add_field( array(
'name' => 'Test Taxonomy Multicheck',
'desc' => 'Description Goes Here',
'id' => 'wiki_test_taxonomy_multicheck',
'taxonomy' => '', //Enter Taxonomy Slug
'type' => 'taxonomy_multicheck',
// Optional :
'text' => array(
'no_terms_text' => 'Sorry, no terms could be found.' // Change default text. Default: "No terms"
),
'remove_default' => 'true', // Removes the default metabox provided by WP core.
// Optionally override the args sent to the WordPress get_terms function.
'query_args' => array(
// 'orderby' => 'slug',
// 'hide_empty' => true,
),
) );
cmb-type-taxonomy-multicheck
-
'select_all_button' => false
, Setting to false disables the 'Select All' button
Inline checkboxes with taxonomy terms. Example:
cmb-type-taxonomy-multicheck-inline
-
'select_all_button' => false
, Setting to false disables the 'Select All' button
To retrieve the values from the taxonomy fields, use get_the_terms
, not get_post_meta
, etc. The taxonomy fields are not intended to provide an arbitrary list of terms to pick from, but are intended to be a replacement for the default taxonomy meta-boxes. I.e. they are meant to set the taxonomy terms on an object, and will not save as a meta value. Any other use of these types will be hacky and/or buggy. Suggest looking at building a custom field type instead - Example.
A field with checkboxes with taxonomy terms, and multiple terms can be selected. Displayed in a hierarchical fashion (indented). Example:
cmb-type-taxonomy-multicheck-hierarchical
A metabox with TinyMCE editor (same as WordPress' visual editor). Example:
$cmb->add_field( array(
'name' => 'Test wysiwyg',
'desc' => 'field description (optional)',
'id' => 'wiki_test_wysiwyg',
'type' => 'wysiwyg',
'options' => array(),
) );
cmb-type-wysiwyg
Text added in a wysiwyg field will not have paragraph tags automatically added, the same is true of standard WordPress post content editing with the WYSIWYG. When outputting formatted text, wrap your get_post_meta() call with wpautop to generate the paragraph tags.
<?php echo wpautop( get_post_meta( get_the_ID(), 'wiki_test_wysiwyg', true ) ); ?>
If you want oembed filters to apply to the wysiwyg content, add this helper function to your theme or plugin:
function yourprefix_get_wysiwyg_output( $meta_key, $post_id = 0 ) {
global $wp_embed;
$post_id = $post_id ? $post_id : get_the_id();
$content = get_post_meta( $post_id, $meta_key, 1 );
$content = $wp_embed->autoembed( $content );
$content = $wp_embed->run_shortcode( $content );
$content = wpautop( $content );
$content = do_shortcode( $content );
return $content;
}
...
echo yourprefix_get_wysiwyg_output( 'wiki_test_wysiwyg', get_the_ID() );
The options array allows you to customize the settings of the wysiwyg. Here's an example with all the options:
array(
'name' => 'Test wysiwyg',
'desc' => 'field description (optional)',
'id' => 'wiki_test_wysiwyg',
'type' => 'wysiwyg',
'options' => array(
'wpautop' => true, // use wpautop?
'media_buttons' => true, // show insert/upload button(s)
'textarea_name' => $editor_id, // set the textarea name to something different, square brackets [] can be used here
'textarea_rows' => get_option('default_post_edit_rows', 10), // rows="..."
'tabindex' => '',
'editor_css' => '', // intended for extra styles for both visual and HTML editors buttons, needs to include the `<style>` tags, can use "scoped".
'editor_class' => '', // add extra class(es) to the editor textarea
'teeny' => false, // output the minimal editor config used in Press This
'dfw' => false, // replace the default fullscreen with DFW (needs specific css)
'tinymce' => true, // load TinyMCE, can be used to pass settings directly to TinyMCE using an array()
'quicktags' => true // load Quicktags, can be used to pass settings directly to Quicktags using an array()
),
),
The 'id'
should not be set to 'content' as the standard editor has this id and it will result in a non working editor.
A file uploader. By default it will store the file url and allow either attachments or URLs. This field type will also store the attachment ID (useful for getting different image sizes). It will store it in $id . '_id'
, so if your field id is wiki_test_image
the ID is stored in wiki_test_image_id
. You can also limit it to only allowing attachments (can't manually type in a URL), which is also useful if you plan to use the attachment ID. The example shows its default values, with possible values commented inline. Example:
$cmb->add_field( array(
'name' => 'Test File',
'desc' => 'Upload an image or enter an URL.',
'id' => 'wiki_test_image',
'type' => 'file',
// Optional:
'options' => array(
'url' => false, // Hide the text input for the url
),
'text' => array(
'add_upload_file_text' => 'Add File' // Change upload button text. Default: "Add or Upload File"
),
// query_args are passed to wp.media's library query.
'query_args' => array(
'type' => 'application/pdf', // Make library only display PDFs.
// Or only allow gif, jpg, or png images
// 'type' => array(
// 'image/gif',
// 'image/jpeg',
// 'image/png',
// ),
),
'preview_size' => 'large', // Image size to use when previewing in the admin.
) );
cmb-type-file
Example using the wiki_test_image_id
meta key to retrieve a medium image:
$image = wp_get_attachment_image( get_post_meta( get_the_ID(), 'wiki_test_image_id', 1 ), 'medium' );
A file uploader that allows you to add as many files as you want. Once added, files can be dragged and dropped to reorder.
This is a repeatable field, and will store its data in an array, with the attachment ID as the array key and the attachment url as the value. Example:
$cmb->add_field( array(
'name' => 'Test File List',
'desc' => '',
'id' => 'wiki_test_file_list',
'type' => 'file_list',
// 'preview_size' => array( 100, 100 ), // Default: array( 50, 50 )
// 'query_args' => array( 'type' => 'image' ), // Only images attachment
// Optional, override default text strings
'text' => array(
'add_upload_files_text' => 'Replacement', // default: "Add or Upload Files"
'remove_image_text' => 'Replacement', // default: "Remove Image"
'file_text' => 'Replacement', // default: "File:"
'file_download_text' => 'Replacement', // default: "Download"
'remove_text' => 'Replacement', // default: "Remove"
),
) );
cmb-type-file-list
-
preview_size
Changes the size of the preview images in the field. Default: array( 50, 50 ).
/**
* Sample template tag function for outputting a cmb2 file_list
*
* @param string $file_list_meta_id The field meta id. ('wiki_test_file_list')
* @param string $img_size Size of image to show
*/
function cmb2_output_file_list( $file_list_meta_id, $img_size = 'medium' ) {
// Get the list of files
$files = get_post_meta( get_the_ID(), $file_list_meta_id, 1 );
echo '<div class="file-list-wrap">';
// Loop through them and output an image
foreach ( (array) $files as $attachment_id => $attachment_url ) {
echo '<div class="file-list-image">';
echo wp_get_attachment_image( $attachment_id, $img_size );
echo '</div>';
}
echo '</div>';
}
<?php cmb2_output_file_list( 'wiki_test_file_list', 'small' ); ?>
Displays embedded media inline using WordPress' built-in oEmbed support. See codex.wordpress.org/Embeds for more info and for a list of embed services supported. (added in 0.9.1). Example:
$cmb->add_field( array(
'name' => 'oEmbed',
'desc' => 'Enter a youtube, twitter, or instagram URL. Supports services listed at <a href="http://codex.wordpress.org/Embeds">http://codex.wordpress.org/Embeds</a>.',
'id' => 'wiki_test_embed',
'type' => 'oembed',
) );
cmb-type-oembed
Text added in a oembed
field will not automatically display the embed in your theme. To generate the embed in your theme, this is a method you could use:
$url = esc_url( get_post_meta( get_the_ID(), 'wiki_test_embed', 1 ) );
echo wp_oembed_get( $url );
Hybrid field that supports adding other fields as a repeatable group. Example:
$group_field_id = $cmb->add_field( array(
'id' => 'wiki_test_repeat_group',
'type' => 'group',
'description' => __( 'Generates reusable form entries', 'cmb2' ),
// 'repeatable' => false, // use false if you want non-repeatable group
'options' => array(
'group_title' => __( 'Entry {#}', 'cmb2' ), // since version 1.1.4, {#} gets replaced by row number
'add_button' => __( 'Add Another Entry', 'cmb2' ),
'remove_button' => __( 'Remove Entry', 'cmb2' ),
'sortable' => true,
// 'closed' => true, // true to have the groups closed by default
// 'remove_confirm' => esc_html__( 'Are you sure you want to remove?', 'cmb2' ), // Performs confirmation before removing group.
),
) );
// Id's for group's fields only need to be unique for the group. Prefix is not needed.
$cmb->add_group_field( $group_field_id, array(
'name' => 'Entry Title',
'id' => 'title',
'type' => 'text',
// 'repeatable' => true, // Repeatable fields are supported w/in repeatable groups (for most types)
) );
$cmb->add_group_field( $group_field_id, array(
'name' => 'Description',
'description' => 'Write a short description for this entry',
'id' => 'description',
'type' => 'textarea_small',
) );
$cmb->add_group_field( $group_field_id, array(
'name' => 'Entry Image',
'id' => 'image',
'type' => 'file',
) );
$cmb->add_group_field( $group_field_id, array(
'name' => 'Image Caption',
'id' => 'image_caption',
'type' => 'text',
) );
cmb-field-list
All repeatable group entries will be saved as an array to that meta-key. Example usage to pull data back:
$entries = get_post_meta( get_the_ID(), 'wiki_test_repeat_group', true );
foreach ( (array) $entries as $key => $entry ) {
$img = $title = $desc = $caption = '';
if ( isset( $entry['title'] ) ) {
$title = esc_html( $entry['title'] );
}
if ( isset( $entry['description'] ) ) {
$desc = wpautop( $entry['description'] );
}
if ( isset( $entry['image_id'] ) ) {
$img = wp_get_attachment_image( $entry['image_id'], 'share-pick', null, array(
'class' => 'thumb',
) );
}
$caption = isset( $entry['image_caption'] ) ? wpautop( $entry['image_caption'] ) : '';
// Do something with the data
}
// Or get just the title from the first group.
$first_entry_title = '';
if ( isset( $entries[0]['title'] ) ) {
$first_entry_title = esc_html( $entries[0]['title'] );
}`
The group
field type supports several a few extra parameters.
The following are documented on the Field Parameters page.
'before_group'
'after_group'
'before_group_row'
'after_group_row'
The field also supports the following:
-
'group_title'
- Defines the title for each group section. Can use the{#}
placeholder to output the group number. -
'add_button'
- Defines the text for the group add button. Defaults to "Add Group". -
'remove_button'
- Defines the text for the group remove button. Defaults to "Remove Group". -
'remove_confirm'
- Defines the text used to confirm if group should be removed. By default, it is empty, so there is no confirmation when removing a group. -
'sortable'
- Whether groups are sortable. Defaults to false. -
'closed'
- Whether groups are displayed closed (collapsed). Defaults to false.
You can define your own field types as well.
Common field parameters are now documented on this page. The below anchors are in place to keep incoming links from breaking.
Documentation:
-
Installation
Installation instructions for various environments -
Basic Usage
Get up and running -
Advanced Usage
Not for the faint of heart -
Field Types
Breakdown of field types -
Examples
Examples for registering fields -
Field Parameters
Breakdown of common field parameters -
Display Options
Limit display of boxes -
Box Properties
Breakdown of box properties -
Troubleshooting
Common issues & how to deal with them -
Notable Changes in CMB2 (from original CMB)
CMB2 — a complete re-write -
Tips & Tricks
10x your CMB2 skills -
REST API
CMB2 data through WordPress REST API -
Javascript API
Work with CMB2 JS events & hooks
Advanced tutorials:
- Adding your own field types
- Adding your own show_on filters
- Displaying boxes on the front-end
- Using CMB to create an Admin Theme Options Page
- Create New Posts (or Custom Post Type) Entries Using A Front End Form
- Disable CMB2 Styles on Front End Forms
External Resources: