В этом руководстве показано, как добавить настройки темы, например цвета темы, в настройщик WordPress и перекомпилировать таблицу стилей темы с выбранными переменными. Имея стили темы в SCSS с помощью библиотеки, вы можете легко позволить пользователям темы настраивать любые переменные в таблице стилей темы без необходимости редактировать файлы SCSS самостоятельно.
Любая хорошая тема должна позволять много настроек. По крайней мере, должна быть возможность установить основные цвета темы. Вместо того, чтобы писать много уродливого CSS для переопределения цветов темы везде, вы можете вместо этого перекомпилировать полную таблицу стилей непосредственно из Customizer. Этот урок научит вас, как!
Что мы будем делать – и что нам нужно
Я предполагаю, что ваша тема уже имеет некоторые стили в файлах SCSS, которые вы уже скомпилировали в файл main темы style.css. И используя SCSS, вы, скорее всего, определяете повторяющиеся вещи, такие как цвета, размеры или точки останова, как переменные SCSS и используете эти переменные в своих стилях.
Вы можете создать любое количество настроек Customizer для переменных в файле SCSS. Пипетки, числовой и текстовый ввод идеально подходят для этого. Когда пользователь изменяет настройки в WordPress Customizer, он увидит предварительный просмотр темы с измененными переменными. И когда они нажмут «Сохранить», окончательный CSS будет скомпилирован в основной CSS-файл таблицы стилей с использованием выбранных значений.
В качестве примера для этого руководства я предполагаю, что основной файл SCSS таблицы стилей темы @importсоздает variables.scssфайл. Там мы определили три переменные, которые мы хотим настроить в Customizer: два цвета и один размер текста в формате px.
$main: #594c74 !default;
$secondary: #555 !default;
$text-size: 12px !default;Обратите внимание, что для того, чтобы позволить SCSS переопределять переменные, они должны быть определены с расширением !default. Это правило SCSS. Для того, чтобы этот учебник работал; любые переменные, которые вы хотите настроить, должны быть определены по умолчанию в ваших файлах SCSS.
Вам решать, когда (и если) вы хотите перезаписать файл CSS. В этом руководстве предполагается, что когда пользователь нажимает «Сохранить» в Customizer, он перекомпилирует и запишет в CSS темы. Однако, пока предварительный просмотр Customizer активен и пользователь меняет настройки (до нажатия кнопки «Сохранить»), мы просто выводим скомпилированный CSS в заголовок для предварительного просмотра веб-сайта. Мы не хотим сразу перезаписывать файл CSS на тот случай, если пользователь захочет отменить внесенные изменения.
Иметь ввиду…
Это руководство будет перезаписывать style.cssфайл темы при каждом сохранении настроек Customizer.
Я предполагаю, что вы уже скомпилировали файлы SCSS с помощью программы-компилятора (например, Koala или командной строки). Наличие этого кода в вашей теме перезапишет файл CSS, но не изменит ваши исходные файлы SCSS. Это означает, что всякий раз, когда вы вносите изменения в Customizer, а затем возвращаетесь к своим исходным файлам SCSS и перекомпилируете, ваши настройки Customize будут потеряны!
Есть несколько способов обойти это, и это зависит от вашего проекта и того, как вы работаете. В большинстве случаев это не будет проблемой. Обычно об этом нужно помнить, пока вы разрабатываете свою тему. Если вы отдаете свою завершенную тему кому-то еще для использования, они в любом случае не будут касаться ваших файлов SCSS.
С этим покончено, давайте начнем смотреть, как мы это делаем:
- Знакомимся с библиотекой SCSSPHP и включаем ее в нашу тему.
- Создайте настройки Customizer для каждой переменной SCSS, которую мы хотим настроить.
- Убедитесь, что настройщик предварительно просматривает изменения на ходу
- При сохранении настроек Customizer мы перекомпилируем и перезапишем файл CSS темы.
1 Библиотека SCSSPHP
Для компиляции файлов SCSS мы будем использовать библиотеку SCSSPHP от leafo (лицензия MIT). Обратите внимание, что это руководство относится к библиотеке SCSS. У автора библиотеки есть похожая библиотека LESS PHP, если вы предпочитаете использовать LESS, но помните, что следующее руководство предназначено для библиотеки SCSS.
Библиотека SCSSPPHP очень проста в использовании! Вот упрощенный обзор того, как мы будем использовать библиотеку в PHP нашей темы:
- Включаем библиотеку
- Создайте новый экземпляр класса компилятора из библиотеки
- Загрузите содержимое исходного файла SCSS и передайте его объекту компилятора.
- Определить ассоциативный массив; Имена переменных SCSS (включая
$) в виде ключей и их значений. Любой элемент в этом массиве переопределит переменные с тем же именем в предоставленном файле SCSS. - Мы просим объект компилятора скомпилировать и получаем в ответ скомпилированный CSS в виде строки. Затем мы можем либо вывести этот CSS внутри
head, либо записать его вstyle.cssфайл темы.
Какие переменные SCSS мы можем скомпилировать?
Простой ответ: любая допустимая переменная SCSS!
Библиотека SCSSPHP может скомпилировать любую допустимую переменную SCSS, но имейте в виду, что вы должны убедиться, что они правильно отформатированы из Customizer. Например, цвета должны иметь префикс a #для шестнадцатеричных цветов или быть отформатированы как rgb()или rgba()определения. К переменной размера обычно нужно добавлять ‘ px‘, ‘ em‘, ‘ %‘ и так далее.
Если вы планируете создать продвинутую систему для компиляции переменных SCSS с помощью темы Customizer, убедитесь, что у вас есть хорошая система для правильного форматирования каждого типа переменных!
Давайте сделаем первый шаг в сторону; скачиваем и включаем библиотеку в нашу тему:
Загрузка и включение библиотеки SCSSPHP в вашу тему
Первым шагом является загрузка библиотеки SCSSPHP. На связанной странице нажмите кнопку «Скачать» в самом верху. Если вы предпочитаете использовать Composer, на сайте есть руководство по этому вопросу.
Распакуйте zip в подпапку где-нибудь в вашей теме. В качестве примера я помещаю его в theme/inc/scssphp/папку.
Откройте файл PHP, куда вы хотите добавить свой код для компиляции. Это может быть непосредственно внутри вашей темы functions.phpили файла PHP, включенного в functions.php. Для простоты я пишу все внутри functions.php.
Прежде чем мы сможем использовать библиотеку, нам нужно включить ее; вот так:
require_once(get_stylesheet_directory(). '/inc/scssphp/scss.inc.php');Соответственно измените путь к своим файлам. Нам нужно включить scss.inc.phpфайл, найденный в корневой папке библиотеки. Теперь после этой строки мы можем использовать классы библиотеки!
2 Создание настроек Customizer для переменных SCSS
Давайте создадим настройки WordPress Customizer для наших переменных. Ради урока мы добавим настройки для упомянутых выше переменных SCSS: две палитры цветов и числовой ввод.
Я не буду подробно объяснять, как добавить настройки Customizer — для этого есть множество руководств. В приведенном ниже примере кода я создаю новый раздел и помещаю внутрь три параметра:
Этот код подключается customize_registerи добавляет раздел под названием «Переменные темы». Затем он добавляет палитру цветов ‘ theme-main‘, еще одну палитру цветов ‘ theme-secondary‘ и ввод числа ‘ theme-text-size‘. Это все функциональные возможности WordPress по умолчанию. Я также добавляю для каждого параметра по умолчанию те же значения, которые определены в variables.scssфайле. Это просто для того, чтобы настройки Customizer запускались с правильными цветами.
Это выглядит здорово! Но на данный момент ничего не происходит, когда вы настраиваете эти переменные. Давайте продолжим с шагом 3; обработка предварительного просмотра в Customizer.
3 Скомпилируйте CSS на ходу в предварительном просмотре Customizer
Этот шаг обрабатывает обновление предварительного просмотра настройщика, пока пользователь меняет настройки, и не записывает ни в один из наших файлов. Вместо этого мы выведем скомпилированный CSS в <head>превью внутри <style>тега. Таким образом мы гарантируем, что встроенный CSS переопределит все стили из исходного файла CSS.
Чтобы проверить, используем ли мы в настоящее время предварительный просмотр Customizer, мы используем функцию [is_customize_preview](https://developer.wordpress.org/reference/functions/is_customize_preview/)(). Когда это возвращается true, мы создаем функцию, привязанную к wp_head. Внутри функции мы инициируем и настраиваем библиотеку SCSSPHP, получаем текущие значения настроек, компилируем CSS и выводим его в <style>теге.
В строке #7мы определяем путь к исходному файлу SCSS и загружаем его содержимое в переменную по адресу #8. И в строке #9и #10мы настраиваем путь импорта для библиотеки, чтобы убедиться, что все @imports работают правильно в наших файлах SCSS. Подробнее об этом можно прочитать на сайте документации библиотеки, в заголовке «Import Paths». По сути, библиотеке SCSSPHP необходимо знать относительный путь к вашей папке SCSS, чтобы все @importпути были правильными.
В строке #12-16мы создаем массив для компилятора; ассоциативный массив с именами переменных в качестве ключей. Для значений, которые мы используем [get_theme_mod](https://developer.wordpress.org/reference/functions/get_theme_mod/)(), чтобы получить значения из Customizer. Функция get_theme_mod()позволяет определить значение по умолчанию в качестве второго параметра, если значение не было сохранено. Это спасает нас от сбоя компилятора с такими значениями, как null. Таким образом, мы предоставляем то же значение по умолчанию, что и в нашем файле переменных SCSS и при регистрации настроек Customizer.
Также обратите внимание, что код в строке #15добавляет ‘ px‘, гарантируя, что фактическое значение переменной допустимо. В противном случае он будет компилироваться как «$text-size: 12;», когда нам нужен «$text-size: 12px;». Мы предоставляем компилятору массив переменных в строке #17, сообщая ему о необходимости компиляции с использованием этих переменных.
Затем в строке #19-22мы вызываем compile()функцию, которая должна вернуть скомпилированный CSS в виде строки. Мы выводим <style>тег со строкой CSS внутри. Поскольку мы привязаны к wp_head, настройщик будет отображать предварительный просмотр с измененным CSS каждый раз, когда вносятся изменения.
4 Сохранение скомпилированного CSS в таблице стилей темы
Код для компиляции CSS очень похож на предыдущий шаг. Единственное отличие состоит в том, что теперь мы записываем CSS в файл, а не выводим его. Вам действительно следует подумать о том, чтобы поместить это в функцию, чтобы не повторять код, но для ясности я решил разделить их.
Мы определяем [customize_save_after](https://developer.wordpress.org/reference/hooks/customize_save_after/), какие триггеры срабатывают всякий раз, когда кто-то нажимает «Сохранить» в настройщике WordPress. На этом этапе мы извлекаем исходный SCSS, определяем значения переменных и компилируем его в CSS. Со строкой CSS мы используем простую функцию PHP, чтобы записать ее в файл CSS темы.
Единственное отличие от предыдущего — это строка, в #8которой мы определяем целевой файл для записи, и строка, в #19которой мы записываем в файл.
Вывод
Теперь у нас есть настройки Customizer, которые управляют переменными в файле SCSS темы и перезаписывают основную таблицу стилей темы, используя эти переменные. Нет ограничений на то, сколько и какие настройки вы хотите разрешить пользователям темы настраивать! Потратьте некоторое время на настройку надлежащей системы для обработки форматирования различных типов переменных (например, префиксов или постфиксов) и правильную структуру настроек настройщика. Пользователи темы оценят гибкость и простоту настройки темы!
Вы также можете найти различные способы обработки записи файла окончательного CSS. Если вы не хотите перезаписывать основную таблицу стилей, возможно, вы хотите вывести ее в другой файл. Вы также можете изучить использование условий if-else в SCSS.
Этот учебник был написан, чтобы дать вам трамплин для того, как вы можете настроить свою тему WordPress из Customizer. Дайте мне знать, было ли это полезно для вас — или если вам нужен более продвинутый учебник, который гарантирует, что таблица стилей темы не будет перезаписана!