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 developer’s 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 memorize 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 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.
This type of setup is known as a fluent interface.
Let’s see this in action: say you want to add a 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.
Step 2: Register the box and add field.
Step 3: Umm.. There is no step 3!
Let’s break down the register_cmb2_groups function to see how this works.
Here we register the meta box. There are 4 classes available which are boxes:
- Box – For posts of any type.
- User_Box – For used edit screens.
- Term_Box – For term edit screens.
- 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.
There is only one method for registering a field on any box no matter the type. You call the method with the 2 required arguments.
Here is where a lot of the magic happens. The field 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. Your IDE here makes it super simple. Call $box->field()-> 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.
Further configuration
Each type method will return a full Field class which allows further configuration. Every available CMB2 field parameter is available as a class property, as well as many helper methods which allow chaining.