Adding fields to the Customizer

Intro

WordPress 3.4 introduced one of the biggest new features in years - the Customizer. It allows users to adjust the settings of their WordPress site through an interface, which shows a preview of the website and all changes are immediately applied in that preview.

Ultimate Fields not only makes adding fields to the Customizer a piece of cake, but also pioneers the possibility to customize the settings of posts, terms and users there. Yes - you can even customize individual pages now!

Support

As mentioned above, there are various locations that are supported in the customizer. Those include:

• Options Pages: You can simply bring the fields that you already have in your theme options to the customizer.
• Customizer: If you wish not to display a settings page in the backend, but still use the customizer, you can use this location.
• Post Type
• Taxonomy
• User

The first two location types will have a constantly displayed section in the customizer. The rest will only be displayed when an item of the right type is being shown. This means that if you have a container, associated with a post type, you will only see it when you are customizing a page and etc.

Usage in the UI

If you are using the Administration Interface, associating locations with the customizer is fairly easy: You just need to go to the "Customizer" tab in the location's box. There you can let the container/location appear in the customizer.

You can even define postMessage fields, which will be directly sent from the customizer to the preview through JavaScript without having to reload the preview.

That's it - once you have performed those simple steps, your fields will appear in the Customizer.

Usage in PHP

In PHP you can use the show_in_customizer and postmessage_fields arguments in the $args array or use the show_in_customizer and set_dynamic_fields methods when creating locations.

// Using arguments
$container->add_location( 'taxonomy', 'category', array(
	'show_in_customizer' => true,
	'postmessage_fields' => array( 'category_color' ) )
));

// Creating an instance
$location = new UF\Location\Taxonomy( 'category' );
$location->show_in_customizer();
$location->set_dynamic_fields(array( 'category_color' ));

Both of these approaches work the same way with all supported locations. The "Customizer" location is the only exception, as there you do not need to use show_in_customizer and can only pass the postmessage_fields when needed.

Displaying data in the front-end

The customizer works with two types of values:

• Standard: When normal values are changed the customizer refreshes the preview of the page and displays them. This experience is slightly less seamless for end users, but does not require any additional development steps.
• Dynamic (or PostMessage): Those values are directly sent to the preview through JavaScript and do not refresh the page. This method provides a seamless preview, but requires extra development steps.

The following steps are only required for dynamic fields.

Enqueuing JavaScript

In order to handle data changes in JavaScript you will need to enqueue an additional scripts.

Because those additionals scripts are only required in the cusotmizer, you should use the customize_preview_init hook instead of wp_enqueue_scripts. There you need to enqueue your script while adding a dependency on the uf-customize-preview script, as well as all other scripts, which you need.

add_action( 'customize_preview_init', 'showcase_colors_js' );
function showcase_colors_js() {
	$uri = get_template_directory_uri() . '/modules/colors/customizer.js';
	wp_enqueue_script( 'showcase-colors', $uri, array( 'jquery', 'uf-customize-preview' ), '1.0', true );
}

JavaScript Implementation

Within your JavaScript file you will have access to the UF.customize object, which builts on top of the Customizer API in order to allow context to be carried alongside the normal value.

You need to use the UF.customize.bind( field_name, callback ) method. Once a setting has been updated, the callback will receive two parameters:

1. value contains the new raw value of the field.
2. context may contain additional data for the value.

UF.customize.bind( 'header_color', function( value, context ) {
	$( '.header' ).css({
    	backgroundColor: value
	});
});

Field Names

In the example above we use "header_color" as the field name. This works the same way for the "Options Page" and "Customizer" locations. For the rest, you have to append a type to the field name.

Location	Format	Field Name	Example
Options Page	FIELD_NAME	header_color	header_color
Customizer	FIELD_NAME	header_color	header_color
Post Type	FIELD_NAME[post_ID]	header_color	header_color[post_5]
Taxonomy	FIELD_NAME[term_ID]	header_color	header_color[term_5]
User	FIELD_NAME[user_ID]	header_color	header_color[user_5]

The reason to have to do this is that unlike generic options, a user can navigate between multiple pages, terms and users while in the customizer and each of them must be able to have its own values.

Context

The context parameter of the callback may receive additional data based on the field type:

A standard text field will not receive any additional information, since the value is basic enough.

The basic value of an image field would be just the identifier of the attachment, which is next to useless in JavaScript, as it would require an additional AJAX request to load the image and that would make the whole experience (both for users and developers) anything but seamless. This is why for image fields, the context parameter contains the same data, which is normally generated by wp_prepare_attachment_for_js. This allows you to do the following:

UF.customize.bind( 'header_background[post_2]', function( value, context ) {
    var header = $( '.page-header' );

    if( value ) {
        header.css({
            backgroundImage: 'url(' + context.sizes.full.url + ')'
        });
    } else {
        header.css({
            backgroundImage: false
        });
    }
})

In this particular example we are getting the full image size (uncropped) and using its src property for the background image of the header.

Each field type may contain different types of data for the context. The article for each of those field will include details on what you should expect.

Example

You can check out a fully working example at https://github.com/imJignesh/uf-showcase-theme/tree/master/modules/colors.

This is a module from the showcase theme, which comes with Ultimate Fields. The module uses a couple of locations and field types in order to show how the Customizer can be useful in combination with Ultimate Fields.