Релиз WordPress 4.7 принес нам множество замечательных изменений, которые включают улучшения при взаимодействии с пользователем и обновления интерфейса в настройках темы (theme customizer).
В случае если вы слышите в первые о настройке внешнего вида темы, то это возможность в админ панели WordPress (Внешний вид — Настроить) настраивать цвета, шрифты, тексты и много еще чего с помощью визуального интерфейса.
В этой статье я покажу вам, как использовать кастомайзер в теме используя все нововведения с версии WordPress 4.7
Введение в настройщик (customizer) темы
В первые кастомайзер был анонсирован в WordPress 3.4 он позволил пользователям в режиме реального времени наблюдать за изменениями которые они делают без фактического изменения сайта, и только после того как они вдоволь наиграются с настройками применить их нажав кнопку Сохранить.
Как разработчики, мы можем получить доступ к функционалу который изменяет имя сайта или фоновое изображение, и мы можем создавать свои элементы управления по средствам Theme Customizations API.
Внешняя настройка темы для разработчиков
Существует три аспекта на которые нужно обратить внимание при работе с кастомайзером. Вы должны создать поля ввода (controls) для кастомайзера, написать css и/или логику которая будет применять настройки в теме и реализовать просмотр изменений в реальном времени без перезагрузки страницы.
Шаг первый.
Перед тем как начать, давайте создадим среду с которой будем работать. Для этой статьи давайте создадим новую и очень простую тему. В действительности, она не будет рассматриваться в качестве темы которая соответствует стандартам. Я просто буду использовать index.php файл что бы набросать немного html на главной странице.
Вы можете загрузить тему которую я буду использовать, или посмотреть ее код на github.
Если вы уже заходили в настройки темы через админ панель, вы могли заметить, что по умолчанию вы можете менять название сайта, описание, а также писать CSS и это все меняется во время перезагрузки страницы. Позже мы разберемся как это изменить, и сделать изменения на ходу.
Закладываем основу
Давайте вначале подготовим почву для работы с нашим кастомайзером. Я создам файл customizer.php и подключу его в файл function.php
include('customizer.php');
customizer.php файл мы начнем с вызова экшена ( action ) customizer_register который будет содержать все секции, настройки и поля ввода.
add_action( 'customize_register', 'cd_customizer_settings' );
function cd_customizer_settings( $wp_customize ) {
}
Секции, Настройки и Поля
Секции представляют собой навигацию внутри кастомайзера. Вы наверняка уже видели несколько секций: Site Identity, Menus, Static Front Page and Additional CSS. Определяя секцию мы создаем новый пункт навигации и заполняем его полями.
Поля это елементы пользовательского интерфейса которые позволяют нам управлять настройками. Они делятся на такие типы как: input (простое поле ввода), textarea (поле для ввода большого количества текста), colorpicker (поле для выбора цвета) и т.д.
Настройки представляют собой данные которые тема принимает и использует. Мы создаем контролы что бы пользователи легко управляли данными.
Создание секции
Что бы добавить новую секцию мы используем метод add_section() объекта $wp_customize. Он принимает два аргумента: идентификатор секции и массив дополнительных опций, например позиция секции в списке секций и ее заголовок.
$wp_customize->add_section( 'cd_colors' , array(
'title' => 'Цвета',
'priority' => 30,
));
Обратите внимание, что код выше и любой другой должен быть в функции cd_customizer_settings().
Наша секция сейчас зарегистрирована, но она не будет показана пока мы не добавим в нее контрол.
Создание настроек
Настройки мы можем добавить с помощью метода add_settings() используя так же объект $wp_customizer->add_settings() метод принимает два параметра: id для настроек и массив из опций, который содержит такую информацию как настройки по умолчанию и метод передачи данных.
$wp_customize->add_setting( 'background_color' , array(
'default' => '#43C6E4',
'transport' => 'refresh',
) );
Параметр transport по умолчанию со значением refresh, я добавил его потому что мы будем его менять позже. Значение refresh означает, что когда настройки будут изменяться WordPress будет перезагружать страницу которую мы редактируем.
Создаем поле ввода (control)
Поля добавляются по аналогии с настройками, и секциями при помощи метода $wp_customizer->add_control(). Аргументы которые принимает метод более индивидуальные и сложные чем другие.
Первым аргументом мы можем передать объект контрола, в таком случаем больше не нужно передавать аргументы. Потому что экземпляр объекта будет принимать специфичные для себя параметры.
Так же мы можем передать первым аргументом идентификатор поля, в таком случае вторым будут опции, они являются обязательными.
В нашем примере мы будем использовать класс WP_Customize_Color_Control чтобы создать элемент colorpicker (выбор цвета).
$wp_customize->add_control( new WP_Customize_Color_Control( $wp_customize, 'background_color', array(
'label' => 'Цвет фона',
'section' => 'cd_colors',
'settings' => 'background_color',
)));
Первым параметром этого объекта должен быть сам объект $wp_customize, вторым идентификатор. Я стараюсь использовать id настроек которые он контролирует. Третий — это массив который содержит настройки вроде лейбла, id секции и id настроек которые он изменяет.
На данном этапе у нас есть секция с настройками и полем типа colorpicker. Поле пока ничего не делает, но настройки отображаются и значение можно поменять.
Генерация динамического CSS
Что бы заставить это работать, мы должны применить значение настроек в теме. В нашем примере мы будем менять background-color в body. И так же зададим значение фона по умолчанию.
add_action( 'wp_head', 'cd_customizer_css');
function cd_customizer_css()
{
?>
< ?php
}
Стили добавляются всем известным способом, думаю не стоит останавливаться на этом. Хочу поговорить о то как достаются настройки. Функция get_theme_mod() возвращает текущие настройки темы. Первым параметром является имя настройки, вторым это значение по умолчанию.
Функция конечно же может использоваться в коде темы чтобы менять функциональность. Дальше мы создадим поле и настройки которые будут использоваться для показа и скрытия кнопки. Мы будем использовать get_theme_mod() в файле index.php
Предварительный просмотр без перезагрузки
Изменение настроек при перезагрузке это отлично, но было бы более изящнее делать эти изменения на лету. Режим предварительного просмотра позволяет использовать JavaScript для манипуляции с настройками.
Для начала создадим customizer.js файл и подключим его.
add_action( 'customize_preview_init', 'cd_customizer' );
function cd_customizer() {
wp_enqueue_script(
'cd_customizer',
get_template_directory_uri() . '/customizer.js',
array( 'jquery','customize-preview' ),
'',
true
);
}
Добавим стандартную обертку для скрипта.
( function( $ ) {
} )( jQuery );
Теперь изменим опцию настроек transport на postMessage.
Наконец вставим следующий код в файл customizer.js.
( function( $ ) {
wp.customize( 'background_color', function( value ) {
value.bind( function( newval ) {
$( 'body' ).css( 'background-color', newval );
} );
} );
} )( jQuery );
Функция customize() принимает два параметра, имя настройки которую нужно прослушивать и анонимную функцию которая будет выполнять действия.
Изменение без перезагрузки для настроек из коробки
Возможность изменять заголовок и описание блога идет по умолчанию. Давайте настроим изменения на лету и для них. Хотя мы не определяли эти параметры и элементы управления, у нас все еще есть средства для их изменения. Мы будем использовать метод get_setting() из класса customizer, чтобы получить и изменить опции для настроек.
$wp_customize->get_setting( 'blogname' )->transport = 'postMessage'; $wp_customize->get_setting( 'blogdescription' )->transport = 'postMessage';
Вышеприведенный код должен быть добавлен в функцию cd_customizer_settings(). Финальный шаг это добавление JavaScript кода который будет изменять значения элементов.
wp.customize( 'blogname', function( value ) {
value.bind( function( newval ) {
$( '#intro h1' ).html( newval );
} );
} );
wp.customize( 'blogdescription', function( value ) {
value.bind( function( newval ) {
$( '#intro h2' ).html( newval );
} );
} );
Если все прошло гладко вы будете видеть изменение текста во время его печати.
Дополнительные примеры
В кастомайзер вы можете добавить множество настроек. Давайте разберем еще несколько примеров.
Показ и скрытие секции
Что бы управлять видимостью секции я добавлю элемент радио кнопки. Передадим два параметра в add_control() первый это обычная строка, id элемента. Второй параметр будет описывать контрол. Ниже полный код который вам нужно добавить в функцию cd_customizer_settings().
$wp_customize->add_section( 'cd_button' , array(
'title' => 'Кнопка',
'priority' => 20,
) );
$wp_customize->add_setting( 'cd_button_display' , array(
'default' => true,
'transport' => 'refresh',
) );
$wp_customize->add_control( 'cd_button_display', array(
'label' => 'Видимость кнопки',
'section' => 'cd_button',
'settings' => 'cd_button_display',
'type' => 'radio',
'choices' => array(
'show' => 'Показать',
'hide' => 'Скрыть',
),
) );
В index.php файл я добавил условие которое проверяет включен ли показ секции.
< ?php if( get_theme_mod( 'cd_button_display', 'show' ) == 'show' ) : ?> Вперед! < ?php endif ?>
Обратите внимание, что на данный момент метод обновления tranport равен значению refresh. Мы исправим это позже, а сейчас давайте займемся текстом в кнопке. Для изменения текста нужно добавить еще текстовый control.
$wp_customize->add_setting( 'cd_button_text' , array(
'default' => 'Вперед!',
'transport' => 'postMessage',
) );
$wp_customize->add_control( 'cd_button_text', array(
'label' => 'Текст кнопки',
'section' => 'cd_button',
'type' => 'text',
) );
В index.php заменим статический текст кнопки, на текст из опции при помощи get_theme_mode() и определим значение по умолчанию.
< ?php echo get_theme_mod( 'cd_button_text', 'Вперед!' ) ?>
Еще давайте позаботимся об изменении текста на лету, допишем пару строк в customizer.js.
wp.customize( 'cd_button_text', function( value ) {
value.bind( function( newval ) {
$( '#intro a' ).html( newval );
} );
} );
Выборочная перезагрузка элементов
Когда мы добавили опцию отображения кнопки, мы использовали метод перезагрузки refresh. Так как логика отображения написана в php, javascript нам не поможет. Предыдущие примеры в js отлично подходят для простых настроек, таких как заголовок сайта, описание, цвет.
В версии WP 4.5 появилась возможность перезагрузки выборочных элементов ( Selective Refresh ). Давайте применим этот метод к кнопке.
Создадим функцию cd_show_main_button() которую будем вызывать в index.php и обернем ее в контейнер.
< ?php cd_show_main_button() ?>
Сама функция точно такая же, как наш предыдущий код, но теперь ее можно использовать повторно в другом месте.
function cd_show_main_button() { if( get_theme_mod( 'cd_button_display', 'show' ) == 'show' ) { echo "" . get_theme_mod( 'cd_button_text', 'Вперед!' ) . "";
}
}
Последний шаг это сказать WordPress какой элемент нужно обновлять. Установите для свойства transport в настройке cd_button_display значение postMessage и добавьте следующий код в функцию cd_customizer_settings().
$wp_customize->selective_refresh->add_partial( 'cd_button_display', array(
'selector' => '#button-container',
'render_callback' => 'cd_show_main_button',
) );
Селектор элемента в котором мы хотим обновить все, указан во втором аргументе, и также определена функция, которая генерирует контент.
Сейчас если вы попытаетесь настроить кнопку вы увидите, что она не становится прозрачной, а потом загружается контент.
Добавление слайдера диапазона
В кастомайзере есть множество элементов управления от текста до загрузчика изображений, но бывают случаи когда этого не достаточно. В больших проектах нам может потребоваться более сложный элемент управления.
Customizer API позволяет нам создавать свои элементы ввода настроек с помощью классов. Давайте создадим слайдер для выбора диапазона, с помощью ползунка мы будем уменьшать или увеличевать значение.
Добавим код ниже в файл customizer.php:
if( class_exists( 'WP_Customize_Control' ) ) { class WP_Customize_Range extends WP_Customize_Control { public $type = 'range'; public function __construct( $manager, $id, $args = array() ) { parent::__construct( $manager, $id, $args ); $defaults = array( 'min' => 0, 'max' => 10, 'step' => 1 ); $args = wp_parse_args( $args, $defaults ); $this->min = $args['min']; $this->max = $args['max']; $this->step = $args['step']; } public function render_content() { ?> < ?php echo esc_html( $this->label ); ?> link(); ?> value="< ?php echo esc_attr( $this->value() ); ?>" oninput="jQuery(this).next('input').val( jQuery(this).val() )">
< ?php
}
}
}
Сперва нам нужно проверить существует ли WP_Customize_Control класс, далее создать класс WP_Customize_Range который будет его расширять. В нем определяем свойство $type и функцию render_content().
В render_content() мы выводим html код нашего элемента, используйте $this->value() чтобы получить текущее значение и $this->link() для отображение атрибута name в input элементе.
В конструктор я добавил несколько опций (min, max, step) которым я присваиваю значения по умолчанию если они не пришли в объект.
Для теста я создам небольшой счетчик который выводит количество фотографий на сайте. Код ниже я добавлю в index.php файл.
< ?php echo get_theme_mod( ‘cd_photocount’, 0 ) ?> фото
Теперь время создать настройки и сам контрол (control).
$wp_customize->add_setting( 'cd_photocount' , array(
'default' => 0,
'transport' => 'postMessage',
) );
$wp_customize->add_control( new WP_Customize_Range( $wp_customize, 'cd_photocount', array(
'label' => 'Количество фото',
'min' => 10,
'max' => 9999,
'step' => 10,
'section' => 'title_tagline',
) ) );
И еще немного JS для изменения без перезагрузки.
wp.customize( 'cd_photocount', function( value ) {
value.bind( function( newval ) {
$( '#photocount span' ).html( newval );
} );
} );
Теперь вы сможете создавать отличные настройки для ваших тем, тем более у вас есть хорошая основа для этого.
Автор статьи Daniel Pataki
Редакция и перевод webupblog.
