Podpowiedzi zamiast opisów opcji w ekranie personalizacji motywu

W poprzednim wpisie pokazałem podstawy API JavaScript dla ekranu personalizacji motywu. Pora wykorzystać praktycznie zdobytą wiedzę i przy okazji dowiedzieć się paru nowych rzeczy – w tym wpisie opiszę jak w prosty sposób zamienić opisy kontrolek na ikonki wyświetlające podpowiedzi.

Poprzednio pisałem, że skrypty możemy dodawać do ekranu personalizacji poprzez akcje customize_preview_init i customize_controls_enqueue_scripts. Opisywany skrypt jest na tyle prosty, że nie widzę sensu osadzać go w dodatkowym pliku – dlatego warto wykorzystać trzeci sposób dodawania skryptów do ekranu personalizacji – poprzez akcję customize_controls_print_scripts:

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');

Nasz skrypt będzie działał następująco:

  1. Poczeka aż interfejs ekranu personalizacji będzie załadowany
  2. Iterując przez wszystkie kontrolki wykryje, które z nich mają opisy
  3. Pobierze te opisy do zmiennej a sam element opisu usunie
  4. Wstawi do etykiety kontrolki element i z odpowiednią ikoną i atrybutem title zawierającym opis kontrolki

Ikonkę, którą wykorzystamy bierzemy oczywiście z zestawu Dashicons.

Zacznijmy od tego jak wykryć, że interfejs ekranu personalizacji motywu jest gotowy na modyfikacje. Bazujemy tutaj na dwóch zdarzeniach:

  1. DOMContentLoaded – dzięki temu obiekt wp.customize będzie dostępny dla naszego skryptu
  2. ready – jest to zdarzenie generowane przez skrypty ekranu personalizacji

W kodzie wygląda to następująco:

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');

Pora na właściwe działania operujące na wszystkich kontrolkach:

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

Powyższy kod iteruje dzięki metodzie each po wszystkich kontrolkach i odwołując się do pola container kontrolki znajduje element opisu, który posiada klasę customize-control-description. Ponieważ element opisu jest opcjonalny, dla reszty kodu dodajemy warunek sprawdzający jego istnienie.

Następnie musimy pobrać tekst z opisu, usunąć opis i wstawić ikonkę do tytułu:

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>');
	}
});	

Warto zwrócić uwagę na spację przed elementem ikonki oraz na fakt, że zastosowałem tutaj style inline – w tym wypadku dodawanie oddzielnych styli CSS mija się z celem, ale przy bardziej rozbudowanych modyfikacjach zalecam wykorzystanie dodatkowej klasy CSS.

Cały kod skryptu prezentuje się następująco:

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');

Jako ćwiczenie można wykonać dodawanie tooltipów stylowanych w CSS np. poprzez element dfn