The WordPress Customizer: Panels & Custom Login 4 (dev)

Over the past few weeks I’ve been rewriting my most popular WordPress plugin; Custom Login. It’s been at version 3.x for a little over a year when I rewrote the plugin at the end of twenty fourteen. Version 4 will see a lot of improvements (too many to list right now), the biggest being a new option to design the /wp-login.php page via the WordPress customizer. If you’re not familiar with it, I suggest you check out the Theme Customization API codex.

What is the Theme Customization API?

The Theme Customization screen (i.e. “Theme Customizer”) allows site admins to tweak a theme’s settings, color scheme or widgets, and see a preview of those changes in real time.

Using the customizer has great benefits to something that controls the look of a page, especially when those changes show up in real time.

Creating settings for a plugin

In WordPress 4.0 improvements were made to the cuztomizer api which introduced panels. A panel, just like a section is a container for controls, a panel is a container for sections. This allows developers to create a single container for their settings to live in. It also has an optional argument parameter called ‘active_callback’ which accepts a boolean value. The ‘active_callback’ tells the panel to show/hide depending on what page or URL the customize.php is looking at. For the sake of this quick tutorial I am going to ignore the ‘active_callback’ argument.

Basic setting and control

The following example is just that; an example. In this example I’ve created a simple setting to change the background color of an element. This setting has a controller and lives in the Custom Login form section, which is housed in the Custom Login panel container.

Note that in the example I am not using the ‘active_callback’ to show/hide the panel, so all Custom Login settings that would be registered would always show.

A Code Walk-through

namespace Passy;

add_action( 'customize_register', __NAMESPACE__ . '\\customize_register' );

function customize_register( WP_Customize_Manager $wp_customize ) {}

I’m prefixing this file with a namespace to avoid function collisions. The WordPress action customize_register accepts one parameter; $wp_customize. Which is an instance of the WP_Customize_Manager object.

$wp_customize->add_panel(
  'custom_login_settings',
  array(
    'priority' => 10,
    'capability' => 'manage_options',
    'title' => __( 'Custom Login', 'custom-login' ),
    'description' => __( 'Style your wp-login.php page with ease.', 'custom-login' ),
  )
);

This optional step add the container for sections. If your settings don’t need more than one section a panel is most likely not needed. The add_panel accepts to arguments, the ID of the panel and the settings arguments array. For more info check out the add_panel developer docs.

$wp_customize->add_section(
  'custom_login_form',
  array(
    'title' => __( 'Custom Login Form', 'custom-login',
    'panel' => 'custom_login_settings', // WordPress 4.3
    'capability' => 'manage_options', // If different then the panel 'capability'
    'priority' => 10,
  )
);

Sections are the real containers for your settings and your settings controllers. I’m giving the section an ID and defining some basic settings for the section. For more info check out the add_section developer docs.

$wp_customize->add_setting(
  'form_background',
  array(
    'default'    => '',
    'type'       => 'option', // this is a option not a theme mod AKA get_option()
    'capability' => 'manage_options',
  )
);

The add_setting is a required method to define your plugin or theme settings. Give your setting an ID and arguments. In this case the important arg is the type. For plugins you define the type as an “option” and for themes it would be “theme_mod” (default).

$wp_customize->add_control(
  new WP_Customize_Color_Control(
    $wp_customize,
    'form_background',
    array(
      'label'    => __( 'Form Background Color', 'custom-login' ),
      'section'  => 'custom_login_form',
      'settings' => 'custom_login_settings["design"]',
    )
  )
);

The controller for the setting is the most important method. It registers what type of setting the add_setting ID is. In this example we’re instantiating a new object of the WP_Customize_Color_Control (a WordPress core class) passing in the current $wp_customize object and setting the ID to the ID of the registered setting (our previous code example) and then defining some arguments like which section this setting lives in and the settings argument which will inherit the get_option() option ID. For more info check out the add_control codex.

Custom Login Customize in version 4

If you’d like to track the development progress of Custom Login check out the dev branch on GitHub. Note this is a work in progress, and should not be used in production, it’s not even in beta.

Resources

• Justin Tadlock – Images in the cutomizer
• tutsplus – Color schemes
• Otto What’s new (2015)
• WordPress Theme Handbook