ButterBean Lesson #2: Managers

In ButterBean, managers are the glue that hold everything together.

Managers house sections, which house controls. We’ll talk about those more in upcoming tutorials. For now, it’s all about the foundation.

I modeled managers after the WordPress customizer in many respects. Think of each manager as a “mini customizer”. The big difference is that you can have many managers on the edit post screen.

Managers are housed within a post meta box and can be moved around and generally work just like any other meta box.

Basics of adding a manager

When adding a new manager, you use the $butterbean->register_manager() function. This allows you to create a new manager. Along with that, you need 3 pieces of information at minimum:

  • A unique name/ID for your manager.
  • What post type(s) to display the manager on.
  • A text label/title for display.

To register a manager, hook into the butterbean_register hook like so:

add_action( 'butterbean_register', 'butterbean_lesson_2_register', 10, 2 );

function butterbean_lesson_2_register( $butterbean, $post_type ) {

    // Only run this on the `page` post type.
    if ( 'page' !== $post_type )
        return;

    // Register our custom manager.
    $butterbean->register_manager(
        'lesson_2',
        array(
            'label'     => 'ButterBean Lesson #2',
            'post_type' => 'page'
        )
    );

    // Get our custom manager object.
    $manager = $butterbean->get_manager( 'lesson_2' );
}

Basically, this tells ButterBean that you want to register a manager with the lesson_2 name, on the page post type, and with the ButterBean Lesson #2 label.

Additional arguments

The following is a list of all the available arguments and what they do. It gives you quite a bit of control over your manager.

typestring

The type of manager to use. ButterBean comes built with a single manager type, which is named default. This manager presents your sections in a tabbed interface. Plugin developers create register and create additional types of managers with wholly different interfaces. For the vast majority of use cases, you don’t need to set this and can leave it at default.

labelstring

This is the text label used to identify your manager by users. It is placed at the top of the meta box that the manager sits in. This argument has no default and must be set. Also, be sure to internationalize this so that it can be translated.

post_typestring|array

The post type can be a single post type name or an array of post type names. By default, this is set to post.

contextstring

This corresponds to the core WordPress add_meta_box() function’s context argument. Accepted values are normal, advanced, and side. The default is advanced.

prioritystring

Like the previous argument, this also matches up to the add_meta_box() function’s priority argument. Accepted values are high, core, default, and low. The default is set to default.

capabilitystring

This is a user role capability that you can pass to the manager that allows it to only be shown to users with the given capability. For example, if you pass in manage_options, the manager will only appear for users with that capability.

post_type_supportsstring

This argument checks if the post type supports a certain feature, such as title, editor, etc. If the post type does not support the given feature, the manager will not appear.

theme_supportsstring

This argument checks if the currently active theme supports a specific theme feature like title-tag, post-thumbnails, etc. If the theme doesn’t support the feature, the manager will not show.

Manager functions

The ButterBean class (and the $butterbean object derived from that class) has several functions for working with managers. You’ve seen the $butterbean->register_manager() function. Let’s look at some of the others.

$butterbean->get_manager( $name )

This function returns a manager object. For a full look at manager objects, take a look at the ButterBean_Manager class in inc/class-manager.php.

$manager = $butterbean->get_manager( 'lesson_2' );

$butterbean->unregister_manager( $name )

This function unregisters an existing manager. Theoretically, one plugin can remove another plugin’s manager. There’s probably some interesting use cases.

$butterbean->unregister_manager( 'lesson_2' );

$butterbean->manager_exists( $name )

This function checks if a manager exists (i.e., if a manager has been registered). It is a boolean check and will return true or false.

if ( $butterbean->manager_exists( 'lesson_2' ) ) {

        // Do something if the manager exists.
}

A working foundation

Now that you know how to build managers, you have the foundation for everything else we’ll be building on in the next tutorials.

There’s other neat things you can do with managers if you want to try your hand at making custom manager types. That’s outside the scope of this tutorial and something I’d like to show down the road. Just know that you’re not limited to the default tabbed interface. If anyone has any UI ideas, I’d love to give them a try myself.