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:

Types:

1. title An arbitrary title field *
2. text
3. text_small
4. text_medium
5. text_email
6. text_url
7. text_money
8. textarea
9. textarea_small
10. textarea_code
11. text_time Time picker
12. select_timezone Time zone dropdown
13. text_date Date Picker
14. text_date_timestamp Date Picker (UNIX timestamp)
15. text_datetime_timestamp Text Date/Time Picker Combo (UNIX timestamp)
16. text_datetime_timestamp_timezone Text Date/Time Picker/Time zone Combo (serialized DateTime object)
17. hidden Hidden input type
18. colorpicker Color picker
19. radio *
20. radio_inline *
21. taxonomy_radio * Default Category/Tag/Taxonomy metaboxes replacement.
22. taxonomy_radio_inline * Default Category/Tag/Taxonomy metaboxes replacement.
23. taxonomy_radio_hierarchical * Default Category/Tag/Taxonomy metaboxes replacement, displayed in a hierarchical fashion (indented).
24. select
25. taxonomy_select * Default Category/Tag/Taxonomy metaboxes replacement.
26. checkbox *
27. multicheck and multicheck_inline
28. taxonomy_multicheck * Default Category/Tag/Taxonomy metaboxes replacement.
29. taxonomy_multicheck_inline Default Category/Tag/Taxonomy metaboxes replacement.
30. taxonomy_multicheck_hierarchical Default Category/Tag/Taxonomy metaboxes replacement, displayed in a hierarchical fashion (indented).
31. wysiwyg (TinyMCE) *
32. file Image/File upload *†
33. file_list Image Gallery/File list management
34. oembed Converts oembed urls (instagram, twitter, youtube, etc. oEmbed in the Codex)
35. group Hybrid field that supports adding other fields as a repeatable group. *

More Info

• Create your own field type
• Common field parameters shared by all fields

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

title

---

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'
) );

CSS Field Class:

cmb-type-title

text

---

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',
) );

CSS Field Class:

cmb-type-text

text_small

---

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'
) );

CSS Field Class:

cmb-type-text-small

text_medium

---

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'
) );

CSS Field Class:

cmb-type-text-medium

text_email

---

Standard text field which enforces an email address. Example:

$cmb->add_field( array(
	'name' => 'Test Text Email',
	'id'   => 'wiki_test_email',
	'type' => 'text_email',
) );

CSS Field Class:

cmb-type-text-email

text_url

---

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

CSS Field Class:

cmb-type-text-url

text_money

---

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 '$'
) );

CSS Field Class:

cmb-type-text-money

textarea

---

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'
) );

CSS Field Class:

cmb-type-textarea

textarea_small

---

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'
) );

CSS Field Class:

cmb-type-textarea-small

textarea_code

---

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'
) );

Notes

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

CSS Field Class:

cmb-type-textarea-code

text_time

---

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',
) );

CSS Field Class:

cmb-type-text-time

Custom Field Attributes:

• time_format, defaults to 'h:i A'. See php.net/manual/en/function.date.php.

Notes

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.

select_timezone

---

Timezone field. Example:

$cmb->add_field( array(
	'name' => 'Time zone',
	'id'   => 'wiki_test_timezone',
	'type' => 'select_timezone',
) );

CSS Field Class:

cmb-type-select-timezone

text_date

---

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',
) );

CSS Field Class:

cmb-type-text-date

Additional Field Options:

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.

jQuery UI Option Example Usage:

$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 ),
		) ),
	),
) );

text_date_timestamp

---

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',
) );

CSS Field Class:

cmb-type-text-date-timestamp

Custom Field Attributes:

• timezone_meta_key, Optionally make this field honor the timezone selected in the select_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.

text_datetime_timestamp

---

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',
) );

CSS Field Class:

cmb-type-text-datetime-timestamp

text_datetime_timestamp_timezone

---

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',
) );

CSS Field Class:

cmb-type-datetime-timestamp-timezone

hidden

---

