Internal linking in the WordPress Theme Customizer

Recently I covered how to use tooltips instead of control descriptions – in this article, I’ll look at how to create internal linking between the elements of the theme customization screen via panels, sections and control descriptions. In order to achieve this we’ll be using some of the API functions described in my earlier article, and the fact that item descriptions may contain HTML, which we can put to our own use.

How does it work?

Internal linking may be useful when there is a large number of options in the theme and we want to associate options from different sections/panels together. Such associations help simplify navigation through the options as clicking the link will redirect to the specific control, section or panel, rather than leaving hunting it down up to the user.

Links in the description will include two important pieces of information – the type of the element to which the link leads, and its ID.

Implementation

For test purposes I suggest creating three links to three different types of element in a single description:

<a href="#blogname" rel="tc-control">Control</a>
<a href="#colors" rel="tc-section">Section</a>
<a href="#widgets" rel="tc-panel">Panel</a>

Then, using code to add scripts, we create the base frame of a function that implements internal linking support via a script:

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

add_action('customize_controls_print_scripts', 'gk_theme_customizer_internal_links');

The script creating internal linking looks as follows:

(function($) {
	$(document).ready(function() {
		var api = wp.customize;
		api.bind('ready', function() {
			$(['control', 'section', 'panel']).each(function(i, type) {
				$('a[rel="tc-'+type+'"]').click(function(e) {
					e.preventDefault();
					var id = $(this).attr('href').replace('#', '');
					if(api[type].has(id)) {
						api[type].instance(id).focus();
					}
				});
			});
		});
	});
})(jQuery);

What does the above code do? In brief:

1. It waits until the interface of the theme customization screen is fully rendered.
2. Next, it iterates through the three types of elements which we can link to.
3. For each link type it adds a click event.
4. Then it enables the default action of the links.
5. It takes the ID of the linked element from the href attribute.
6. Then, it checks if an element of the specified type and identifier exists
7. Finally, We call the focus method on the specific element which causes the defined section/panel to open.

The whole code is as follows:

function gk_theme_customizer_internal_links() {
   ?>
   <script type="text/javascript">
	(function($) {
		$(document).ready(function() {
			var api = wp.customize;
			api.bind('ready', function() {
				$(['control', 'section', 'panel']).each(function(i, type) {
					$('a[rel="tc-'+type+'"]').click(function(e) {
						e.preventDefault();
						var id = $(this).attr('href').replace('#', '');
						if(api[type].has(id)) {
							api[type].instance(id).focus();
						}
					});
				});
			});
		});
	})(jQuery);
   </script>
   <?php
}

add_action('customize_controls_print_scripts', 'gk_theme_customizer_internal_links');