ButterBean

ButterBean is a neat little post meta box framework built on Backbone.js and Underscore.js. You can run it as a standalone plugin or drop it into your own plugins.

GitHub Download
Version 1.0.0 · FAQs · Support

ButterBean Example

How it works

ButterBean is a simple framework meant for building single meta boxes that handle many fields. This is often a better option than many meta boxes. It’s probably most useful as a drop-in framework for custom post types. What follows is a quick setup guide to get you started using it.

Installation

If not using ButterBean as a standalone plugin, you need to drop the butterbean folder into your theme and load the main butterbean.php file.

PHP

add_action( 'plugins_loaded', 'th_load' );

function th_load() {

	require_once( 'path/to/butterbean/butterbean.php' );
}

Registration callback

To register your custom managers, sections, controls, and settings, you’ll need to use the butterbean_register action hook. This hook will pass the $butterbean object and the current $post_type string.

PHP

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

function th_register( $butterbean, $post_type ) {

	// Bail if not our post type.
	if ( 'your_post_type' !== $post_type )
		return;

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

Build a manager

A manager is a group of sections and controls. A single manager is tied to a single meta box on the edit post screen. You can have multiple managers (meta boxes) per screen if desired.

PHP

$butterbean->register_manager(
	'example',
	array(
		'label'     => esc_html__( 'Example', 'your-textdomain' ),
		'post_type' => 'your_post_type',
		'context'   => 'normal',
		'priority'  => 'high'
	)
);

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

Create custom sections

Sections allow you to group controls. You can add a custom label, description, and icon for each section.

PHP

$manager->register_section(
	'section_1',
	array(
		'label' => esc_html__( 'Section 1', 'your-textdomain' ),
		'icon'  => 'dashicons-admin-generic'
	)
);

Create custom controls

Controls are your fields within the manager. They are tied to a specific section and setting. A control can be as simple as a plain textbox to more a more complicated WordPress media view.

There are several built-in control types. Plus, you can extend the ButterBean_Control class with you own control types.

PHP

$manager->register_control(
	'abc_xyz', // Same as setting name.
	array(
		'type'    => 'text',
		'section' => 'section_1',
		'label'   => esc_html__( 'Control ABC', 'your-textdomain' ),
		'attr'    => array( 'class' => 'widefat' )
	)
);

Create custom settings

Settings are how your data is saved. By default, the setting name is a post meta key, so you can use the data on the front end like any other post meta. Make sure to set a sanitize_callback function to sanitize and/or validate your data before it’s saved to the database.

PHP

$manager->register_setting(
	'abc_xyz', // Same as control name.
	array(
		'sanitize_callback' => 'wp_filter_nohtml_kses'
	)
);

FAQs

Some questions and answers you might find useful.

Why did you build this?

ButterBean was originally built as a part of the Custom Content Portfolio plugin. I liked the interface and ported it to a couple of other plugins. It just made sense to separate it into its own project where I could reuse it when I needed.

Another meta box plugin?

Why not? I’m fully aware of existing solutions like CMB2 and ACF. I’m sure those are useful for some folks and will definitely have more features than ButterBean ever will. I just want something simple that I can drop into my own plugins.

Why use Backbone.js?

Mostly, it was a personal experiment in learning a JavaScript framework. Plus, it was already packaged with WordPress, so it made sense to learn it in order to better understand the JS code in core WordPress.

Do I need to know Backbone or Undescore?

No, you don’t need them to use ButterBean. However, you’ll need to know how Underscore templates work if you want to build custom controls. For more advanced, custom JS controls, you’ll want to pick up a little Backbone knowledge.