The many faces of CMB

Ok, so what IS CMB?

• Custom Metaboxes and Fields (CMB for short) will create metaboxes and forms with custom fields that will blow your mind.

  — Custom Metaboxes and Fields for WordPress

Several useful field types are included

• title
• text
• text_small
• text_medium
• text_email
• text_url
• text_money
• textarea
• textarea_small
• textarea_code

• text_date
• text_time
• select_timezone
• text_date_timestamp
• text_datetime_timestamp
• text_datetime_timestamp_timezone
• colorpicker
• radio
• radio_inline
• taxonomy_radio
• taxonomy_radio_inline

• select
• taxonomy_select
• checkbox
• multicheck
• taxonomy_multicheck
• taxonomy_multicheck_inline
• wysiwyg
• file
• file_list
• oembed
• group

Docs

Custom API hook that allows you to create your own field types

• CMB Attached Posts Field from coreymcollins: Custom field type for attaching posts to a page.
• CMB Field Type: Google Maps from mustardBees: Custom field type for Google Maps.
• CMB Field Type: Select2 from mustardBees: Custom field types which use the Select2 script:
• Docs

Field parameters

        ...

        'fields' => array(
            array(
                'name'            => __( 'Test Text', 'cmb' ),
                'desc'            => __( 'field description (optional)', 'cmb' ),
                'id'              => $prefix . 'test_text',
                'type'            => 'text',
                'sanitization_cb' => 'my_custom_sanitization', // custom sanitization callback parameter
                'escape_cb'       => 'my_custom_escaping',  // custom escaping callback parameter
                'on_front'        => false, // Optionally designate a field to wp-admin only
                'repeatable'      => true,
            ),
            array(
                'name'    => __( 'Test wysiwyg', 'cmb' ),
                'desc'    => __( 'field description (optional)', 'cmb' ),
                'id'      => $prefix . 'test_wysiwyg',
                'type'    => 'wysiwyg',
                'options' => array( 'textarea_rows' => 5, ),
            ),
        ),

        ...
          

So what’s the big idea?

How does one begin this magical journey? (example-functions.php)

add_filter( 'cmb_meta_boxes', 'cmb_sample_metaboxes' );
function cmb_sample_metaboxes( $meta_boxes = array() ) {

    // Start with an underscore to hide fields from custom fields list
    $prefix = '_cmb_';

    /**
     * Sample metabox to demonstrate each field type included
     */
    $meta_boxes['test_metabox'] = array(
        'id'         => 'test_metabox',
        'title'      => __( 'Test Metabox', 'cmb' ),
        'pages'      => array( 'page', ), // Post type
        'context'    => 'normal',
        'priority'   => 'high',
        'show_names' => true, // Show field names on the left
        'fields'     => array(
        ...
        ),
    );

    // Add other metaboxes as needed

    return $meta_boxes;
}

Custom field type

            array(
                'name'    => __( 'Custom Type Example', 'cmb' ),
                'desc'    => __( 'field description (optional)', 'cmb' ),
                'id'      => $prefix . 'test_my_custom_type',
                'type'    => 'my_custom_type',
            ),

add_action( 'cmb_render_my_custom_type', 'cmb_render_my_custom_type', 10, 6 );
function cmb_render_my_custom_type( $args, $escaped_val, $object_id, $object_type, $cmb_types ) {
   $name = $cmb_types->_name();
   $id = $this->_id();

   echo '<input type="text" name="'. $name .'" id="'. $id .'" value="'. $escaped_val .'" />';
   echo $this->_desc( true );
}

Customizing the built-in fields

• name: The field label
• desc: Field description. Usually under or adjacent to the field input.
• id: The data key. If using for posts, will be the post-meta key. If using for an options page, will be the array key.
• type: What makes the whole thing work.
• repeatable: Supported by most, and will make the individual field a repeatable one.
• default: Specify a default value for the field.
• show_names: Hide label for the field.
• options: For fields that take an options array. These include: select, radio, multicheck, wysiwyg and group.
• before and after: These allow you to add arbitrary text/markup before and after the field just inside the td tag.
• on_front: If you’re planning on using your metabox fields on the front-end as well (user-facing), then you can specify that certain fields do not get displayed there by setting this parameter to false.

Customizing the built-in fields (s’more)

• attributes: Will modify default attributes (class, input type, rows, etc), or add your own (placeholder, data attributes). Example:

  array(
      'name'        => 'Extra Small Textarea',
      'id'          => $prefix .'xtra_small_textarea',
      'type'        => 'textarea_small',
      'attributes'  => array(
          'placeholder' => 'A small amount of text',
          'rows'        => 3,
          'class'       => 'custom-class-name',
      ),
  ),
  

• escape_cb: Bypass the CMB escaping (escapes before display) methods with your own callback.
• sanitization_cb: Bypass the CMB sanitization (sanitizes before saving) methods with your own callback.

Docs

More Power

• Hooks
  • cmb_before_table
  • cmb_after_table
  • (aformentioned) cmb_render_$name
• Filters
  • cmb_show_on
  • cmb_meta_box_url: tell cmb where it lives
  • cmb_allow_frontend: Disallow a form/metabox on the front-end
  • cmb_override_meta_value
  • etc!