ButterBean Lesson #3: Sections

In the previous tutorial on managers, I explained how managers house everything else within the ButterBean framework, namely sections and controls.

In this tutorial, I’ll be covering how sections work within an individual manager. A section is a way to group one of more controls within the manager.

If you’ve ever worked with the WordPress customize API, the concepts are pretty much exactly the same.

Basics of adding section

A section must be “attached” to a manager object. So, you can’t register a section with an existing manager. Sections are registered with the $manager->register_section() function, where $manager is an instance of the ButterBean_Manager class.

The following code will register a manager and a section for that manager.

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

function butterbean_lesson_3_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_3',
        array(
            'label'     => 'ButterBean Lesson #3',
            'post_type' => 'page'
        )
    );

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

    // Register custom sections.
    $manager->register_section(
        'lesson_3_a',
        array(
            'label' => 'Section A',
            'icon'  => 'dashicons-admin-generic'
        )
    );
}

The section part of the code is given a unique name/ID of lessone_3_a. We also defined a label and icon.

It’s important to note that sections require controls before they will appear in the UI. I’ll be covering controls in Lesson #4 of this tutorial series.

Additional arguments

The following list is of all the arguments that can be passed to $manager->register_section( $name, $args ) and what they do.

typestring

This represents the type of section to use. The default is aptly titled default. There’s little chance that most developers will ever need to change this. However, the possibility is there for utilizing custom sections, which we’ll save for a tutorial in the future.

labelstring

This is the text label that is shown to users and is required to be set. This label should be internationalized so that it can be translated.

descriptionstring

This is a custom description that will appear at the top of the section output, above the controls, if present. The description should be internationalized as well.

iconstring

All sections need to have an icon defined. The default icons are from the core WordPress Dashicons. You need only input the Dashicon name and the appropriate icon will appear. The default icon is dashicons-admin-generic.

Any custom class can actually be used here. However, you’ll need to handle the CSS for anything other than core WP’s Dashicons.

priorityinteger

This is the priority in which your section should be given in relation to the other sections. The default priority is 10. Priority is handled in order from low to high numbers.

capabilitystring

This is a user role capability that you can pass to the section that allows it to only be shown to users with the given capability. For example, if you pass in manage_options, the section 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 section 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 section will not show.

Section functions

The ButterBean_Manager and the $manager object from that class has several functions for working with sections. We’ve covered the $manager->register_section() function above. The following are other section-related functions that might prove useful.

$manager->get_section( $name )

This function returns a section object. You can get an overview of section objects by opening inc/class-section.php.

$section = $manager->get_section( 'lesson_3_a' );

$manager->unregister_section( $name )

This function removes an existing section object.

$manager->unregister_section( 'lesson_3_a' );

$manager->section_exists( $name )

This function checks if a section exists (i.e., if it has been registered). It returns true or false.

if ( $manager->section_exists( 'lesson_3_a' ) ) {

        // Do something if the lessone_3_a section exists.
}

Dive into sections

Now that we’ve covered managers and sections, you should be getting a feel for how things work. Managers and sections are perhaps the two easiest concepts in ButterBean. Controls is where things get a bit more complicated. However, we needed to cover the basics so that you would have a solid foundation to build from.

In the next tutorial, I’ll be covering controls and explaining how all of the built-in controls work. Stay tuned for something a bit more exciting!

1 Comment

Comments are closed.