The Underscores (_s) theme with Sass and Gulp Part 14: the Customizer

==================================================================

On this page:

  1. The Customizer.
  2. Add controls for the header background color.
  3. Preview settings in the Customizer.
  4. Apply Customizer changes to the front end.
  5. Add sections and radio controls to the Customizer.
  6. Change theme output based on Customizer settings.

==================================================================

75. The Customizer

Github repo branch: part14_75

Out of the box, we can control some parts of our theme through the Customizer. These parts ship with the WP core, and after installing Wordpress they are present in the Customizer. These are:

  • Site Identity;
  • Colors;
  • Header image;
  • Background image;
  • Menus;
  • Widgets
  • Homepage settings;
  • Additional CSS;

But what we're going to do is extend that functionality to new things that are not covered by Wordpress core.

  1. the inc/customizer.php file
  2. the js/customizer.js file

75.1 The inc/customizer.php file

This is where we define all the elements that will show up in the customizer, and you see, out of the box, we have some controls here. These are controls for blog name, blog description, and header text color. These are in fact also all core Wordpress features and they can already be set in the Wordpress back-end by choosing 'Setting' in the back-end menu. The reason why they're here though is because we want to be able to preview what happens when you change them in the theme. And that's done by queuing them up here in 'customizer.php' .

<?php
  /**
  * Pre Underscores Theme Customizer
  *
  * @package Pre_Underscores
  */
/**
  * Add postMessage support for site title and description for the Theme Customizer.
  *
  * @param WP_Customize_Manager $wp_customize Theme Customizer object.
  */
  function pre_underscores_customize_register( $wp_customize ) {
  $wp_customize->get_setting( 'blogname' )->transport         = 'postMessage';
  $wp_customize->get_setting( 'blogdescription' )->transport  = 'postMessage';
  $wp_customize->get_setting( 'header_textcolor' )->transport = 'postMessage';
 if ( isset( $wp_customize->selective_refresh ) ) {
  $wp_customize->selective_refresh->add_partial( 'blogname', array(
  'selector'        => '.site-title a',
  'render_callback' => 'pre_underscores_customize_partial_blogname',
  ) );
  $wp_customize->selective_refresh->add_partial( 'blogdescription', array(
  'selector'        => '.site-description',
  'render_callback' => 'pre_underscores_customize_partial_blogdescription',
  ) );
  }
  }
  add_action( 'customize_register', 'pre_underscores_customize_register' );
/**
  * Render the site title for the selective refresh partial.
  *
  * @return void
  */
  function pre_underscores_customize_partial_blogname() {
  bloginfo( 'name' );
  }
/**
  * Render the site tagline for the selective refresh partial.
  *
  * @return void
  */
  function pre_underscores_customize_partial_blogdescription() {
  bloginfo( 'description' );
  }
/**
  * Binds JS handlers to make Theme Customizer preview reload changes asynchronously.
  */
  function pre_underscores_customize_preview_js() {
  wp_enqueue_script( 'pre_underscores-customizer', get_template_directory_uri() . '/js/customizer.js', array( 'customize-preview' ), '20151215', true );
  }
  add_action( 'customize_preview_init', 'pre_underscores_customize_preview_js' );
  

75.2 The js/customizer.js file

The features who are queued up in the Customizer are called in using javascript, and applied to the preview in the Customizer. That's done in the js/customizer.js file.

/**
  * File customizer.js.
  *
  * Theme Customizer enhancements for a better user experience.
  *
  * Contains handlers to make Theme Customizer preview reload changes asynchronously.
  */