Adds a hidden input type to the bottom of the CMB2 output. Example:

$cmb->add_field( array(
	'id'   => 'wiki_test_hidden',
	'type' => 'hidden',
) );

CSS Field Class:

not applicable to this field type.

colorpicker

---

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.
	// ),
) );

Additional Field Options:

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

Iris Option Example Usage:

$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', ),
        ) ),
    ),
) );

CSS Field Class:

cmb-type-colorpicker

checkbox

---

Standard checkbox. Example:

$cmb->add_field( array(
	'name' => 'Test Checkbox',
	'desc' => 'field description (optional)',
	'id'   => 'wiki_test_checkbox',
	'type' => 'checkbox',
) );

To use in your template (in the loop):

<?php if ( get_post_meta( get_the_ID(), 'wiki_test_checkbox', 1 ) ) : ?>
	<div>Some HTML</div>
<?php endif; ?>

CSS Field Class:

cmb-type-checkbox

multicheck and multicheck_inline

---

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',
	),
) );

CSS Field Class:

cmb-type-multicheck

Custom Field Attributes:

• 'select_all_button' => false, Setting to false disables the 'Select All' button

radio

---

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.

CSS Field Class:

cmb-type-radio

radio_inline

---

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',
) );

CSS Field Class:

cmb-type-radio-inline

select

---

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.

CSS Field Class:

cmb-type-select

Optional:

• 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' ),
		);
	}
}

Notes

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
}

taxonomy_radio

---

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,
	),
) );

CSS Field Class:

cmb-type-taxonomy-radio

taxonomy_radio_inline

---

Inline radio buttons pre-populated with taxonomy terms. Example:

CSS Field Class:

cmb-type-taxonomy-radio-inline

taxonomy_radio_hierarchical

---

Radio buttons pre-populated with taxonomy terms, displayed in a hierarchical fashion (indented). Example:

CSS Field Class:

cmb-type-taxonomy-radio-hierarchical

taxonomy_select

---

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,
	),
) );

CSS Field Class:

cmb-type-taxonomy-select

taxonomy_multicheck

---

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,
	),
) );

CSS Field Class:

cmb-type-taxonomy-multicheck

Custom Field Attributes:

• 'select_all_button' => false, Setting to false disables the 'Select All' button

taxonomy_multicheck_inline

---

Inline checkboxes with taxonomy terms. Example:

CSS Field Class:

cmb-type-taxonomy-multicheck-inline

Custom Field Attributes:

• 'select_all_button' => false, Setting to false disables the 'Select All' button

Notes

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.

taxonomy_multicheck_hierarchical

---

A field with checkboxes with taxonomy terms, and multiple terms can be selected. Displayed in a hierarchical fashion (indented). Example:

CSS Field Class:

cmb-type-taxonomy-multicheck-hierarchical

wysiwyg

---

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(),
) );

CSS Field Class:

cmb-type-wysiwyg

Notes

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.

file

---

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.
) );

CSS Field Class:

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' );

file_list

---

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"
	),
) );

CSS Field Class:

cmb-type-file-list

Custom Field Attributes:

• preview_size Changes the size of the preview images in the field. Default: array( 50, 50 ).

Sample function for getting and outputting file_list images

/**
 * 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>';
}

To use in your template (in the loop):

<?php cmb2_output_file_list( 'wiki_test_file_list', 'small' ); ?>

oembed

---

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',
) );

CSS Field Class:

cmb-type-oembed

Notes

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

group

---

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',
) );

CSS Field Class:

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'] );
}`

Custom Field Attributes:

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.

Custom Field Types

You can define your own field types as well.

Common Field Parameters

Common field parameters are now documented on this page. The below anchors are in place to keep incoming links from breaking.

• name
• desc
• id
• type
• repeatable
• default
• show_names
• options
• before, after, before_row, after_row, before_field, after_field
• classes
• on_front
• attributes
• show_on_cb
• options_cb
• escape_cb
• sanitization_cb
• render_row_cb