MB Settings Page: Now Supports Customizer & Network Settings Pages

A custom settings page is essential for plugins. But for themes, the WordPress Customizer seems to be the standard. In the last few weeks, we worked on a big improvement of MB Settings Page to make it work in the Customizer. Moreover, you're now able to create network-wide settings pages.

Let's take a look at these features.

Customizer Support

This is a quick video that demonstrates how to use MB Settings Page to create custom panels, sections and fields in the Customizer. You'll see how easy it is to turn a settings page into a Customizer panel.

Creating A Customizer Panel

The idea behind Customizer support is map a settings page to a Customizer panel. And each meta box in the settings page will be a Customizer section. The mapping is quite simple, clear, but very powerful. It allows you to bring everything in a settings page into the Customizer with a single line of code.

Assuming you have a settings page, registered with this code:

add_filter( 'mb_settings_pages', function ( $settings_pages ) {
    $settings_pages[] = array(
        'id'          => 'rubik',
        'option_name' => 'theme_mods_justread',
        'menu_title'  => 'Theme Options',
        'parent'      => 'themes.php',
    );
    return $settings_pages;
} );

To bring it to the Customizer, simply add 'customizer' => true, e.g.:

add_filter( 'mb_settings_pages', function ( $settings_pages ) {
    $settings_pages[] = array(
        'id'          => 'rubik',
        'option_name' => 'theme_mods_justread',
        'menu_title'  => 'Theme Options',
        'parent'      => 'themes.php',
        'customizer'  => true, // THIS
    );
    return $settings_pages;
} );

And you'll see a new panel in the Customizer as follows:

And each meta box in the settings page now are the Customize section:

Disabling Admin Settings Pages

When you have Customizer panels, sections and fields, you might not want to use settings pages in the WordPress admin anymore. The Customizer now becomes the all-in-one place for entering the settings and customization.

Understanding it, we added a new parameter 'customizer_only' => true that disables the admin settings page and allows only Customizer settings:

add_filter( 'mb_settings_pages', function ( $settings_pages ) {
    $settings_pages[] = array(
        'id'               => 'rubik',
        'option_name'      => 'theme_mods_justread',
        'menu_title'       => 'Theme Options',
        'parent'           => 'themes.php',
        'customizer'       => true,
        'customizer_onlye' => true, // THIS
    );
    return $settings_pages;
} );

Creating Top-Level Customizer Sections

Sometimes you don't want the top-level panel that creates too much hierarchy (panel → sections → fields). You just want top-level sections (sections → fields). That will help users to navigate to your settings in the Customizer faster and easier.

In that case, you need to do 2 steps:

Step 1: Remove the code that registers settings pages as you don't need settings pages anymore. This is the code you should remove:

add_filter( 'mb_settings_pages', function ( $settings_pages ) {
    $settings_pages[] = array(
        'id'          => 'rubik',
        'option_name' => 'theme_mods_justread',
        'menu_title'  => 'Theme Options',
        'parent'      => 'themes.php',
        'customizer'  => true,
    );
    return $settings_pages;
} );

Step 2: In each meta box, replace the parameter 'settings_pages' => 'rubik' with 'panel' => ''.

For example, you have a meta box for your settings page, which has the following code:

add_filter( 'rwmb_meta_boxes', function ( $meta_boxes ) {
    $meta_boxes[] = array(
        'id'             => 'general',
        'title'          => 'General',
        'settings_pages' => 'rubik',
        'fields'         => array(
            array(
                'name' => 'Logo',
                'id'   => 'logo',
                'type' => 'file_input',
            ),
            array(
                'name'    => 'Layout',
                'id'      => 'layout',
                'type'    => 'image_select',
                'options' => array(
                    'sidebar-left'  => 'http://i.imgur.com/Y2sxQ2R.png',
                    'sidebar-right' => 'http://i.imgur.com/h7ONxhz.png',
                    'no-sidebar'    => 'http://i.imgur.com/m7oQKvk.png',
                ),
            ),
        ),
    );
    return $meta_boxes;
} );

Then you need to change it to:

add_filter( 'rwmb_meta_boxes', function ( $meta_boxes ) {
    $meta_boxes[] = array(
        'id'             => 'general',
        'title'          => 'General',
        'panel'          => '', // THIS
        'fields'         => array(
            array(
                'name' => 'Logo',
                'id'   => 'logo',
                'type' => 'file_input',
            ),
            array(
                'name'    => 'Layout',
                'id'      => 'layout',
                'type'    => 'image_select',
                'options' => array(
                    'sidebar-left'  => 'http://i.imgur.com/Y2sxQ2R.png',
                    'sidebar-right' => 'http://i.imgur.com/h7ONxhz.png',
                    'no-sidebar'    => 'http://i.imgur.com/m7oQKvk.png',
                ),
            ),
        ),
    );
    return $meta_boxes;
} );

It's very simple, isn't it? And you'll see the section on the Customizer like this:

What if you want the section to be inside another panel? Like inside another plugin's panel? Simply set the panel parameter to ID of the target panel: 'panel' => 'panel_id'.

Compatibility

At the moment, all Meta Box fields are supported in the Customizer, except file and image field types. But other upload field types such as file_advanced, file_upload, image_advanced, image_upload, single_image still, work very well. (The reason is that the Customizer doesn't handle file uploads and the submission is performed via Ajax)

The good news is all the extensions such as Meta Box Conditional Logic, Meta Box Tabs are supported. That will help you create much better experiences for your users.

Known issues: because of the complexity, the postMessage transport for the Customizer is not supported yet. Your browser will refresh the whole page to see the updated settings.

We have this case study on how to create a settings page for Customizer Options and this post about using MB Setting Pages to change the displayed information in a theme.

Network Settings Pages

This new version also adds support for creating network settings pages. A network settings page is a settings page that provides settings for all the websites in the network. For example, you might want to enter Google Maps API key for all the websites or set the contact phone number for all of them.

Using MB Settings Page, you're now able to do that easily with just one line of code. Simply add 'network' => true to the settings pages args. Like this:

add_filter( 'mb_settings_pages', function ( $settings_pages ) {
    $settings_pages[] = array(
        'id'          => 'custom-options',
        'option_name' => 'custom_options',
        'menu_title'  => 'Custom Options',
        'icon_url'    => 'dashicons-welcome-widgets-menus',
        'network'     => true, // THIS
    );

    return $settings_pages;
} );

Don't forget to network activate Meta Box and MB Settings Pages. And now, when you go to the network admin area, you'll see a settings page like the screenshot above.

Conclusion

With Customizer and Multisite support, we hope the plugin can help you build flexible and powerful custom options for your users and improve the user experience.

You can download the extension now on your My Account page, or use the automatic update to get it.

If you have any suggestions or ideas to make it better, please leave it in the comments below.