ButterBean Lesson #1: The Basics

Screenshot of lesson 1 final output

With version 1.0.0 of ButterBean out the door, it’s time to actually find out what you can do with the framework.

This tutorial is going to cover the basics of building something with ButterBean from start to finish. The screenshot above is what the final output should look like.

You’re expected to have some familiarity with WordPress plugin development if you plan to use ButterBean. While I plan to explain as much as I can, I can’t explain every single detail. This post and the following posts in this series are going to be lengthy.

Adding ButterBean to your plugin

First, you need to grab a copy of the project from its GitHub repository and put it in your plugin.

I’ll assume a plugin structure like this:

your-plugin
        /butterbean
                /butterbean.php
                /...

After adding it, you need to load the framework. The standard plugins_loaded hook will be fine. Really, any hook before init will work.

add_action( 'plugins_loaded', 'butterbean_lesson_1_load' );

function butterbean_lesson_1_load() {

        require_once( trailingslashit( plugin_dir_path( __FILE__ ) ) . 'butterbean/butterbean.php' );
}

Registration hook

Perhaps the most important hook in ButterBean is the butterbean_register action hook. It’s the point where all of ButterBean’s functionality is available to you and where you can register your own managers, sections, controls, and settings (we’ll get to those below).

do_action( 'butterbean_register', $butterbean, $post_type );

The hook passes 2 parameters that you can use:

  • $butterbean – This is the plugin object.
  • $post_type – Post type of the current post that’s being edited/created.

So, let’s create a custom registration function that will run for the page post type.

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

function butterbean_lesson_1_register( $butterbean, $post_type ) {

        // Let's bail if not on our post type screen.
        if ( 'page' !== $post_type )
                return;

        // Register managers, sections, controls, and settings here.
}

Creating a manager

A manager in ButterBean is just a meta box. Actually, it’s a tabbed group of sections (below) within a meta box. Think of it as a way to put a lot of stuff in one area.

It’s possible to register multiple managers. However, most projects will only need one.

To register a manager, you should use the $butterbean->register_manager() function. In this tutorial, we’re going to focus on just doing the basics. I’ll cover more advanced manager concepts in a later tutorial.

A basic manager looks like the following:

$butterbean->register_manager(
        'lesson_1',
        array(
                'label'     => 'ButterBean Lesson #1',
                'post_type' => 'page'
        )
);

The first parameter is the unique name/ID for the manager.

The second parameter is an array of arguments. We set the label, which is used as the meta box title and the post_type to tell ButterBean on which post type screens this manager is being used on.

In order to register sections, controls, and settings for a manager, you’ll need to get a copy of the manager object you just registered. You do this like so:

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

This is actually important to note before we get to the next sections: the $butterbean object houses managers and the $manager object houses sections, controls, and settings.

Creating a section

Sections are the “tabs” within a manager. They’re a way to group multiple controls. If you’ve ever worked with the WordPress customizer, this process is essentially the same.

$manager->register_section(
        'lesson_1_section_a',
        array(
                'label'    => 'Section A',
                'dashicon' => 'dashicons-admin-generic'
        )
);

The first parameter is the unique name/ID for the section.

The second parameter is an array of arguments for registering the section. We set the label, which is used as the “tab” link. And, we set an icon from one of the available Dashicons included in core WordPress.

Creating a control

Now we’re really getting into the more interesting stuff. Controls represent the form fields that are output on the screen. Controls can be anything as simple as a basic text field to something more complex like a image upload using the core media modal.

There are many built-in types of controls, which I’ll cover in a later tutorial. For this example, we’re going to create a basic text control using the $manager->register_control() function.

$manager->register_control(
        'lesson_1_meta_a',
        array(
                'type'    => 'text',
                'section' => 'lesson_1_section_a',
                'label'   => 'Example Text Input',
        )
);

The first parameter is the unique name/ID of the control. It’s also the name of the “setting” or “meta key” (see below). There are more advanced ways to tie a control + setting together, but the easiest is to give the control and setting the same name.

The second parameter is an array of arguments:

  • type – We’ve set the type to the default of text.
  • section – Name of the section to add the control to.
  • label – The title/label to display to the user.

Like I said, controls can get advanced, so I’ll be covering them in more tutorials down the road.

Creating a setting

Settings are methods of storing data. By default, ButterBean is only concerned with storing post metadata. However, it’s possible to use it to store an option in the wp_options table, handle storing a taxonomy term for a post, and anything else with custom setting classes.

You’ll want to tie settings to a particular control. The easiest way to do this is to give the control and setting the same name. By default, this is also the name of the meta key. So, if you have a setting with the name of example, you can use the get_post_meta( $post_id, 'example', true ) for outputting it on the front end.

To create a setting, you use the $manager->register_setting() function like so:

$manager->register_setting(
        'lesson_1_meta_a',
        array(
                'default'           => 'Hello, world!',
                'sanitize_callback' => 'sanitize_text_field'
        )
);

The first parameter is the unique name/ID of the setting. Remember, it’s also the meta key that gets stored in the database.

The second parameter is an array of arguments for the setting:

  • default – This is an optional default that can be set. Only used on the new post screen for most controls.
  • sanitize_callback – This is a function to call to sanitize the data. This should always be set. Make sure to sanitize and/or validate your data. Always.

Get started

I plan to release an example plugin for all lessons on GitHub. Here’s Lesson #1.

This is just a rough outline of how development with ButterBean works. It is going to take several tutorials and docs to fully explain all of the power behind the framework. So, stay tuned!

Also, feel free to post in the comments about any documentation or tutorials you’d like to see. You’re also more than welcome to contribute to the Wiki on GitHub for ButterBean.

2 Comments


  1. Thanks Justin for all the hard work on this framework!

    It would really help if we could subscribe to your Blog posts. This way I would receive your Posts in my inbox and not forget to check the upcoming tutorials.

Comments are closed.