Taming CMB2

If you’re reading this post, chances are you have used CMB2 to make awesome meta boxes. Or maybe you are considering using CMB2 to create meta boxes. The gist of CMB2 is simple. This library is awesome! It is a developers dream for making meta boxes through the different WordPress types. All of the special field types that you used to have to build from scratch using html and js are now as easy as setting a few keys. (Disclaimer: I am not the author of CMB2. While I have contributed to the project, I cannot take most of the credit)

The Rub: If you have used this library before or have just read through the docs you will see the options are enormous. The boxes have options, the fields have options, the types of fields have different options. Trying to keep track of all the possible field types and options for specific fields is impossible. You can memorized a few over time, but you’ll find yourself running to the docs often to be able to use it.

This was not good enough for me. I decided to do something about it. Meet wordpress-lipe-libs. There are a ton of utilities available here which are not related to this post so I won’t get into all that. This library is a compilation of common utilities and wrappers for doing WP boilerplate tasks in an OOP way. For the context of this post you will be interested in the /src/CMB2 directory.

Within this directory you are going to find classes which map out every possible option for every box, field, and content type. You set options by setting properties and calling methods. Using an IDE with autocomplete like PhpStorm means you don’t have to memorize a single option. You simply start typing what you think it might be and the IDE will find it for you.

Lets see this in action: Say you want to add new meta box to pages with a few custom check-boxes and a select all check-boxes option. (For the sake of brevity in the example I’m leaving out translation calls and name-spacing. I’m also using a functional pattern to make the example more readable.)

Step 1: Hook into the init call to prevent fatal errors when CMB2 is not active.

<?php add_action( 'cmb2_init', 'register_cmb2_groups' );

 

Step 2: Register the box and add field

<?php function register_cmb2_groups(){ $box = new Box( 'box-id', ['page'], 'Box Title' ); $field = new Field( 'field-id', 'Field Label' ); $field->type() ->multicheck( [ '1' => 'one', '2' => 'two', ], true ); $box->add_field( $field ); }

 

Step 3: Umm.. There is no step 3!

Let’s break down the register_cmb2_groups function to see how this works.

<?php $box = new Box( 'box-id', ['page'], 'Box Title' );

 

Here we register the meta box. There are 4 classes available which are boxes:

1. Box – For posts of any type
2. User_Box – For used edit screens
3. Term_Box – For term edit screens
4. Options_Page – For custom options pages

Each box has different properties based on context but registering is identical and truly you only need the 3 arguments which are passed to the constructor to get up and running. You can use autocomplete to find the different properties which may be set to the $box variable.

<?php $field = new Field( 'field-id', 'Field Label' );

 

There is only one class for registering a field on any box no matter the type. You construct a new instance of the class with the 2 required arguments. The class has every possible field option as a property so feel free to set those on the $field variable. There is also a Group class (out of context for this example) for registering a group in the exact same way. If you register a group, be sure to add it to the box before you add fields to the group.

<?php $field->type() ->multicheck( [ '1' => 'one', '2' => 'two', ], true );

 

Here is where a lot of the magic happens. The field class has a type() method which returns an object with every possible field type mapped out into methods with required arguments specific to the field type. I know this sounds like a mouthful.. well it is. You IDE here makes it super simple. Call $field->type()-> and start typing what you think the field might be called. Presto! autocomplete finds the type (which is a method) for you. Each type method will have arguments available specific to its type. Some arguments will be optional, some required, but all  are documented with PHP docs. The PHP docs also include links to the corresponding section of the CMB2 wiki.

<?php $box->add_field( $field );

 

Add the field to your box.  You don’t have to add your fields to the box, but it will be naked without them. If you have a group you can add your field to a group instead (out of context for this example).