JS Blog

WordPress Customization API

FacebookXRedditEmail

With Customization API WordPress introduced new way of changing an appearance of WordPress theme which I think is more user-friendly since theme’s appearance settings are shown besides your website and can be updated live so you can see changes immediately.

Here is an example of use where I added a textarea control in Customize page of a theme in which you specify a custom CSS rules. I used here twentytwelve theme which I rate highly.

If you look at “Customize” listing for twentytwelve theme you’ll see a list of sections. Sections are groups of related settings. Setting is represented by its HTML representation – a control. Last list item though is not a section, but a panel; if clicked, it takes you to another layer.

So in functions.php we need to define a section, control and setting for our Custom CSS. This is done by calling appropriate methods on object that is passed to function which we are registering when adding an action to customize_register.

function twentytwelve_customize_register($wp_customize) {
    $wp_customize->add_section(...);
    $wp_customize->add_setting(...);
    $wp_customize->add_control(...);
}
add_action('customize_register', 'twentitwelve_customize_register');

For section arguments we specify its unique id and array of options – what’s its title and priority – higher the number, lower is the item positioned in “Customize” listing.

$wp_customize->add_section(
    'customcss_section',
    [
        'title'    => __('Custom CSS', 'customizer_customcss_section'),
        'priority' => 80
    ]
);

Adding a section consist of defining unique id and options for it – like what’s the default value for an option and it’s transport. Latter tells WordPress how the changes should be visible. If set to “refresh”, changes are visible after we save changes. If set to “postMessage”, changes are updated live. When we perform a change to control, we can see the change immediately. This option also requires you to write some javascript code which bind value from control to targeted DOM element (which I’ll show it later). Our add_section method looks like this.

$wp_customize->add_setting(
    'customcss',
    [
        'default'   => '',
        'transport' => 'postMessage',
    ]
);

Control is the one who ties section and setting together. We also specify there what type of control we want. There are many predefined controls but what we are looking here is textarea (and class WP_Customize_Control).

$wp_customize->add_control(new WP_Customize_Control(
    $wp_customize,
    'customcss_textarea', // control id
    [
        'section'  => 'customcss_section', // section id we set earlier
        'settings' => 'customcss',         // same goes for setting id
        'type'     => 'textarea',
    ]
));

Because we opted for real-time changes, we need to include some javascript code to make this possible. First include a custom javascript file in WordPress way.

function twentytwelve_customize_preview_js() {
    wp_enqueue_script('twentytwelve-customizer', get_template_directory_uri() . '/js/theme-customizer.js', ['customize-preview'], '20141120', true);
}
add_action('customize_preview_init', 'twentytwelve_customize_preview_js');

Next create js directory in theme’s root folder and theme_customizer.js in it. Add the following code in it:

(function($) {
    wp.customize('customcss', function(value) {
        value.bind(function(to) {
            $('style#customcss').text(to);
        });
    });
})(jQuery);

Here customcss is the id of setting and we bind value of the setting to style tag which is responsible for applying styles to our site.

Right now there doesn’t exist link tag in html so we need to create it. Back in functions.php we add another piece of code which registers style and outputs the value of setting in tags.

function mytheme_customize_css() { ?>
         <style type="text/css">
             <?= get_theme_mod('customcss'); ?>
         </style>
<?php
}
add_action('wp_head', 'mytheme_customize_css');

Bottom line: That was round-up of how you add a customization field to you WordPress theme with Customization API. Keep it in mind that there are a lot more options you can define to section/setting/panel/control so be sure to also check official resources ((Theme Customization API [codex.wordpress.org])) ((Customization API [developer.wordpress.org])) on that topic.

Jernej

, ,