Theme Customization Screen – Controls

The basic element that’s used to manage the personalization options in the theme customization screen is a control. It can be a text field, selection list or more complex elements such as, for example, a color-selection block.

WordPress 4.0 introduces lots of improvements in this area, so creating complex options has become much more convenient.

Creating a control

We create controls with the add_control method, which has two kinds of calls – single and binary. If we’re creating a basic control, the we’ll use the binary call.

$wp_customize->add_control(
    'setting_name',
    array(
        'option' => 'value'
    )
);

It pays to remember that the before we even start creating a new control we should first define the setting using the add_setting method – this setting is then associated with the control in the first argument of the method; add_control. An associative array of options specifies the additional parameters to control. Here’s an example of the settings array:

array(
    'label' => 'Test option',
    'description' => 'Test description',
    'type' => 'text',
    'section' => 'test',
    'priority' => 0
);

If you’re wondering what the individual parameters are for, here’s a short description:

• label – set the control label
• description – the description of the control displayed under the label- this feature was added in WordPress 4.0
• type – the type of control being created
• section – identifies the section where the control is to be assigned
• priority – a parameter for determining the order controls are displayed in the defined section

Theoretically, it is also possible to use another method for creating a control:

$wp_customize->add_control(
    'control_name',
    array(
        …
        'setting' => 'setting_name',
        …
    )
);

In this case, the first argument does not need to be associated with the name of the setting – then, a link is created on the basis of the setting parameter.

On the other hand, when it comes to the add_control method with a single argument, we use it in more complex controls that are offered by WordPress, or in our own created controls:

$wp_customize->add_control(
    new WP_Customize_Color_Control(
        $wp_customize,
        'text_color',
        array(
            'label' => __('Text Color', 'mytheme'),
            'section' => 'colors'
        )
    )
);

The only argument in this case is class instance that creates the control and accepts three arguments:

• manager object of the personalisation screen
• name of setting (or name of control, if we’re using the setting) parameter
• associative array of settings as used in the binary add_control method.

Available types of controls

We have the following types of controls at our disposal:

• text,
• textarea,
• radio (requires additional choices parameter),
• select (requires additional choicesparameter),
• checkbox,
• dropdown-pages

Among the controls that use the single argument add_control method, the ones worth knowing are:

• WP_Customize_Color_Control,
• WP_Customize_Image_Control,
• WP_Customize_Upload_Control,
• WP_Customize_Background_Image_Control,
• WP_Customize_Header_Image_Control

Even more controls

If the controls that I mentioned earlier are not sufficient enough for your needs, then we may take advantage of the fact that WordPress 4.0 and later allows us to specify as a type parameter any value that is supported by the type attribute of the input element in HTML5.

Furthermore, in the input_attrs parameter, we may specify an associative array of additional attributes, which may require an item:

$wp_customize->add_control(
    'mytheme_layout_width',
    array(
        'type' => 'range',
        …
        'input_attrs' => array(
            'min' => 720,
            'max' => 1280,
            'step' => 1
        )
    )
);

Undoubtedly, we should bear in mind that lots of controls have very limited support, which may cause our controls to display incorrectly.

Easy modifications of controls

Existing controls can be modified in two ways – at the PHP level or via the CSS/JS code.

In the case of PHP code , we use the following methods:

• get_control – allows for the modification of parameters for controls that are already declared
• remove_control – allows the removal of a specific control

An example of code that changes the control description:

$wp_customize->get_control('test_control')->description = 'New description';

And the code that removes the control:

$wp_customize->remove_control('test_control');

Thanks to the above functions, we are able to delete unnecessary controls added by WordPress or plugins or, for example, relocate standard controls to different sections.

Should you prefer to make your modifications at the JS/CSS level, you should usethe customize_controls_enqueue_scripts action, which allows you to add your own JS scripts and CSS styles to the personalization screen.

When you modify controls using JS code, I recommend that you add prior to the elements that you want to change some extra CSS classes via the input_attrs argument:

array(
    "input_attrs" => array(
        "class" => "js-override"
    )
)

Own controls?

The personalization screen’s API allows us to create our own controls – in fact, all controls are created with a single argument calling the add_control function. The topic of creating own controls is quite complex, which is why I decided to devote a separate post to this issue. At this point, I would like you to consider whether it is absolutely necessary to create your own controls, as a lot can be achieved just by modifying the existing controls, and many functions can be applied with the correct context.

Summary

Controls are elements of the personalization screen that theme developers haven’t had much impact on in the past, but that have the greatest impact on the relative comfort of configuring a theme. With the changes introduced in WordPress 4.0, developers can offer better fine-tuning options than ever before.