Customize API

Кастомайзер – це API для створення функціоналу попереднього перегляду будь-яких змін у WordPress у фронті у реальному часі без перезавантаження сторінки. Це універсальний інтерфейс для налаштування різних опцій теми: кольори, маркери, віджети, меню тощо.

Кастомайзер надає механізм керування можливостями, тобто одні налаштування можна відображати, наприклад, адміністраторам, інші редакторам, частина налаштувань для однієї сторінки, а частина для іншої.

Об’єкти кастомайзера

Існує чотири типи об’єктів кастомайзера:

• Панелі — панелі об’єднують секції. Секція може існувати поза панеллю, тобто створення панелі робиться за бажанням і вигідно, коли багато секцій і їх потрібно зібратися в панель.
• Секції (sections) — Секції поєднують елементи управління (текстове поле, радіокнопки, списки, що випадають, і так далі).
• Елементи керування (controls) — Елементи керування не можуть існувати поза секцією.
• Налаштування (settings) — Налаштування кастомайзера пов’язують елементи інтерфейсу користувача (controls) з налаштуваннями, що зберігаються в базі даних.

Наприклад, структура кастомайзера теми Twenty Seventeen така:

Використовуючи методи об’єкта WP_Customize_Manager , можна додавати/вилучати/змінювати об’єкти кастомайзера (панелі, секції, елемент керування…).

Основна робота проводиться на хуку customize_register , в функцію якого передається об’єкт WP_Customize_Manager :

add_action( 'customize_register', 'my_theme_customize_register');

function my_theme_customize_register( WP_Customize_Manager $wp_customize ) {
	// Тут робимо щось із $wp_customize - об'єктом класу WP_Customize_Manager, наприклад

	// Дії з панелями
	$wp_customize->add_panel(); // додати панель
	$wp_customize->get_panel(); // отримати панель
	$wp_customize->remove_panel(); // Видалити панель

	// Дії із секціями
	$wp_customize->add_section(); // додати секцію
	$wp_customize->get_section(); // отримати секцію
	$wp_customize->remove_section(); // Видалити секцію

	// Дії з налаштуваннями
	$wp_customize->add_setting(); // додати налаштування
	$wp_customize->get_setting(); // отримати налаштування
	$wp_customize->remove_setting(); // видалити налаштування

	// Дії з елементами управління
	$wp_customize->add_control(); // додати елемент керування
	$wp_customize->get_control(); // отримати елемент управління
	$wp_customize->remove_control(); // Видалити елемент управління
}

Налаштування

Налаштування забезпечують перегляд внесених змін, їх очищення та збереження. Налаштування “стежать” за елементами керування. Наприклад, внесли зміну (обрали колір тла сайту) – він змінився без перезавантаження сторінки. Якщо все влаштувало – публікуєте зміни, щоб усі користувачі сайту їх побачили. Перед збереженням дані очищаються.

При додаванні нової настройки доступні кілька параметрів:

$wp_customize->add_setting( 'setting_id', array(
	'type' => 'theme_mod', // Або 'option'
	'capability' => 'edit_theme_options', // Права доступ до зміни налаштувань кастомайзера.
	'theme_supports' => '', // Потрібно рідко.
	'default' => '', // Значення за промовчанням.
	'transport' => 'refresh', // Або 'postMessage'.
	'sanitize_callback' => '', // Очищення даних на стороні PHP.
	'sanitize_js_callback' => '', // Очищення даних на стороні JavaScript. Здебільшого 'to_json'.
)));

Докладніше дивіться метод WP_Customize_Manager::add_setting() .

Можливо два види налаштувань, параметр type: option(опції) та theme_mod(модифікації теми).

Опції (
option )

Зберігаються в таблиці wp_options . Назва опції в БД буде точно такою, яку ви вказали в першому параметрі (‘setting_id’).

Отримувати такі опції прийнято функцією get_option() .

Такі опції можна використовувати незалежно від активної теми. До цього типу налаштувань підходять такі дані, як “Назва сайту”, яка не залежить від того, яка тема встановлена ​​і на яку зміниться в майбутньому.

Модифікації теми (
theme_mod )

Використовуються для теми та зберігаються для кожної теми окремо. Дані зберігаються у вигляді серіалізованого масиву в таблиці wp_options , опції з назвою theme_mods_THEME_NAME. Отримувати такі опції прийнято функцією get_theme_mods() .

До цього типу налаштувань підійдуть наприклад колір заголовка статей або фон сайту. Нехай у вас була “Тема А”, ви її налаштували. Потім вирішили спробувати “Тему Б”, перейшли і також налаштували. Тепер при перемиканні тим, кожна матиме свої (різні) опції. Однак, якщо тут використовувати тип налаштувань option, то налаштування “Тема Б” переписало б налаштування “Теми А”.

