Theme Customizer WordPress : Исчерпывающее руководство разработчика

Уроки5 комментариев

Это учебное пособие расскажет в деталях как для вашей темы в WordPress подключить Theme Customizer(далее настройщик тем).

Настройщик тем был анонсирован в WordPress в версии 3.4. Он позволяет администратору в среде редактирования опробовать опции темы до того, как они будут применены к рабочему сайту. В этом руководстве мы разберем, каким образом добавить эту функцию к теме.

Тему WordPress, которую мы используем для этого примера, будет Responsive версии 1.8.0.1, автор Emil Uzelac. В данный момент это одна из популярных тем на WordPress.org, что должно послужить нам надежной отправной точкой. Однако, вы вольны самостоятельно использовать любую понравившуюся вам тему.

Обратите внимание: Существует несколько путей подключить настройщик тем и сохранить настройки модификации. Это руководство будет рассматривать метод theme_mod. Если вы не знаете, что это означает, не беда. Вам не нужно понимать назначение различных методов, если вы придерживаетесь данного руководства.

1. Добавляем страницу настройщика темы в меню админ-панели.

Сначала откроем файл темы functions.php и добавим следующий код. Не имеет критического значения, куда конкретно в самом файле мы поместим код, пока он не внутри другой функции.

Здесь мы создали заголовок новой функции “example_customizer_menu” и подключили ее к перехватчику действий “admin_menu”. Эта функция содержит всего одну строку и вызывает функцию add_theme_page() для добавления страниц в админ-панель WordPress. Она имеет четыре обязательных параметра:

