Using tooltips instead of option descriptions in the WordPress Theme Customizer

In my previous article I discussed the basics of the JavaScript API in WordPress, and how it relates to the theme customization screen. Now, it’s time to put what we’ve learned into practice, and learn a few new things along the way! In this post I’ll cover how you can easily convert descriptions of the various controls in the customizer into icons that display tooltips on rollover; an elegant way to keep the interface clean and intuitive.

Previously, I wrote that scripts may be added to the theme customization screen via the customize_preview_init and customize_controls_enqueue_scripts actions.

However, in this case the script is simple enough that there is no need to embed it in an additional file; instead, we can use use the third method of adding scripts to the theme customization screen – through the customize_controls_print_scripts action:

function dziudek_theme_customizer_tooltips() {
	?>
	<script type="text/javascript">
	// Theme Customizer script HERE
	</script>
	<?php
}

add_action('customize_controls_print_scripts', 'dziudek_theme_customizer_tooltips');

So what will this script do?

Here’s a brief rundown:

1. It waits until the customization screen interface is loaded
2. Iterating through all the controls, it detects which of them are descriptions
3. It retrieves these descriptions and places them in the variable while removing the element itself
4. A i element with the specific icon and title attribute, including the control’s description, is added to the control label

The icon which we use for the tooltip is of course taken from the Dashicons set.

Let’s start with how to detect when the theme customization screen interface is ready for modification. Here we’ll need to rely on two things:

1. DOMContentLoaded – This ensures that the wp.customize object is available for our script
2. ready – This event is generated by screen customization scripts

The code then should look as follows:

function dziudek_theme_customizer_tooltips() {
	?>
	<script type="text/javascript">
	jQuery(document).ready(function() {
		wp.customize.bind('ready', function() {
				
		});
	});
	</script>
	<?php
}

add_action('customize_controls_print_scripts', 'dziudek_theme_customizer_tooltips');

Now it’s time to add the actions that operate on our controls:

wp.customize.control.each(function(ctrl, i) {
	var description = ctrl.container.find('.customize-control-description');
	if(description.length) {
		
	}
});	

The above code iterates through all the controls due to the each method and, by referring to the container field of the control, it finds a description element which has a customize-control-description class. Since the description element is optional, we also need to add a condition that checks that this actually exists before performing any further steps.

Then we need to get the text from the description, remove it, and insert the icon to the title area:

wp.customize.control.each(function(ctrl, i) {
	var description = ctrl.container.find('.customize-control-description');
	if(description.length) {
		var title = ctrl.container.find('.customize-control-title');
		var tooltip = description.text();
		description.remove();
		title.append(' <i class="dashicons dashicons-editor-help" style="vertical-align: text-bottom;" title="'+tooltip+'"></i>');
	}
});	

Notice that there’s a space preceding the icon element to keep it separate from the title, as well as the use of inline styles here – in this case adding separate CSS styles is pointless, but with more extensive modifications, I recommend the use of an additional CSS class.

The entire script code is as follows:

function dziudek_theme_customizer_tooltips() {
	?>
	<script type="text/javascript">
	jQuery(document).ready(function() {
		wp.customize.bind('ready', function() {
			wp.customize.control.each(function(ctrl, i) {
				var description = ctrl.container.find('.customize-control-description');
				if(description.length) {
					var title = ctrl.container.find('.customize-control-title');
					var tooltip = description.text();
					description.remove();
					title.append(' <i class="dashicons dashicons-editor-help" style="vertical-align: text-bottom;" title="'+tooltip+'"></i>');
				}
			});	
		});
	});
	</script>
	<?php
}

add_action('customize_controls_print_scripts', 'dziudek_theme_customizer_tooltips');

As an exercise you can add tooltips that are styled in CSS e.g. through the dfn element.