Куди зберігаються проміжні установки?

Під час зміни опцій кастомайзера, але до їх публікації (застосування) WordPress зберігає поточні змінені опції в таблицю wp_posts у вигляді запису типу customize_changesetзі статусом auto-draft.

Ідентифікувати конкретну сесію зміни опцій кастомайзера можна на ім’я запису: у полі post_nameзаписується унікальний id: customize_changeset_uuid , який виглядає так: 653acb14-b389-4d19-ba98-8968c976befa .

Таким чином, отримати змінений опції (ще не опубліковані) можна отримати контент запису з ім’ям customize_changeset_uuid . У контенті, у вигляді рядка JSON зберігаються поточні змінені опції:

{
	"my_show_per_page": {
		"value": "10",
		"type": "option",
		"user_id": 5,
		"date_modified_gmt": "2019-06-21 16:28:30"
	},
	"my_main_swiper_effect": {
		"value": "flip",
		"type": "option",
		"user_id": 5,
		"date_modified_gmt": "2019-06-21 16:28:30"
	}
}

Додавання налаштувань у Customizer

Отримувати значення потрібно функцією get_theme_mod() :

echo get_theme_mod( 'my_setting_name');

PHP

<?php

add_action( 'customize_register', 'customizer_init');
add_action( 'customize_preview_init', 'customizer_js_file');
add_action( 'wp_head', 'customizer_style_tag');

function customizer_init( WP_Customize_Manager $wp_customize ){

	// як оновлювати прев'ю сайту:
	// 'refresh' - перезавантаження кадру (можна повністю відмовитися від JavaScript)
	// 'postMessage' - відправкою AJAX запиту
	$transport = 'postMessage';

	// Секція
	if( 'базова - colors') {

		// налаштування
		$setting = 'link_color';

		$wp_customize->add_setting( $setting, [
			'default' => '#000000',
			'transport' => $transport
		]);

		$wp_customize->add_control(
			new WP_Customize_Color_Control( $wp_customize, $setting, [
				'label' => 'Колір посилань',
				'section' => 'colors',
				'settings' => $setting
			] )
		);

	}

	// Секція
	if( $section = 'display_options' ){

		$wp_customize->add_section( $section, [
			'title' => 'Відображення',
			'priority' => 200, // пріоритет розташування
			'description' => 'Зовнішній вигляд сайту', // опис не обов'язковий
		]);

		// налаштування
		$setting = 'display_header';

		$wp_customize->add_setting( $setting, [
			'default' => 'true',
			'transport' => $transport
		]);

		$wp_customize->add_control( $setting, [
			'section' => $section,
			'label' => 'Відобразити заголовок?',
			'type' => 'checkbox',
		]);

		// налаштування
		$setting = 'color_scheme';

		$wp_customize->add_setting( $setting, [
			'default' => 'normal',
			'transport' => $transport
		]);

		$wp_customize->add_control( $setting, [
			'section' => $section,
			'label' => 'Колірна схема',
			'type' => 'radio',
			'choices' => [
				'normal' => 'Світла',
				'inverse' => 'Темна',
			]
		]);

		// налаштування
		$setting = 'font';

		$wp_customize->add_setting( $setting, [
			'default' => 'arial', // цей шрифт буде задіяний за умовчанням
			'type' => 'theme_mod', // використовувати get_theme_mod() для отримання налаштувань, якщо вказати 'option', то потрібно буде використовувати функцію get_option()
			'transport' => $transport
		]);

		$wp_customize->add_control( $setting, [
			'section' => 'display_options', // секція
			'label' => 'Шрифт',
			'type' => 'select', // список select select
			'choices' => [ // Список значень і лейблів випадаючого списку у вигляді асоціативного масиву
				'arial' => 'Arial',
				'courier' => 'Courier New'
			]
		]);

		// налаштування
		$setting = 'footer_copyright_text';

		$wp_customize->add_setting( $setting, [
			'default' => 'Всі права захищені',
			'sanitize_callback' => 'sanitize_text_field',
			'transport' => $transport
		]);

		$wp_customize->add_control( $setting, [
			'section' => 'display_options', // id секції
			'label' => 'Копірайт',
			'type' => 'text' // текстове поле
		]);

	}

	// секція
	if( $section = 'advanced_options' ){

		// Додаємо ще одну секцію - Налаштування фону
		$wp_customize->add_section( $section, [
			'title' => 'Налаштування фону',
			'priority' => 201,
		]);

		// налаштування
		$setting = 'bg_image';

		$wp_customize->add_setting( $setting, [
				'default' => '', // за замовчуванням - фонове зображення не встановлено
				'transport' => $transport
			]
		);

		$wp_customize->add_control(
			new WP_Customize_Image_Control( $wp_customize, $setting, [
				'label' => 'Фон сайту',
				'settings' => 'bg_image',
				'section' => 'advanced_options'
			] )
		);

		// Додамо кнопку дизайн сайту в кастомайзері для швидкого переходу до поточної настройки
		// при transport = postMessage тут можна вказати функцію,
		// яка замінюватиме частину дизайну (в такий спосіб можна не писати JS код)
		if ( isset( $wp_customize->selective_refresh ) ){

			$wp_customize->selective_refresh->add_partial( $setting, [
				'selector' => '.site-footer .inner',
				'container_inclusive' => false,
				'render_callback' => 'footer_inner_dh5theme',
				'fallback_refresh' => false, // Prevents refresh loop when document does no contain .cta-wrap selector. Це повинно бути встановлене в WP 4.7.
			]);

			// Виправимо стиль, щоб кнопку було видно
			add_action( 'wp_head', function(){
				echo '<style>.site-footer .inner .customize-partial-edit-shortcut{ margin: 10px 0 0 38px; }</style>';
			} );

		}

	}

}