( function( $ ) {
 // Site title and description.
  wp.customize( 'blogname', function( value ) {
  value.bind( function( to ) {
  $( '.site-title a' ).text( to );
  } );
  } );
  wp.customize( 'blogdescription', function( value ) {
  value.bind( function( to ) {
  $( '.site-description' ).text( to );
  } );
  } );
 // Header text color.
  wp.customize( 'header_textcolor', function( value ) {
  value.bind( function( to ) {
  if ( 'blank' === to ) {
  $( '.site-title, .site-description' ).css( {
  'clip': 'rect(1px, 1px, 1px, 1px)',
  'position': 'absolute'
  } );
  } else {
  $( '.site-title, .site-description' ).css( {
  'clip': 'auto',
  'position': 'relative'
  } );
  $( '.site-title a, .site-description' ).css( {
  'color': to
  } );
  }
  } );
  } );
  } )( jQuery );
  

75.3 How it works.

So let's break down how that works. First, we grab the current setting for the theme, so this is the setting that's stored in the database, and we say give us the 'blogname', and then transport that 'blogname'. The same for 'blogdescription'.

$wp_customize->get_setting( 'blogname' )->transport         = 'postMessage';
$wp_customize->get_setting( 'blogdescription' )->transport  = 'postMessage';

That means we can send it to the customizer, the customizer receives the 'blogname', and then applies it to the 'site-title a' element, so it sets the text in that 'site-title a' element to whatever the 'blogname' value is.

// Site title and description.
wp.customize( 'blogname', function( value ) {
value.bind( function( to ) {
$( '.site-title a' ).text( to );
} );
} );
wp.customize( 'blogdescription', function( value ) {
value.bind( function( to ) {
$( '.site-description' ).text( to );
} );
} );

We also do the same with 'header_textcolor'.

$wp_customize->get_setting( 'header_textcolor' )->transport = 'postMessage';

Down here, we grab the 'header_textcolor'; if it's blank, then we hide the site title and description. If it actually has a color, then we go and set 'site-title a' and 'site-description' to that color value.

// Header text color.
wp.customize( 'header_textcolor', function( value ) {
value.bind( function( to ) {
if ( 'blank' === to ) {
$( '.site-title, .site-description' ).css( {
'clip': 'rect(1px, 1px, 1px, 1px)',
'position': 'absolute'
} );
} else {
$( '.site-title, .site-description' ).css( {
'clip': 'auto',
'position': 'relative'
} );
$( '.site-title a, .site-description' ).css( {
'color': to
} );
}
} );
} );
If it actually has a color, then we go and set 'site-title a' and 'site-description' to that color value. So looking at it this way, it's pretty straightforward. Moving forward, we'll add additional features to 'customizer.php', then hook into those features in 'customizer.js', so they are previewed in the customizer. And finally, we have to find a place to write the actual code that'll be applied to the theme in real-time, so that people will see the customizations on the front end.

==================================================================

76. Add controls for the header background color.

Github repo branch: part14_76

- Let's start at the beginning by adding a new control to the color section in the customizer, that targets the background color for the header and the footer. This is done inside customizer.php. If I scroll down we have the function humescores_customize_register. And I need to set up all my new fields inside this function

First, I have to create a new setting, so WordPress can store the setting in the database. I do this by grabbing the wp_customize variable. Here, I want to add a setting. I'll first give the setting a label. So, I'll call it theme_bg_color. Then, I'll set up an array of options. Inside this array, I'll first set a default color. That color should be the blue one we have here. I know that is #002254. Next, I'll set the transport to equal postMessage. That's the same thing that's happening up here and you saw previously. This is done so that we can use the customizer JavaScript to preview what we're doing. Transport equals postMessage. I need to define what type of setting this is, and, in this case, it's a theme_mod, meaning a theme modification.

Anytime I used a customizer, where someone can type in any type of code, I need to make sure there's a citation function in place to block any kind of incursion like JavaScript or anything else. For colors, there is a function for this purpose. So, I'll say sanitize callback. And here, we can either create a custom function or recall an existing one. Because we're sanitizing a hex color, there's already a function because that's something we do all the time. Function is called sanitize hex_color.

/**
* Custom Customizer Customizations
*/

// Setting for header and footer background color
$wp_customize->add_setting( 'theme_bg_color', array(
'default' => '#002254',
'transport' => 'postMessage',
'type' => 'theme_mod',
'sanitize_callback' => 'sanitize_hex_color',
));

All right. This gives me the setting, so I can pass information to the database. But if I save this and go back and reload the customizer, You'll see when I go to color, nothing is changed. That's because we have yet to create an actual control. That's next.

Again, I'll grab the wp_customize object. This time I'm adding a control. Here, I'm going to create a new WP_Customize_Color_Control.This is a standard JavaScript object that we can hook into and that automatically displays a full color control. Inside this color control, I'll grab wp_customize again. Then, define what setting I'm sending information to. That would be theme_bg_color over here. Finally, I'll set up an array of new settings. Here, I'll start the label. And I'll make sure it's translatable.This is the label that will show up when you go to the setting. Here I'll say header and footer background color. Because I'm creating a new control, I have to say what section I want to add it to. The section in question is called colors. Finally, I'll point at the actual setting itself. This is what we're controlling. So, settings, theme_bg_color.

/**
* Custom Customizer Customizations
*/

// Setting for header and footer background color
$wp_customize->add_setting( 'theme_bg_color', array(
'default' => '#002254',
'transport' => 'postMessage',
'type' => 'theme_mod',
'sanitize_callback' => 'sanitize_hex_color',
));

// Control for header and footer background color.
$wp_customize->add_control(
new WP_Customize_Color_Control(
$wp_customize,
'theme_bg_color', array(
'label' => __( 'Header and footer background color', 'humescores'),
'section' => 'colors',
'settings' => 'theme_bg_color'
)
)
);

Save that, go back in the customizer, and reload. Now, when I go to color, I'll have three options. I have text color, background color, and header and footer background color. And the current setting is the current color I have. Now, of course, this doesn't do anything right now. That's because we have yet to hook it to the actual customizer preview. That's next.

==================================================================

77. Preview settings in the Customizer.

Github repo branch: part14_77

Color setting and color control in place I can hook into the Customizer preview to see what the new color will look like before I save it, that after all is the entire purpose of the Customizer. The preview is controlled inside the js folder in the file called customizer.js. Here, I'll simply copy one of the existing functions, and paste it in again.

wp.customize( 'blogname', function( value ) {
value.bind( function( to ) {
$( '.site-title a' ).text( to );
} );
} );

and put in the right comment and parameters

So what I also did here is swap out the background colors css property for the header and the footer, so that means I need to change the css and there's an example of how to do that directly above in the code ofcustomizer.js here. So I'll copy that example and replace the text with the css call. Then I need to find the two elements I want to apply the background color to. Back here, I'll inspect those two elements. They are the header, which has the class site header, and the footer, which has the class site footer. So here, site header and site footer. As you can see, this is just standard css. Then the property that I'm changing is the background color.

// Background color for header and footer.
wp.customize( 'theme_bg_color', function( value ) {
value.bind( function( to ) {
$( '.site-header, .site-footer' ).css( {
'background-color': to
} );
} );
} );

Background dash color. Save that. Go back to the browser. I'll close the Customizer completely, then reopen it. Go to Colors, here's the header and footer background color and now when I change this color value, you can see the header changing and if I scroll to the bottom, you see the footer changing as well. Now of course, doing this allows the site owner to create some pretty hideous color combinations and that's kind of the point of the Customizer.

Here you can test your crazy ideas about what colors work well together before you put them live instead of accidentally creating some horrible color clashes and then not being able to fix it later.

==================================================================

==================================================================

78. Apply Customizer changes to the front end.

Github repo branch: part14_78

 

==================================================================

79. Add sections and radio controls to the Customizer.

Github repo branch: part14_79

==================================================================

80. Change theme output based on Customizer settings.

Github repo branch: part14_80

==================================================================

Leave a comment