функция: add_theme_page( $page_title, $menu_title, $capability, $menu_slug, $function );
$page_title строка Это будет заголовок новой страницы. Однако, страница настройщика не имеет заголовка, так что по большому счету этот параметр можно игнорировать.
$menu_title строка Это будет текст нового пункта в меню «Внешний вид».
$capability строка Это гарантирует, что пользователь обладает нужным уровнем привилегий для доступа к настройщику.
(Для более детальной информации по пользователям WordPress [предложение обрывается — прим. перев.]
$menu_slug строка Это уникальный слаг (ссылка) меню для этой страницы

Обратите внимание: Если вы создаете тему для публичного пользования, для параметров $page_title и $menu_title должна иметься возможность их перевода на другие языки. Более подробную информацию по локализации вы сможете найти на странице правил локализации I18n for WordPress.

Теперь, если мы вернемся назад в админ-панель WordPress, в меню «Appearance»  будет доступна новая страница, озаглавленная «Customize». Нажав «Appearance > Customize», мы откроем новую страницу настройщика тем, которую только что создали. На панели с левой стороы экрана мы обнаружим, что там уже отображаются четыре секции настройки. «Заголовок сайта и стока тэгов», как и «Статичная домашняя страница» добавлены в настройщик автоматически. Разделы «Цвета» и «Фоновый рисунок» добавлены потому, что эта тема поддерживает опцию настраиваемого фонового изображения, встроенную в ядро WordPress. В следующей главе мы будем добавлять уже свои собственные секции.

2. Добавляем новую секцию в настройщик

Для создания нашей собственной секции настроек поместим следующий код в файл functions.php сразу за тем кодом, который мы только что добавили ранее (и снова, расположение не играет большой роли, просто удобнее помещать код в упорядоченной последовательности).

Обратите внимание: Вы не сможете увидеть секцию настроек, пока она не будет содержать хотя бы одну опцию.

Мы подключили нашу функцию к перехватчику действий “customize_register” чтобы обеспечить ее запуск в нужное время. Нашей функции передается объект $wp_customize и мы имеем возможность использовать его методы для добавления секций, опций и элементы управления в настройщик тем. Начнем с добавления секции, используя метод add_section(). Этот метод принимает два параметра.

Метод: add_section( $id, $args );
$id строка Уникальный идентификатор секции
$args массив Массив аргументов, передаваемых функции add_section().

Массив $args позволяет нам указать некоторое количество деталей касательно секции настроек, которую мы создаем.

Массив: $args
title строка Заголовок секции настроек
description строка Необязательный параметр. Описание секции настроек. Это отображается только как всплывающая подсказка, когда указатель мыши находится над заголовком раздела.
priority целое число Необязательный параметр. Определяет порядок, в котором секция будет отображаться. Меньшие номера идут первыми. По умолчанию: 10.
capability строка Необязательный параметр. В зависимости от уровня привилегий пользователя секция отображается или скрывается.
theme_supports строка Необязательный параметр. В зависимости от того, поддерживает ли тема конкретную особенность, секция отображается или скрывается

В нашем примере выше мы не использовали необязательные аргументы «capability» или «theme_supports«. Однако были использованы необязательные аргументы «description» и «priority» , так что вы можете прочувствовать, как они функционируют. Продолжайте дальше и изменяйте их значения для понимания их работы. В следующей главе мы создадим опцию для новой секции.

3. Добавляем новую опцию

Теперь добавим новую опцию в только что созданную секцию настроек. Это процесс, состоящий из двух частей. Во первых, мы должны зарегистрировать опцию. Во-вторых, мы должны создать элемент управления, отображающий опцию. Начнем с создания текстовой опции, используемой для отображения информации об авторских правах в подвале темы.

3.1. Регистрируем опцию

Опции регистрируются с помощью метода add_setting(). Мы его поставим сразу после вызова add_setting() и точно перед закрытием фигурных скобок функции example_customizer().

Обратите внимание: Вы не сможете увидеть эту новую опцию, пока она не будет иметь свой собственный элемент управления. Не переживайте, мы ей присвоим элемент управления чуть позже.

Как и метод add_section(), метод add_setting() принимает два параметра, идентификатор и массив аргументов.

Метод: add_setting( $id, $args )
$id строка Уникальный идентификатор (ID) опции.
$args массив Массив аргументов, передаваемых функции add_setting()

… а здесь аргументы, передаваемые в массиве.

Массив: $args
default строка Необязательный параметр. Значение опции по умолчанию, если значение не было уже сохранено. По умолчанию: пустая строка.
type строка Необязательный параметр. Определяет, как опция будет сохранена. По умолчанию: theme_mod.
capability строка Необязательный параметр. В зависимости от уровня привилегий пользователя, опция отображается или скрывается. По умолчанию: edit_theme_options
theme_supports строка Необязательный параметр. В зависимости от того, поддерживает ли тема конкретную особенность, секция отображается или скрывается. По умолчанию: пустая строка
transport строка Необязательный параметр. Определяет, как новая опция будет передана предварительному просмотру. По умолчанию: refresh.
sanitize_callback строка Необязательный параметр. Имя функции, которая будет вызвана для проверки и корректировки входных данных перед сохранением в базу данных (БД). По умолчанию: пустая строка.
sanitize_js_callback строка Необязательный параметр. Имя функции, которая будет вызвана для проверки и корректировки данных, поступающих из БД в настройщик тем. По умолчанию: пустая строка.

Вы, вероятно, обратили внимание на то, что в коде выше мы задействуем только аргумент «default». Большинство других аргументов имеют приемлемые значения по умолчанию, так что мы не будем беспокоиться и добавлять их в наш вызов метода add_setting(). Некоторые аргументы заслуживают более пристального на них внимания, пока мы не пошли дальше.

Во-первых, аргумент «sanitize_callback» используется для проверки введенных  данных перед тем, как сохранить их в БД. Ради упрощения я пока не задействовал этот аргумент, но вернусь к нему в дальнейшем в этом руководстве. Я полагаю, что проверке и корректировке данных часто не уделяется должного внимания и я хочу это исправить.

Во-вторых, «sanitize_js_callback» может быть не тем, что вы, возможно, ожидаете. Обычно ведется речь о проверке и корректировке данных, когда что-то не то с введенными пользователем данными, перед сохранением в БД. Однако функция «sanitize_js_callback» вызывается для проверки и корректировки данных, уже сохраненных в БД в момент их передачи в настройщик тем. Единственный случай, в котором, по-моему, оправдан вызов этой функции — добавление «#» в начало шестнадцатиричного числа в случае, когда оно сохранено в БД без этого знака.

В третьих, заслуживает также внимание и аргумент «transport«. Когда значение нашей опции изменено в настройщике, существует два пути обновления живого предварительного просмотра для отражения изменений. Значение «refresh» обновляет фрейм, отображающий предварительный просмотр. Это происходит автоматически. Однако, если та небольшая задержка при обновлении страницы для вас неприемлема, вы можете использовать значение «postMessage«. Это передает новое значение измененной опции в предварительный просмотр посредством AJAX и обновлять страницу не требуется. Для использования «postMessage» вам будет нужно написать свои собственные скрипты для обработки данных, передаваемых AJAX в предварительный просмотр. Ради упрощения мы пока будем использовать значение аргумента «transport» по умолчанию «refresh» и вернемся к этому вопросу и к использованию «postMessage» ниже в нашем руководстве.

Ну вот, это мы прошли, теперь давайте присвоим нашей опции элемент управления.

3.2 Создаем элемент управления

Элементы управления это просто интерфейс, используемый для изменения значений опций. Каждая опция должна иметь элемент управления для того, чтобы быть отображаемой в настройщике тем. Элемент управления добавляется через использование метода add_control(). Как и наши предыдущие методы, он принимает два параметра. Первый — это идентификатор (ID) элемента управления. Значение должно быть равным значению ID опции, которой элемент управления принадлежит. Так как наша опция выше имела ID «textbox», элемент управления также должен иметь «textbox». Как и ранее, второй параметр — это массив с аргументами. Мы расположим наш вызов метода add_control() сразу после вызова функции add_setting() и точно перед закрытием фигурной скобки функции example_customizer().

Теперь мы, наконец, должны увидеть секцию и опцию в настройщике тем!

wordpress-theme-customizer-example-settings-section-650x370

Как и предыдущие методы, метод add_control() принимает два параметра, ID и массив аргументов.

метод: add_control( $id, $args )
$id строка Значение ID должно быть равным значению ID опции, которой элемент управления принадлежит.
$args массив Массив с аргументами, передаваемыми в функцию add_control()

Вот аргументы, которые можно помещать в массив $args.

Массив: $args
label строка Текст названия опции.
section строка ID секции, где расположена опция.
type строка Необязательный параметр. Тип ввода, используемый опцией. По умолчанию: текст.
choices массив Если опция использует список для выбора или радио-кнопки, аргумент «choices» определяет список значений для отображения.
priority целое число Необязательный параметр. Определяет порядок, в котором опции отображаются в секции. Меньший номер идет первым. По умолчанию: 10

Суть большинства этих аргументов довольно понятна. Как вы могли заметить, мы задействовали только первые три в примере выше. Мы будем работать с аргументом «choices» чуть позже, когда будем добавлять списки или радио-кнопки. Аргумент «priority» также не был задействован в примере, так как мы имеем всего одну опцию. Указание priority никак не повлияет на порядок опций, пока их не станет больше одной. Мы вернемся к этому в следующей главе, когда будем добавлять другие типы опций в настройщик тем.

4. Доступ к сохраненной опции из темы.

Наконец-то! Теперь-то мы можем использовать новую опцию в нашей теме. Как было упомянуто ранее, мы будем использовать эту опцию для управления текстом об авторских правах в футере темы. Текущее уведомление об авторских правах отображается следующей строкой кода в файле footer.php темы:

Мы убираем эту строку и меняем ее на следующую:

Функция get_theme_mod() принимает два параметра.

Функция: get_theme_mod( $name, $default )
$name строка Имя опции для получения. Имя опции — это любая строка, которую вы указали, как ID опции при ее создании.
$default строка Необязательный параметр. Строка, содержащая текст по умолчанию, который должен отображаться, если значение опции не было сохранено.

Вы заметили, что первый параметр в коде выше такой же, как и ID опции, что мы создали ранее. Вот так WordPress знает, какое значение брать из БД. Второй параметр — это просто альтернативный текст для отображения, в случае, если опция «copyright_textbox» еще не была сохранена.

5. Дополнительные типы элементов управления

Мы уже создали опцию типа textbox и добавили ее в нашу тему, но это только начало. Есть еще множество других стандартных типов элементов управления, предоставляемых WordPress.

5.1 Флажок

Эту опцию мы будем использовать для полного скрытия информации об авторских правах. Во-первых, мы создадим другую опцию с помощью добавления следующего кода сразу после текстового элемента, который мы создали выше.

Обратите внимание, что, в отличии от ранее созданной текстовой опции, нам не нужен массив аргументов, так как не нужно значение опции по умолчанию. Следующим действием мы добавим код для элемента управления «флажок» ниже только что созданной нами опции.

Единственная разница между этим элементом управления и текстовым это свойство «type»добавленное нами в массив аргументов. Это сообщает WordPress, что мы хотим, чтобы отображался флажок, нежели текстовое поле по умолчанию. Теперь давайте используем это в теме для скрытия текста авторских прав, если флажок отмечен. Вот код, выводящий информацию об авторских правах из файла темы footer.php

Давайте проверим опцию hide_copyright и будем отображать текст авторских прав, если флажок снят. Настройщик тем хранит значение флажка, как число 1, если он помечен и пустая строка, если он снят. Поэтому мы добавим условие «if» для проверки перед отображением текста, снята ли галочка. Исходный код выше мы заменим следующим:

 5.2 Радио-кнопки

Для демонстрации использования радио-кнопок мы создадим новую опцию настройщика для указания расположения логотипа, слева, справа или по центру. Сначала давайте создадим опцию и элемент управления добавлением следующего блока кода сразу после элемента управления «hide_copyright».

Вы уже заметили, что, как и в случае с текстовым полем, мы указали значение по умолчанию в параметрах add_setting(), просто на случай, если пока ничего не выбрано. Важное отличие радио-кнопок от вышеописанных типов ввода данных заключается в добавлении массива «choices«, который позволяет указать, какие варианты выбора должны быть доступны. Первая часть каждого элемента ассоциативного массива — это имя элемента радио-кнопки. Это также имя, которое мы используем для извлечения соответствующих данных из БД. Вторая часть каждого элемента массива — это визуальное название, которое будет прикреплено к радио-кнопке.

Для использования этой новой функции в теме мы добавим следующий код перед перехватчиком действий «wp_head» в файле темы header.php.

Это должно быть довольно просто для понимания. Код выше сначала получает значение «logo placement » из БД и присваивает его переменной. Затем, если расположение лого не является пустым значением, оно прогоняется через возможные варианты выбора и прописывает стили для соответствующего размещения лого. Заметьте, что, если позиция лого — слева, то не создается CSS, поскольку тема уже отображает лого слева.

5.3 Списки выбора

Процедура создания списка выбора почти точно такая же, как создание радио-кнопок. Для иллюстрации мы добавим список выбора, который позволит нам заменять значение по умолчанию сообщения в подвале «powered by» на что-нибудь более веселое. Добавим следующий код сразу после опции радио-кнопок и ее элемента управления.

Это было просто! Теперь у нас новый список выбора в настройщике темы и мы готовы его использовать в теме. Начнем с удаления старого сообщения «powered by» из файла footer.php, удалив эти строки:

На их место добавим эту единственную строчку кода:

Если значение «powered by» не было сохранено, в подвале отобразится «Этот сайт работает благодаря WordPress». Однако, если значение было сохранено, «WordPress» заменится на этот забавный выбор из списка.

6. Проверка и корректировка данных

Выше я упоминал, что для упрощения я не хотел бы сразу с самого начала бросаться в такую сложную тему, как проверка данных. Однако, я не хочу оставить у вас впечатление, что я ее не касаюсь, потому что она неважна. Уж так и быть, я выделяю этому целую главу данного руководства. Итак, да, я действительно считаю, что это очень важно. Однако, я не буду залезать во все тонкости и причины, почему это так важно, или описывать последствия невыполнения этой проверки. Я просто скажу так: никогда не доверяйте введенным пользователем данным!

6.01 Проверка текстового ввода

Хорошо, теперь мы займемся кодом. Функции проверки и корректировки данных добавлены использованием аргумента «sanitize_callback» при создании новой опции. Помните изначальный текстовый ввод, добавленный нами в начале руководства для изменения текста об авторских правах в подвале? Вот как это выглядело:

Теперь нам просто надо добавить аргумент «sanitize_callback«в массив аргументов, как показано здесь:

Когда бы ни сохранялась величина «copyright_textbox«, сначала вызывается функция «example_sanitise_text» и ей передается значение, которое должно быть сохранено. Мы должны просто проверить перед окончательным сохранением, допустимо ли это значение, можно ли его сохранять. В этом случае мы хотим сохранить простую строку. Допустим, мы не против, если пользователь вводит немного HTML в текст об авторских правах, но мы определенно не желаем, чтобы там оказались тэги скрипта. И если все-таки пользователь добавил какие-то HTML-тэги в текст, то надо бы проверить на предмет их корректного закрытия. Учитывая все это, получаем коллбэк-функцию проверки и корректировки, которую мы можем использовать для достижения всего вышеописанного:

Функция force_balance_tags() закрывает все незакрытые тэги, а функция wp_kses_post() контролирует, чтобы только безопасные тэги попали в стандартную процедуру записи в БД в WordPress. Эти функции встроены в WordPress и описаны в его документации.

6.02 Проверка флажка

Я продемонстрировал как добавить коллбэк-проверку для текстового ввода в предыдущем разделе, поэтому не буду еще раз повторять то же самое. Вместо этого я займусь непосредственно функцией проверки и корректировки, которая и будет использована для проверки флажка.

Настройщик использует значение 1, если флажок поставлен, и пустое значение, если он снят. Другими словами, есть всего два значения, которые наша функция должна позволять сохранять: 1 и пустая строка. Вот как это все должно выглядеть:

Если значение ввода равно 1 (означающий поставленный флажок), функция возвращает 1. Если значение — что-либо другое, она возвращает пустую строку. Это предотвращает сохранение чего-нибудь опасного в базу данных, способного что-то испортить.

6.03 Проверка радио-кнопок и списков выбора.

Проверка множественного выбора, как радио-кнопки и списки выбора немного более сложней, поскольку каждый раз, когда мы используем множественный выбор, разрешенные значения разные. Например, для проверки опции «Logo placement» (расположение логотипа), которую мы добавили ранее, нам надо удостовериться, что ввод находится среди вот этих значений: «left», «right», «center». Однако наша опция «Powered by» должна принимать только значения «WordPress», «Хомякам», «Реактивному топливу», или «Ядерной энергии» в качестве разрешенных. По этой причине мы должны создать отдельную коллбэк-функцию для каждого поля множественного выбора. Как я говорил ранее, я уже объяснял, как добавлять функцию проверки, поэтому перехожу непосредственно к самим функциям, которые мы будем использовать для проверки наших множественных выборов.

Давайте начнем с радио-кнопок «Logo placement». Для упрощения мы используем такой же массив, что мы создали при добавлении элемента управления «Logo placement», для того, чтобы проверить, соответствует ли ввод ожидаемым данным.

Первая половина этой функции проверки хранит изначальные значения выбора положения лого в массиве. Вторая половина проверяет, подходит ли введенное значение, сравнивая его с этим массивом с помощью функции языка PHP array_key_exists(). Если ввод соответствует одному из элементов массива, мы возвращаем ввод, как есть. Однако, если введенные данные не равны ни одному из существующих элементов массива, возвращается пустая строка. Это предотвращает сохранение в БД значений, которые не входят в допустимые в нашем конкретном случае.

Функция проверки для списка выбора работает практически так же. Единственное отличие в том, что мы заменили массив значений расположения лого на массив значений из нашего списка «Powered by».

…и это все о проверке и корректировке всех стандартных элементов ввода, доступных в настройщике тем WordPress.

7. Специальные типы элементов управления

В дополнение к основным элементам управления, о которых шла речь выше, в WordPress доступны и некоторые специальные. Поскольку мы уже рассказали, как использовать функцию get_theme_mod() для извлечения сохраненных в БД опций, я не буду удлиннять это руководство, рассказывая, как ее использовать для каждого типа элементов управления. Я просто покажу, как создавать элементы, и предоставлю вам право самим решать, как вы будете использовать сохраненные значения в вашей теме.

7.01 Выпадающий список страниц

Создание выпадающего списка страниц довольно просто. Мы можем начать с того же кода, что мы использовали для создания флажка и просто изменим название опции, проверочную коллбэк-функцию и тип элемента управления.

Это был просто! Заметьте, что элементу массива «type» присвоено значение «dropdown-pages», что автоматически создаст список выбора в настройщике тем, позволяя нам выбирать страницу. Значение, сохраненное в БД для этой опции — это ID страницы. Поэтому мы должны убедиться, что введенные данные — это целое число, прежде, чем сохранять в БД. Вот проверочная функция, которую мы будем здесь использовать:

7.02 элемент Выбора цвета

Вот здесь мы начинаем разбирать более интересные типы элементов управления. Добавления опции не изменилось, но добавления элемента управления слегка другое. Начнем с добавления опции.

Выглядит знакомо, правда? Единственная разница используемой нами проверочной коллбэк-функции. WordPress имеет встроенную функцию для проверки шестнадцатиричных кодов цветов, которые и являются типом выходного значения, которое создает наш элемент выбора цвета. Также мы установим значения цвета по умлочанию — черный (#000000).

Теперь посмотрим на код, используемый для создания элемента выбора цвета.

Элемент выбора цвета был встроен в WordPress с использованием объектно ориентированного языка PHP, поэтому формат вызова add_control() отличается от ранее показанных способов. Обратите внимание на строку с «new WP_Customize_Color_Control«. Это говорит WordPress, что мы хотим новый экземпляр класса WP_Customize_Color_Control. Если вы не знаете, что все это значит, не переживайте. Вы не обязаны знать объектно-ориентированное программирование для работы с настройщиком тем, поэтому я не буду здесь это объяснять.

The WP_Customize_Color_Control принимает три параметра. Первый $wp_customize всегда тот же самый, поэтому я не буду объяснять по нему. Просто убедитесь, что используете его. Второй — это ID опции. Это должен быть такой же ID, как при вызове функции add_setting().Третий — это массив аргументов, разобранный в следующей таблице:

массив: $args
label строка Заголовок для этой опции
section строка Секция, в которую данная опция будет добавлена
settings строка ID опции, использованной ранее в вызове add_control() и при вызове add_setting()

Вот и все. Да не устанет WordPress от работы, создавая нам элемент выбора цвета.

7.03 Загрузка файлов

Есть еще один встроенный в WordPress класс, который позволит нам создать опцию загрузки файлов в настройщике тем. WordPress сам ограничивает типы файлов, которые могут быть загружены, поэтому на этот раз я пропущу функцию проверки и корректировки.

Так же, как в в случае выбора цвета, элемент управления загрузки файлов отображается созданием нового экземпляра класса. На этот раз класс называется WP_Customize_Upload_Control. Хорошо, что он принимает такие же аргументы, что и элемент выбора цвета, так что тут все просто. Все, что мы должны поменять — это ID опции.

7.04 Загрузка изображений

Класс загрузки изображения — это наследник класса загрузки фалов и вызывается точно так же. Мы меняем только WP_Customize_Upload_Control на WP_Customize_Image_Control и используем новый ID опции.

Еще раз, WordPress автоматически ограничивает типы файлов, которые могут быть загружены, но загрузка в данном случае не ограничена только картинками. Вы можете создать проверочную функцию для загрузки только лишь картинок. Но, поскольку это руководство по настройщику тем, а не по проверке и коррекции данных, я оставлю эту тему нераскрытой.

8. Создание пользовательских элементов управления

Итак, мы рассказали все о встроенных в WordPress элементах управления, а что если мы хотим создать дополнительные элементы? Отто написал отличную статью по созданию пользовательских элементов управления, поэтому этот раздел будет основан на ней.

Вы, возможно, заметили ранее, что тип ввода текстовой области (textarea) не входит во встроенные в WordPress типы. Здесь мы и создадим пользовательский элемент управления для использования типов ввода textareas в настройщике тем.

Для создания нашего собственного элемента управления нам понадобится расширить WP_Customize_Control class и переопределить функцию render_content() для вывода нашего нового элемента управления. Если вы знакомы с объектно ориентированным языком PHP, это для вас будет понятно, если нет — ничего, просто следуйте за мной. Очень сложно не будет.

Помещаем наш класс внутри функции example_customizer(), которую мы создали в начале этого руководства. Эту функцию мы использовали для настройки и добавления всех опций в настройщик тем. Чтобы класс работал, как надо, он должен быть определен в пределах этой функции:

Обратите внимание: существует другой путь определения класса вне этой функции, но я оставлю это вам для самостоятельного изучения.

Для того, чтобы создать наш новый класс текстовой области, мы добавим следующий кусок кода в только что упомянутую функцию:

Смотрите, функция render_content() отображает нашу текстовую область вместе с названием этого поля. Класс WP_Customize_Control, от которого мы наследовали Example_Customize_Textarea_Control, сделает всю остальную работу за нас сам.

Теперь мы можем добавить опцию в наш настройщик тем, которая использует класс текстовой области, что мы только что создали. Для упрощения я не буду описывать добавление таких вещей, как порядок отображения, коллбэк-функцию и т.д. Это все описано ранее. Сам код будет почти таким же, как тот, что мы использовали для элементов загрузки файлов и изображений.

Единственные изменения

  1. ID опции был изменен на «textarea»
  2. Имя вызываемого класса изменено на «Example_Customize_Textarea_Control»
  3. Название было изменено на «Textarea»

Это должно дать вам хорошую почву для того, чтобы создавать свои классы для расширения настройщика тем.

9. добавление новых опций в существующие секции

Может быть, вы хотите добавить новую опцию в секцию, которая уже существует. Например, из-за того, что тема Responsive поддерживает свойство WordPress, позволяющее менять фон (background), секция настроек «Colors» («Цвета») создана автоматически и туда помещены опции «Background Color». Давайте добавим еще одну опцию в секцию «Colors» и назовем ее «Font Color» («Цвет шрифта»). Первое, что мы должны сделать — это найти, какое у секции ID, чтобы мы могли добавить к ней новую опцию. Секции добавляемые автоматически самим WordPress-ом, определены в файле wp-includes/class-wp-customize-manager.php. Посмотрев его содержимое, мы найдем, что ID секции «Colors» является «colors».

Так как мы уже создавали опцию цвета ранее, просто скопируем код, использованный нами ранее в работе с опцией цвета и сделаем некоторые изменения.

Вот изменения:

  1. Изменили предыдущее значение ID «color-setting» на «font-color» во всех трех местах, где это присутствует.
  2. Поменяли цвет по умолчанию.
  3. Поменяли название.
  4. И, наконец, изменили свойство секции на «colors» для того, чтобы опция добавилась именно в существующую секцию «Colors».

Мы уже рассказывали, как использовать сохраненные опции в теме, поэтому процедуру применения сохраненного цвета шрифта к теме я оставляю вам, как домашнее задание.

10. Использование AJAX для обновления предварительного просмотра

Вернемся к рассмотрению параметра «transport» и его значения «postMessage«, которые мы кратко рассмотрели в главе 3. Добавим новую опцию для изменения цвета фона области содержимого на домашней странице. Во-первых, мы добавим еще один выбор цвета к секции «Colors» настройщика тем:

Единственное отличие между этим кодом и кодом, что мы использовали ранее для создания элемента выбора цвета, это название/ID и добавление аргумента «transport«. Теперь, когда мы установили метод «transport«, мы должны написать функцию для осуществления обновлений через AJAX. Эта функция будет прикреплена к перехватчику действий wp_footer. Для осуществления этого добавим следующий код внутрь функции example_customizer(), которую мы создали в самом начале.

Этот код проверяет, имеет ли пользователь административные пава и используется ли настройщик тем. Если обе проверки этих условий возвращают «true», тогда функция example_customize_preview() прикрепляется к wp_footer. Последний аргумент (21) — это просто приоритет, который дан этой функции. Он должен быть установлен значением больше 20 для правильной работы.

И, наконец, создаем функцию example_customize_preview() для добавления Javascript, который будет управлять обновлением через AJAX.

Эта функция просто добавляет кусок кода javascript в подвал темы (и только тогда насройщик тем и используется). Она может служить вам базой для управления почти любыми типами данных настройщика, проходящих через AJAX. Код вверху делает в основном две вещи. Первая: он получает значение поля настройщика, когда оно изменяется (в этом примере это значение «featured-background», как можно увидеть в пятой строке). Вторая: он что-то делает с этим значением. Так как мы используем элемент ввода цвета, мы устанавливаем эту измененную величину цвета, как цвет фона элемента #featured (строка 7), используя функцию css() jQuery.

11. Использование AJAX для предустановленных опций

А что если мы захотим изменить параметр transport у встроенной опции? Такая возможность тоже есть. Для демонстрации мы будем менять встроенную опцию «Site Title» (Название сайта) так, чтобы она была передана настройщику тем, используя «postMessage«, а не как обычно, через «refresh«. Первое, мы добавляем следующую строку в главную функцию example_customizer(), созданную ранее:

Это обеспечит, что изменения значение этой опции будет передано предварительному просмотру через AJAX. Однако, для правильной работы надо, чтобы функция Javascript обработала значение, когда оно передается предварительному просмотру. Мы можем добавить этот код в функцию example_customize_preview(), которую мы создали на предыдущем шаге. Он просто обновляет текст привязки (анкор) внутри элемента «.site-name», когда значение меняется.

Имейте в виду: тема Responsive автора Emil Uzelac, используемая в этом руководстве не отображает название сайта, если присутствует изображение шапки. Отключите изображение шапки, если не получается протестировать код с этой темой.

12. Еще?

Я что-то упустил? Если у вас есть предложения по улучшению этого руководства или вы просто находите очень полезным и хотите рассказать мне об этом, не стесняйтесь, обращайтесь ко мне в комментариях.

Спасибо!

Источник: themefoundation.com


5 комментариев

Добавить комментарий

Войти с помощью: