Using contextual controls in the WordPress theme customizer

For me, one of the most important improvements in the WordPress Theme Customizer’s functionality with the release of WordPress 4.0 is the ability to control when and where theme settings appear. With this functionality, it’s possible to limit options, preventing them from appearing on subpages where they are not relevant, or create additional controls or settings that are only available under particular circumstances. This allows us to streamline and improve the user experience when dealing with theme settings.

Important contextual features

When defining the context in which options are available, there are two important contextual features in WordPress 4.0 to be aware of:

1. Contextual controls are specifically for theme customizer settings only
2.  The visibility of particular settings in turn influences the visibility of the settings’ section and panels

So, we can’t block an entire section of settings in the customizer from appearing when the user in on a particular subpage, but if we specify that each individual setting in a particular section is hidden, WordPress will automatically hide the section since there are no settings to change. For example, let’s say our theme has a “Layouts” section, and inside this are three options; “Desktop Width”, “Tablet Width”, and “Mobile Width”. We can’t write a contextual control that will remove the “Layouts” section from the customizer, but we can create a control that hides the three individual width options, that will in turn cause the entire “Layouts” section to be hidden since there are no options to display.

How to add contextual controls to a setting?

We may add a contextual control that defines when a particular option should be available by specifying the active_callback parameter in the setting’s creation process, like in the following example:

$wp_customizer->add_control(
  'setting_name',
  array(
    'type' => 'text',
    'section' => 'section_name',
    'label' => 'Option with context',
    'active_callback' => 'is_front_page'
  )
);

In the above example, this new setting will appear only when the theme customizer’s preview is pointed to a homepage displayed on the website, thanks to the native is_front_page function.

Additionally, if this setting is the only one for a specific section, then when a page, post or other area of the website other than the homepage is displayed in the preview window, the entire section will be hidden.

Creating your own contexts for controls

Of course, it’s very unlikely that you’ll get all the controls you need from the native functions available in WordPress; thankfully it is entirely possible to create your own context functions. For example, we could create a function that detects if a subpage displays a theme gallery:

function mytheme_is_gallery_page() {
   return is_page_template('template.gallery.php');
}

Then, when creating the setting, we can link to the new contextual control much like we did when referencing the is_front_page function:

$wp_customizer->add_control(
  'setting_name',
  array(
    'type' => 'text',
    'section' => 'section_name',
    'label' => 'Option with context',
    'active_callback' => 'mytheme_is_gallery_page'
  )
);

Creating dependent options

The context for a particular setting is fluid; as users change and modify the available settings and the website updates accordingly, some settings may no longer be relevant. To get around this issue, we can tweak our code to take other settings into account when deciding whether to display or not; we could have a an option that only appears on a particular page, but will still be hidden unless other settings meet the contextual requirements. For example, we could have a setting that lets you set the post list into columns; the “Number of Columns” setting could be hidden until the post listing setting is changed to “columns”.

Creating this kind of relationship between settings will require some specific knowledge about the theme customizer’s structure how its classes relate to each other.

Below, you can see a function that creates an option where users may specify the typeface to be used on the site. When the user selects the “google” option so they can use a Google Font on their site, a secondary field for the font URL will be displayed:

function mytheme_show_font_field($control) {
    $option = $control->manager->get_setting('mytheme_font');

    return $option->value() == 'google';
}

The whole thing works because for each function that is built to support a contextual control, there is a handle assigned to control which context it refers to. With a given control’s object in hand, we can use the theme customizer manager (manager’s functionality, to be specific) to read the current setting using the get_setting method.

Then, we can pass a request to the value method about the object to learn the current value of our chosen setting.

Thanks to this mechanism, we may create complex relationships between options and hide unnecessary configuration fields until they are needed.

How to use contextual controls?

The main purpose of contextual controls is to amend the option panel’s content so that it fits the current page in the preview window; options specific to the frontpage should not appear on a subpage or post page, and vice-versa.

Here’s a handful of interesting ideas for using these controls:

• we do not have to create complex controls that connect features from other standard controls – we can just create connections between them using contextual controls.
• we may create a unique set of options for subpage templates in our theme, and display the options specific to each subpage that will subsequently be invisible on other subpages.
• we may extend prior concepts regarding entries or category or tag subpages.
• we may create plugins that add options to the theme customizer that only appear on subpages relevant to the plugin, or where the plugin appears.
• with contextual controls, we may check, by reading values of specified settings, whether other plugins / settings that are essential for our option to work correctly are active.

Context in your own controls

At the end – it’s worth knowing that while creating your own control, we may define a default context function easily. A base function could look like this:

public function active_callback() {
   return true;
}

Then we can overwrite it in our control class. It can be useful, e.g. in the event that a given control needs an additional plugin to work correctly.

Summary

Contextual controls for settings are an incredible improvement that further reduces the need for your own option panels within a theme, centralizing control. They provide an effective functionality for creating a user-friendly theme or plugin that provides easy to understand options and allows you to have direct control over when a particular setting is visible to prevent confusion or other issues from arising.