function customizer_style_tag(){

	$ style = [];

	$body_styles = [];

	switch( get_theme_mod( 'font' ) ){
		case 'arial':
			$body_styles[] = 'font-family: Arial, Helvetica, sans-serif;';
			break;
		case 'courier':
			$body_styles[] = 'font-family: "Courier New", Courier;';
			break;
		default:
			$body_styles[] = 'font-family: Arial, Helvetica, sans-serif;';
			break;
	}

	if( 'inverse' === get_theme_mod( 'color_scheme' ) )
		$body_styles[] = 'background-color:#000; color:#fff;';
	else
		$body_styles[] = 'background-color:#fff; color:#000;';

	if( $bg_image = get_theme_mod( 'bg_image' ) ){
		$body_styles[] = "background-image: url('$bg_image');";
	}

	$style[] = 'body {'. implode('', $body_styles).' }';

	$style[] = 'a { color: ' . get_theme_mod('link_color'). '; }';

	if( ! get_theme_mod( 'display_header' ) )
		$style[] = '#header { display: none; }';

	echo "<style>n" . implode( "n", $ style ) . "n</style>n";
}

function customizer_js_file(){
	wp_enqueue_script( 'theme-customizer', get_stylesheet_directory_uri() . '/js/theme-customizer.js', [ 'jquery', 'customize-preview' ], null, true );
}

theme-customizer.js

jQuery(function( $ ) {

	// налаштування
	wp.customize( 'link_color', function( value ) {
		value.bind( function( newVal ) {
			$('a').css('color', newVal);
		} );
	});

	// налаштування
	wp.customize( 'display_header', function( value ) {
		value.bind( function( newVal ) {
			false === newVal ? $( '#header' ).hide() : $( '#header' ).show();
		} );
	});

	// налаштування
	wp.customize( 'color_scheme', function( value ) {
		value.bind( function( newVal ) {
			if ( 'inverse' === newVal ) {
				$( 'body' ).css({
					'background-color': '#000',
					'color' : '#fff'
				});
			}
			else {
				$( 'body' ).css({
					'background-color': '#fff',
					'color' : '#000'
				});
			}
		});
	});

	// налаштування
	var sFont;
	wp.customize( 'font', function( value ) {
		value.bind( function( newVal ) {
			switch( newVal.toString().toLowerCase() ) {
				case 'arial':
					sFont = 'Arial, Helvetica, sans-serif';
					break;
				case 'courier':
					sFont = 'Courier New, Courier';
					break;
				default:
					sFont = 'Arial, Helvetica, sans-serif';
					break;
			}
			$( 'body' ).css({
				fontFamily: sFont
			});
		});

	});

	// налаштування
	wp.customize( 'footer_copyright_text', function( value ) {
		value.bind( function( newVal ) {
			$('#copyright').text(newVal);
		});
	});

	// налаштування
	wp.customize( 'background_image', function( value ) {
		value.bind( function( newVal ) {
			0 === $.trim(newVal).length? $( 'body' ).css( 'background-image', '' ) : $( 'body' ).css( 'background-image', 'url( ' + newVal + ')' );
		});
	});

});

Методи

Методи додавання налаштувань/секцій.

$wp_customize->add_panel( $id, $args )

Додає панель.

$wp_customize->add_section( $id, $args )

Додає секцію.

$wp_customize->add_setting( $id, $args )

