Скажімо, у вас є клієнт, компанія якого настільки велика, що має кілька підрозділів. Тепер давайте уявимо, що цей клієнт хоче, щоб кожен підрозділ мав свій власний сайт на виділеному домені. Кожен сайт повинен мати той же формат, але відмінну кольорову гаму. В цьому випадку краще використовувати настроювач WordPress (також відомий, як Theme Customization API), і я хотів би описати вам простий приклад того, як вбудувати його в тему.
До кінця цієї статті, у нас буде тема для WordPress, що містить кілька модифікацій з зрозумілими шаблонами в коді, що дозволяють розвивати її далі.
Виберемо приклад
Тема для прикладу, на яку ми будемо посилатися. Ви також можете встановити її на своєму WordPress-сайті — вона є повністю робочої і готової до використання відразу після установки.
Короткі зауваження по термінам
Терміни Customizer, Theme Modification API і Theme Customization API використовується в співтоваристві WordPress, як тотожні і взаємно замінюють. Але я думаю, що деякі відмінності між ними існують, і намагаюся їх поважати:
- Customizer — являє собою розділ інтерфейсу системи WordPress — /wp-admin/customize.php;
- Theme Modificaton API — це сімейство функцій, що створюють, зчитувальних, що змінюють і видаляють дані, якими управляє налагоджувальник;
- Theme Customization API — це сімейство функцій для видалення і додавання параметрів в настроювач.
Створіть тестовий сайт
Переконайтеся, що на вашому тестовому сайті встановлена остання версія WordPress — на момент написання статті це WordPress 4.3.2. Насправді, для прикладу нам потрібен лише останній WordPress і зазначена вище тема, встановлена і активована:
Скріншот themes.php, показує, що наша тема активована
Після того як ви встановите тему, увійдіть в панель адміністрування: ви побачите, що в розділі «Дизайн» є посилання «Налаштувати». Цей пункт існує за замовчуванням; мені не потрібно реєструвати його або оголошувати його підтримку.
Навіть якщо в нашій темі не зареєстрований жоден mod, ця посилання все одно буде корисна, тому що ядро WordPress автоматично додає в цей пункт деякі налаштування для сайту, опис сайта і т. д. «Налаштувати» — це той розділ, в якому ми будемо працювати, тому натисніть на цю посилання.
Панель настроювача
Ми потрапляємо безпосередньо в настроювач. Його ієрархічна структура має три рівня: панелі містять розділи, розділи містять параметри, а параметри — дані, які управляються через елементи керування в інтерфейсі.
Ось, як ми можемо собі це уявити:
Панель
|__ Розділ
| |__ Параметри та їх елементи управління
| |__ Параметри та їх елементи управління
|__ Розділ
| |__ Параметри та їх елементи управління
| |__ Параметри та їх елементи управління
|
Панель
|__ Розділ
| |__ Параметри та їх елементи управління
| |__ Параметри та їх елементи управління
|__ Розділ
| |__ Параметри та їх елементи управління
| |__ Параметри та їх елементи управління
Якщо це вам не зовсім зрозуміло, приділіть деякий час вивчення документації, пов’язаної з панелями, а також розділами, а також налаштуваннями і елементами їх управління.
Можна спочатку зареєструвати панель, а потім перейти за адресою /wp-admin/customizer.php, щоб подивитися, чи працює ця панель. Якщо ви не виявите цієї панелі, не турбуйтеся: панель не буде відображатися, якщо в ній ще не зареєстрований жоден параметр й елемент управління.
Панелі
Заходячи в панель настроювача, ми відразу ж бачимо зліва два розділи меню: «Властивості сайту» і «Body»:
Скріншот настроювача з двома розділами меню
«Властивості сайту» додаються в WordPress за замовчуванням, а «Body» створюється нашою темою.
Розділи
Якщо ми натискаємо на пункт «Body», то побачимо, що він містить кілька розділів: «Colors» і «Layout Options». Нагадаю, що моя тема містить код, який додає пункт «Body», розділи «Colors» і «Layout Options»:
Скріншот, на якому показані розділи, додані вами темою в настроювач
Параметри
Якщо ми зайдемо в розділ «Colors», то побачимо, що я зареєстрував декілька параметрів і елементів управління, з допомогою яких можна змінювати кольори теми. За замовчуванням я встановив значення «Помаранчевий» і «Чорний», які введені спочатку в відповідних полях:
Скріншот, на якому показано кілька параметрів, доданих темою в настроювач
Кілька слів щодо даних: WordPress зберігає і витягує параметри за допомогою сімейства функцій Theme Modification. Ми також можемо використовувати ці функції, хоча я буду використовувати в цій темі тільки одну функцію get_theme_mod().
Елементи управління
Панелі, розділи та параметри мають ієрархічну взаємозв’язок. Елементи управління теж є частиною цієї ієрархії.
Вони виводяться в інтерфейсі настроювача для кожного параметра. Щоб щось робити з модом теми, ми повинні зареєструвати для нього, як параметр, так і елемент управління для нього.
Ряд елементів управління додаються системою WordPress, в тому числі і панель вибору кольору. Більше про типи елементів управління WordPress за замовчуванням ви можете прочитати в кодексі.
Елементи WordPress за замовчуванням і як їх видалити
Давайте повернемося в самий верх панелі, а потім зайдемо в розділ «Властивості сайту». WordPress додає цю панель за замовчуванням, пропускає рівень розділів і виводить відразу декілька параметрів, таких як «Назва сайту» і «Іконка сайту»:
Скріншот параметрів, що додаються WordPress за замовчуванням
Насправді я прибрав купу панелей, розділів та параметрів, які WordPress додає за замовчуванням. Я просто наведу приклад того, як скасувати їх реєстрацію. Наш приклад теми містить клас під назвою CSST_TMD_Customizer, в якому я і ставлю для настроювача зміни цього мода теми.
Щоб видалити компоненти за замовчуванням, я підключаюся до дії customize_register і отримую доступ до об’єкта $wp_customize:
remove_control( ‘blogdescription’ );
// Видаляємо розділ для визначення статичної головної сторінки.
$wp_customize -> remove_section( ‘static_front_page’ );
// Видаляємо панель для обробки меню навігації.
$wp_customize -> remove_panel( ‘nav_menus’ );
}
?>
Я вибрав для видалення ці елементи, так як вони добре ілюструють ієрархічну структуру, про яку я говорив. Які елементи видаляти, я визначив, вивчивши код розмітки цій області настроювача. Я використовував атрибут data-customize-setting-link цього елемента керування (ви можете перевірити це на скріншоті, наведеному вище).
Щодо одного моменту прошу мене пробачити: видалення nav_menus виведе попередження в режимі налагодження. Я не зміг знайти спосіб уникнути цього.
Визначення нових панелей, розділів та параметрів
Я визначу нові панелі, розділи та параметри тільки один раз у величезному масиві, щоб інші моди теми могли використовувати його. Це дозволить нам додати ці параметри в настроювач і вивести їх з допомогою CSS.
Наша тема містить клас, який називається CSST_TMD_Theme_Mods, в якому я створюю масив панелей, розділів та параметрів, що додаються в настроювач. Давайте розберемо приклад, в якому ми додамо панель «Body», розділ «Кольору» у цю панель, а потім додамо параметр «Колір фону» в цей розділ. Іншими словами:
Панель: Body
|__ Розділ: Кольори
|__ Параметр: Колір фону з елементом управління — панель вибору кольору
По-перше, панель з ім’ям body визначається наступним чином:
esc_html__( ‘Body’, ‘csst_tmd’ ),
// Опис для цієї панелі в інтерфейсі настроювача.
‘description’ => esc_html__( ‘Моди теми розділу Body сторінки’, ‘csst_tmd’ ),
// Порядок виведення цієї панелі в настройщике.
‘priority’ => 20,
// Панель body містить кілька розділів.
‘sections’ => array(),
);
$out[‘body’] = $body;
Далі додаємо в цю панель розділ з ім’ям colors.
// Визначаємо розділ colors, який знаходиться в панелі body.
$out[‘body’][‘sections’][‘colors’] = array(
// Заголовок цього розділу в інтерфейсі настроювача.
‘title’ => esc_html__( ‘Colors’, ‘csst_tmd’ ),
// Опис цього розділу в інтерфейсі настроювача.
‘description’ => esc_html__( ‘Colors for the Page Body’, ‘csst_tmd’ ),
// Порядок виведення розділу в панелі.
‘priority’ => 10,
// Розділ colors містить ряд параметрів.
‘settings’ => array(),
);
?>
Потім в розділ colors додається параметр background_color:
‘color’,
// Текст заголовка елемента управління.
‘label’ => esc_html__( ‘Колір фону’, ‘csst_tmd’ ),
// Текст опису для елемента керування.
‘description’ => esc_html( ‘Колір фону елемента body, на екранах з альбомної орієнтацією з розширенням менше 800 пікселей.’, ‘csst_tmd’ ),
// Порядок виводу елемента керування в розділі.
‘priority’ => 10,
// Значення за замовчуванням для цього параметра.
‘default’ => ‘#000000’,
// Функція зворотного виклику для перевірки даних.
‘sanitize_callback’ => ‘sanitize_hex_color’,
‘sanitize_js_callback’ => ‘sanitize_hex_color’,
// Чи ми хочемо використовувати css цього параметра в TinyMCE?
‘tinymce_css’ => FALSE,
// Чи є цей параметр адаптивним для створення css?
‘css’ => array(
// Цей параметр задається одним правилом css. Тут ми можемо створити кілька правил.
array(
// Рядок селектора.
‘selector’ => ‘body’,
// Властивість css.
‘property’ => ‘background-color’,
// Кілька медиазапросов для цього css.
‘queries’ => array(
‘max-width’ => ‘800px’,
‘orientation’ => ‘landscape’,
),
// Кінець правила css. Тут ми можемо почати ще одне правило, щоб використовувати цей параметр border-color елемента body, або чого-небудь іншого.
),
// Кінець списку правил css (тут у нас тільки одне правило).
),
// Кінець параметра.
);
?>
Це робиться, щоб забезпечити можливість створювати багато вкладених вузлів і довге визначення масиву. У проектах з дуже великою кількістю налаштувань я часто використовую перехідні елементи, щоб уникнути проблем з продуктивністю при великій кількості циклів. Я також розбиваю масив на кілька функцій для кожної панелі, щоб зробити його більш зручним для читання і налагодження.
Але ви не зобов’язані робити це саме таким чином. Ви можете зробити можливим застосування правила тільки в тому випадку, якщо в розділі body присутні певні класи. Можна відмовитися від використання багатовимірного масиву і оголошувати свої параметри по одному.
Якщо від усіх моїх циклів у вас закрутилася голова, подивіться прекрасну тему Twenty Sixteen, яка реєструє параметри «Налаштування» взагалі без циклів. Я не вдаюся до цієї техніки, так як вважаю, що вона не дуже компактна. Наприклад, рядок color_scheme присутній в цьому файлі в 83 місцях.
Передача модів теми у настроювач
Додавання наших параметрів дуже схоже на видалення з налаштування основних параметрів. Ми повинні підключитися до customizer_register, тільки на цей раз ми додаємо елементи замість того, щоб видаляти їх. Ось фрагмент функції, яка робить це:
get_panels();
// Для кожної панелі…
foreach ( $panels as $panel_id => $panel ) {
// Додаємо панель у інтерфейс.
$wp_customize -> add_panel(
$panel_id,
array(
‘title’ => $panel[‘title’],
‘description’ => $panel[‘description’],
‘priority’ => $panel[‘priority’],
)
);
// Для кожного розділу цієї панелі, додаємо його в інтерфейс і додаємо для нього параметри.
foreach( $panel[‘sections’] as $section_id => $section ) {
// Додаємо цей розділ інтерфейс.
$wp_customize -> add_section(
$panel_id . ‘-‘ . $section_id,
array(
‘title’ => $section[‘title’],
‘description’ => $section[‘description’],
‘priority’ => $section[‘priority’],
‘panel’ => $panel_id,
)
);
// Для кожного параметра в цьому розділі, додаємо його в інтерфейс.
foreach( $section[‘settings’] as $setting_id => $setting ) {
// Розпочинаємо побудову масиву аргументів для додавання параметрів.
$setting_args = array(
‘default’ => $setting[‘default’],
‘sanitize_callback’ => $setting[‘sanitize_callback’],
‘sanitize_js_callback’ => $setting[‘sanitize_js_callback’],
);
// Реєструємо параметр.
$wp_customize -> add_setting(
$panel_id . ‘-‘ . $section_id . ‘-‘ . $setting_id,
$setting_args
);
// Розпочинаємо побудову масиву аргументів для додавання елементів керування.
$control_args = array(
‘label’ => $setting[‘label’],
‘section’ => $panel_id . ‘-‘ . $section_id,
‘type’ => $setting[‘type’],
‘description’ => $setting[‘description’],
);
// Параметр типу ‘color’ спеціальний тип елемента управління.
if( $setting[‘type’] == ‘color’ ) {
$wp_customize -> add_control(
// Він підтримується в WordPress за замовчуванням. Це панель вибору кольору.
new WP_Customize_Color_Control(
$wp_customize,
$panel_id . ‘-‘ . $section_id . ‘-‘ . $setting_id,
$control_args
)
);
// Інакше WordPress буде використовувати елемент керування за замовчуванням.
} else {
$wp_customize -> add_control(
$panel_id . ‘-‘ . $section_id . ‘-‘ . $setting_id,
$control_args
);
}
// Кінець цього параметра.
}
// Кінець цього розділу.
}
// Кінець цієї панелі.
}
}
?>
Ми обробили через цикл користувальницькі панелі, додавши кожну панель. У той час, коли ми перебуваємо в панелі, ми обробляємо через цикл розділи, додаючи розділи для цієї панелі. Коли ми перебуваємо в розділі, обробляємо через цикл параметрів для цього розділу. Кожен раз, коли ми додаємо параметр, ми також повинні додати елемент керування для цього параметра. Все дуже зациклено!
Все це простіше переварити, якщо ви подивитеся вихідний файл. Ознайомтеся з документацією кодексу WordPress за функціями, які я використовую для взаємодії з $wp_customize, таким як метод add_setting().
Поговоримо про функції попереднього перегляду
Панелі попереднього перегляду дозволяє швидко переглянути зміни для теми:
Щоб зовнішній вигляд змінювався так швидко, потрібно включити «попередній перегляд«. Ця частина не включена в нашу тему, і я її зазвичай не використовую. Існує два найпоширеніших способи підключити попередній перегляд:
1: Вбудовані стилі для елемента
Найбільш часто документований спосіб реалізації попереднього перегляду. Для зміни CSS вибраних елементів HTML використовує JavaScript:
// Оновлення кольору посилання за замовчуванням.
wp.customize( ‘mytheme_options[link_color]’, function( value ) {
value.bind( function( newval ) {
$( ‘a’ ).css( ‘color’, newval );
} );
} );
// Оновлення кольору посилання в сайдбарі.
wp.customize( ‘mytheme_options[sidebar_link_color]’, function( value ) {
value.bind( function( newval ) {
$( ‘.sidebar a’ ).css( ‘color’, newval );
} );
} );
Оновлюючи колір посилань розділу body під час перегляду, я випадково прибрав спеціальні стилі для посилань у сайдбарі. Це проблема, і у мене немає рішення для неї.
Ще одна проблема цього підходу полягає в медиазапросах. Нагадаю, що діапазон застосування модів нашої теми поширюється на конкретні медиазапросы. Щоб передати цю логіку через JS знадобилося б багато роботи.
2: Вбудовані блоки стилів
Якщо ви покопаетесь в темі Twenty П’ятнадцять, то побачите, що замість зміни стилів елемента в ній оновлюється блок вбудованих стилів, який генерується настроювачем. Ви можете взяти відправні матеріали для такого підходу звідси.
Я спробував розібратися в цьому і перекодувати цей ресурс у щось, що б я дійсно міг зрозуміти і підтримувати самостійно. І у мене виникли труднощі. Тут я знайшов деякі дії, але насправді цей тікет не допоміг зробити так, щоб мені подобалося, як виглядає попередній перегляд.
Якщо сотні сайтів клієнтів використовують одну тему, то ми повинні бути обережними при її відновленні. Напевно, для цього буде потрібно візуальне регрессионное тестування, щоб зробити все правильно.
Стилі для Front End
Ми зробили все, щоб створити інтерфейс настроювача, і він працює. Можна використовувати ці значення в будь-якому місці: CSS для wp_head(), класах розділу body, редактора TinyMCE. Ми також можемо передати значення JS.
Давайте використаємо їх для виведення CSS. У нас вже є кілька параметрів для управління кольором шрифту і колір фону для елемента body, так що ми можемо почати з цього.
Тема містить клас CSST_TMD_Inline_Styles, який обробляє в циклі всі параметри і виводить відповідний CSS-код за допомогою функції add_inline_style().
Це означає, що власні стилі додаються в чергу завантаження в залежності від стилів теми. Ось як це виглядає у дії:
get_inline_styles( ‘unwrapped’, ‘front_end’ );
// Приєднуємо стилі настроювача.
wp_add_inline_style( CSST_TMD, $styles );
}
…
?>
Ми викликаємо метод $this -> get_inline_styles(). Цей метод відповідає за обробку в циклі всіх налаштувань настроювача і висновок гігантського блоку CSS:
$setting ) {
// Захоплюємо css для цього параметра.
$css_rules = $setting[‘css’];
// Захоплюємо поточне значення для цього параметра.
$value = $setting[‘value’];
// Для кожного правила css…
foreach( $css_rules as $css_rule ) {
// Селектор css.
$selector = $css_rule[‘selector’];
// Властивість css.
$property = $css_rule[‘property’];
// Задаємо з цього CSS.
$rule_string = «$selector { $property : $value ; }»;
// Містить це правило медиазапросы?
if( isset( $css_rule[‘queries’] ) ) {
…
foreach( $queries as $query_key => $query_value ) {
…
// Додаємо ключ і значення міді-запиту.
$query .= «( $query_key : $query_value )»;
// Якщо це не останній запит, додаємо оператор «and».
if( $i
Блок вбудованих стилів побудований. На даний момент це один рядок, у якій кожен селектор CSS і кожна властивість CSS визначено в масиві параметрів. Значення CSS — це раніше збережені через настроювач дані, які ми маємо.
Інші застосування параметрів настроювача
Наведений вище приклад є найважливішим варіантом застосування кастомайзера. Але далеко не єдиним. У нас також є клас, CSST_TMD_Body_Classes, в якому ми додаємо кожен параметр як клас розділу body — і в wp-admin, і в front end. Це може бути корисно, якщо у нас є параметр зсуву сайдбара вправо або вліво.
Клас CSST_TMD_Tiny_MCE служить для визначення стилів редактора записів в wp-admin, тому в ньому будуть використовуватися ті ж кольори, що задані через параметр настроювача.
Ресурси і наступні кроки
Я настійно рекомендую вам стежити за обговоренням теми настроювача в блозі Make. В недавній статті там зазначається, що продуктивність front-end — це проблемна область настроювача. Я згоден з цим, але продуктивність у Chrome і Firefox може бути істотно поліпшена. Також у статті згадується про можливості використання ревізій для настроювача, подібно ревізіям для записів.
Я бачив кілька збірників призначених для користувача елементів управління, розміщених на GitHub. Цей містить кілька корисних і складних елементів управління. А ось ще один.
Якщо ви можете виконати все, що було описано в цій статті, вам логічно буде зробити подальші кроки:
- Додати інші параметри в масив;
- Зробити синтаксис медиазапросов більш надійним, щоб ви могли реєструвати медиазапросы з допомогою специфічних логічних операторів;
- Поліпшити шаблони JavaScript для користувацьких типів елементів управління.
Якщо ви знайшли цю статтю занадто складною, я буду радий відповісти на ваші питання в коментарях.
Переклад статті «Getting Started with the WordPress Customizer» був підготовлений дружною командою проекту Сайтостроение від А до Я.
