Google+
4elements web design & consultancy

Shineyrock

web design & consultancy
Shineyrock web design & consultancy

Shineyrock

  1. web design and consultancy

blog

  1. Home
  2. blog
  3. read
  4. Customizer JavaScript APIs: The Previewer
  • dislike -5 22

    Customizer JavaScript APIs: The Previewer

    1. November 2016
    2. Daily
    3. read 823
    4. response 1

    Let's assume we've built a theme with a number of Customizer Settings and Controls which allow your theme users to customize a number of things on the theme front-end such as the website title, tagline, and color.

    However, some of our users may not immediately be aware that they are able to customise these particular parts of the theme, especially if they are buried under multiple Panels and Sections. So how can we make it quicker for them to customise the theme?

    WordPress.com has recently added Edit buttons on some editable areas, which are immediately noticeable upon launching the Customizer. When the user clicks these buttons, it will show them the respective Control.

    Two Edit buttons in WordPresscom Customizer
    The new "Edit" button in the Customizer Preview window on WordPress.com, 

    This is a nice UX improvement that we actually can also achieve with the Customizer JavaScript API on our theme. And you'll find that doing so is not as complicated as you may have imagined. So, let's take a quick look at how it works.

    Prerequisites

    In the last tutorial, we only wrote code in the customizer-control.js file, which affects the Customizer back-end interfaces. In this tutorial, we will also employ the other file, customizer-preview.js, which is loaded in the Preview window. You should have these two files created and loaded. Otherwise, I suggest that you follow the first tutorial of this series before proceeding further.

    Creating an Edit Button

    First of all, we add a couple of Edit buttons next to the Site Title.

    <h1 class="site-title">
	<a href="<?php echo esc_url( home_url( '/' ) ); ?>" rel="home"><?php bloginfo( 'name' ); ?></a>
	<?php if ( is_customize_preview() ) : ?>
	<button class="customizer-edit" data-control='{ "name":"blogname" } ''><?php esc_html_e( 'Edit Text', 'cjs' ); ?></button>
	<button class="customizer-edit" data-control='{ "name":"header_textcolor", "color": true } ''><?php esc_html_e( 'Edit Color', 'cjs' ); ?></button>
	<?php endif; ?>
</h1>

    Using is_customize_preview(), this button will only be shown in the Customizer Preview window. Each of these buttons is assigned with a class name, .customizer-edit, which will enable us to select these buttons and bind them with a click Event later on.

    Furthermore, we've also added these buttons with a data-control attribute containing the name or the id of the registered Settings in the Customizer. The name in this attribute will help us determine the correct Setting and Control to serve to the user later on.

    An example of using the data-control attribute
    Two edit buttons to customize the Title and the Title color.

    Since presentation is not our primary concern for now, our two "Edit" buttons in the Preview window do not look as nice as the ones in WordPress.com. You may add the styles in a way that matches your theme design as a whole.

    Defining a Custom Event

    Next, we define a custom Event; an Event that tells one of these buttons is clicked. Add the following code in the customizer-preview.js file.

    var customize = wp.customize;

$( document.body ).on( 'click', '.customizer-edit', function(){
	customize.preview.send( 'preview-edit', $( this ).data( 'control' ) );
});

    The code binds each of these buttons with the click Event, using the  .preview.send() method to cast an Event. The .preview.send() method takes two parameters, namely the custom Event name and the argument. In our case, we've defined a new Event called preview-edit, and pass an argument with data retrieved from the data-control attribute of the button.

    Listening to the Custom Event

    We can listen to a custom Event cast from the .preview.send() method through another Customizer method called .previewer.bind()—notice the previewer with er. This method is similar to the jQuery .on() Method, in which we define the Event name to listen and a function that will run when the Event is triggered. Add .previewer.bind() in the customizer-control.js, as follows.

    var customize = wp.customize;

customize.previewer.bind( 'preview-edit', function( data ) {

} );

    Next, we transform the data passed into a JSON compliance format, select a control element based on the name retrieved out of the data, and focus on the control element using the Customizer .focus() method.

    var customize = wp.customize;

customize.previewer.bind( 'preview-edit', function( data ) {
	var data = JSON.parse( data );
	var control = customize.control( data.name );

	control.focus();
} );

    Now, as you can see below, when we click on, for example, the "Edit Text" button, it will show the "Site Title" setting and focus the cursor in the input.

    Updating the site title
    The Edit button in action.

    Furthermore, if we look at the source code therein, the .focus() method accepts a parameter called completeCallback. This parameter runs consecutively after the .focus() function is executed. We can utilise this parameter, for example, to add an animation effect.

    customize.previewer.bind( 'preview-edit', function( data ) {

	var data = JSON.parse( data );
	var control = customize.control( data.name );

	control.focus( {
		completeCallback : function() {
			setTimeout( function() {
				control.container.addClass( 'shake animated' );
			}, 300 );
		}
	} );
} );

    The overall experience now feels more alive.

    The final version of the experience
    Input element enhanced with CSS animation

    Wrapping Up

    We have mentioned a number of the Customizer JavaScript APIs:

    • .preview.send() method to cast a custom Event.
    • .previewer.bind() method to bind the Customizer with a custom Event.
    • .focus() method to focus on an input element of a Control as well as the completeCallback parameter.

    In this tutorial, we use these methods to allow our theme users to edit the Site Title text quickly by clicking on the "Edit Text" button in the Preview window.

    We still have one button remaining to bring up the Color controls. But I will leave it here as a challenge; use the same three methods to make the "Edit Color" function. When in doubt, feel free to take a glimpse at the source code.

    Photo

    martijn broeders

    founder/ strategic creative at shineyrock web design & consultancy
    e-mail: .(JavaScript must be enabled to view this email address)
    phone: 434 210 0245
    Add a comment...
    4elements
    Comments
  • 1
    silhouette
    Mora
    August 18, 2018 at

    I quite like looking through an article that will make men and women think. Also, thanks for permitting me to comment!

    4elements
    Comments

By - category

    By - date

      Copyright © 1999 - 2024 Shineyrock web design and consultancy, All Rights Reserved / Terms of Conditions / Sitemap: XML, HTML, Images, Mobile, News