Додає нове налаштування/опцію. В основі роботи методу лежить клас WP_Customize_Setting() .

$id
(рядок) (обов’язковий)

Назва опції.

$args
(масив)

Параметри налаштування. Можливі ключі масиву, всі властивості класу WP_Customize_Setting{} :

• $type (рядок)
  Type of the setting.
  За замовчуванням: ‘theme_mod’
• $capability (рядок)
  Capability required for the setting.
  За замовчуванням: ‘edit_theme_options’
• $theme_supports (рядок/масив)
  Theme features required to support the panel.
  За замовчуванням: none
• $default (рядок)
  Default value for the setting.
  За замовчуванням: ”
• $transport (рядок)
  Параметри відображення попереднього перегляду змін у Налаштування тем. Можливо:
  refresh— застосовує зміни перезавантаження кадру (можна повністю відмовитися від JavaScript).
  postMessage– застосовує зміни через JavaScript.
  За замовчуванням: ‘refresh’
• $validate_callback (callable)
  Server-side validation callback for setting’s value.
  Функція отримає параметри $validity, $value, $this, дивіться хук customize_validate_(id)
  За замовчуванням: ”
• $sanitize_callback (callable)
  Callback до filtrа Customize setting value in un-slashed form.
  Функція отримає параметри $value, $this, дивіться хук customize_sanitize_(id)
  За замовчуванням: ”
• $sanitize_js_callback (callable)
  Callback для Customize PHP встановлює значення для значення, що це JSON serializable.
  Функція отримає параметри $value, $this, дивіться хук customize_sanitize_js_(id)
  За замовчуванням: ”
• $dirty (true/false)
  Whether or not setting is initially dirty when created.
  Типово: false

За замовчуванням: попереднє встановлення

$wp_customize->add_control( $id, $args )

Додає елемент керування.

$id
(WP_Customize_Control/рядок) (обов’язковий)

Об’єкт Customize Control або ID.

Рядки, які можна використовувати: text, checkbox, textarea, radio, select, dropdown-pages, і email, url, number, hidden, date.

Об’єкти, які можна використовувати як параметр $id .

Різні:

• WP_Customize_Color_Control
• WP_Customize_Background_Position_Control
• WP_Customize_Code_Editor_Control
• WP_Customize_Date_Time_Control
• WP_Customize_Theme_Control

Image:

• WP_Customize_Image_Control
• WP_Customize_Background_Image_Control
• WP_Customize_Cropped_Image_Control
• WP_Customize_Header_Image_Control
• WP_Customize_Media_Control
• WP_Customize_Upload_Control

Nav_Menu:

• WP_Customize_Nav_Menu_Control
• WP_Customize_Nav_Menu_Item_Control
• WP_Customize_Nav_Menu_Location_Control
• WP_Customize_Nav_Menu_Locations_Control
• WP_Customize_Nav_Menu_Name_Control
• WP_Customize_New_Menu_Control
• WP_Customize_Nav_Menu_Auto_Add_Control

Widget:

• WP_Widget_Area_Customize_Control
• WP_Widget_Form_Customize_Control

$args
(масив)

Масив властивостей нового об’єкта управління.

Параметр потрібно вказувати, тільки коли $id вказується рядок, якщо $id вказується об’єкт, то параметри передаються в створюваний об’єкт.

• $settings (масив)
  All settings tied to the control. If undefined. Ідентифікатори в доповіді відповідають ID ідентифікатора WP_Customize_Setting.
  За замовчуванням $setting
• $setting (рядок)
  The primary setting for control (іf there is one).
  За замовчуванням: ‘default’
• $capability (рядок)
  Capability потрібна для використання цього контролю. Normally derived from $settings.
• $priority (число)
  Order priority to load the control.
  Типово: 10
• $section (рядок)
  The section this control belongs to.
  За замовчуванням: ”
• $label (рядок)
  Label for the control.
  За замовчуванням: ”
• $description (рядок)
  Description for the control.
  За замовчуванням: ”
• $choices (масив)
  List of choices ‘radio’ або ‘select’ type controls, де значення є keys, і літери є значення.
  За замовчуванням: array()
• $input_attrs (масив)
  List of custom input attributes for control output, де attribute names є keys and values ​​are the values.
  За замовчуванням: array()
• $allow_addition (true/false)
  Show UI для отримання нового вмісту, поточно тільки використовуваного для стрільби-контролю.
  Типово: false
• $type (рядок)
  The type of the control.
  За замовчуванням: ‘text’
• $active_callback (callback)
  Active callback.

За замовчуванням: array()

$wp_customize->selective_refresh->add_partial( $id, $args )

Adds a partial.

–

Оф. дока: Theme Customization API