Руководство по бесконфликтному включению JavaScript и CSS в WordPress
25 Мар 2023г. в 10:25Если у вас есть сайт под управлением WordPress, то просматривая исходный код страниц в браузере, вы вполне можете обнаружить следующее сочетание строк:
1
<script src="/wp-includes/js/jquery/jquery.js?ver=1.6.1" type="text/javascript"></script>
2
<script src="/wp-content/plugins/some-plugin/jquery.js"></script>
Такая ситуация влечет за собой потерю времени на повторную загрузку кода и может привести к проблемам во время работы плагинов. Рассмотрим, как можно избежать дублирования.
Причина возникновения проблемы
Первая копия jQuery включается в код страницы самой системой WordPress, а вторая копия из папки some-plugin (папка какого-нибудь плагина) может включаться кодом плагина.
По умолчанию WordPress включает несколько библиотек JavaScript:
Scriptaculous,
jQuery (выполняется в режиме noConflict),
ядро jQuery UI и несколько виджетов для него,
Prototype.
Полный список можно найти в Codex.
Решение задачи
Так как WordPress включает некоторые библиотеки, то разработчики плагинов и тем могут избежать проблемы дублирования с помощью функций PHP wp_register_script и wp_enqueue_script для включения скриптов JavaScript в код HTML.
Только регистрация файла (функция wp_register_script) не делает никакого вывода в ваш код HTML. Она только добавляет файл в список известных WordPress скриптов. Далее в уроке будет показано, что с помощью регистрации можно отслеживать информацию по версии плагина или темы.
Чтобы вывести код из файла в код страницы HTML нужно включить файл в очередь (функция wp_enqueue_script). С помощью данной функции WordPress включает нужный тег script в заголовок или в нижний колонтитул страницы. Далее в уроке будет показано, как сделать включение.
Регистрация файла требует выполнения более сложного кода, чем включение в очередь.
Чтобы данная техника работала, файл темы header.php должен иметь строку <?php wp_head(); ?> непосредственно перед тегом </head>, а файл footer.php - строку <?php wp_footer(); ?> непосредственно перед тегом </body>.
Регистрация кода JavaScript
Перед регистрацией вашего кода JavaScript нужно определиться с несколькими параметрами:
идентификатор файла (то есть имя, под которым WordPress будет знать ваш код);
зависимость от других скриптов и библиотек (например, от jQuery);
номер версии (не обязательно);
где будет вставляться код из файла в страницу HTML (заголовок или нижний колонтитул).
В данном уроке разбирается тема WordPress, но все рекомендации равнозначно действительны и для плагинов.
Примеры
Для иллюстрации силы функций будем использовать пример двух фалов JavaScript.
Первый будет называться base.js, который содержит некоторую функцию:
1
function makeRed(selector){
2
var $ = jQuery; //используем псевдоним $ в данном контексте
3
$(function(){
4
$(selector).css('color','red');
5
});
6
}
Файл base.js зависит от jQuery. Версия данного фала будет 1.0.0, а включать его нужно в нижний колонтитул.
Второй файл custom.js использует код JavaScript на сайте:
1
makeRed('*');
Файл custom.js вызывает функцию, определенную в файле base.js, то есть зависит от него.
Как и base.js, custom.js будет иметь версию 1.0.0 и включается в нижнем колонтитуле страницы.
Файл custom.js также неявно зависит от jQuery. Но в данном случае нет необходимости указывать зависимость.
Зарегистрируем наш код JavaScript с помощью функции wp_register_script. Она принимает следующие аргументы:
$handle строка, идентификатор файла
$source строка, источник файла
$dependancies массив (опционально), зависимости
$version строка (опционально), номер версии
$in_footer true/false (опционально, по умолчанию false), флаг размещения фала в нижнем колонтитуле
При регистрации скриптов лучшим методом является использование крючка init для выполнения операции один раз для всех скриптов.
Для регистрации скриптов в нашем примере нужно добавить следующий код в файл темы functions.php:
function mytheme_register_scripts() {
//base.js – зависит от jQuery
wp_register_script(
'theme-base', //идентификатор
'/wp-content/themes/my-theme/base.js', //источник
array('jquery'), //зависимости
'1.0.0', //версия
true //выполняем в нижнем колонтитуле
);
//custom.js – зависит от base.js
wp_register_script(
'theme-custom',
'/wp-content/themes/my-theme/custom.js',
array('theme-base'),
'1.0.0',
true
);
}
add_action('init', 'mytheme_register_scripts');
Регистрировать jQuery не нужно.
Выполнение регистрации не включает никакого кода JavaScript в код HTML.
Чтобы внести добавить соответствующий вывод в код HTML, нужно включить наши файлы в очередь. В отличие от регистрации, включение в очередь выполняется очень коротким кодом.
Вывод кода JavaScript в код HTML
Добавление тега <script> в код HTML выполняется функцией wp_enqueue_script. Она принимает единственный аргумент - идентификатор файла, определенный при регистрации:
function mytheme_enqueue_scripts(){
if (!is_admin()):
wp_enqueue_script('theme-custom'); //custom.js
endif; //!is_admin
}
add_action('wp_print_scripts', 'mytheme_enqueue_scripts');
Из двух зарегистрированных файлов JavaScript (base.js и custom.js), нужно добавить только второй к функционалу сайта. Без второго файла, добавление первого не имеет смысла.
При обработке включенного в очередь файла custom.js для вставки кода в HTML, WordPress распознает зависимость от base.js, который, в свою очередь, зависит от jQuery. Код HTML будет выглядеть так:
1
<script src="/wp-includes/js/jquery/jquery.js?ver=1.6.1" type="text/javascript"></script>
2
<script src="/wp-content/themes/my-theme/base.js?ver=1.0.0" type="text/javascript"></script>
3
<script src="/wp-content/themes/my-theme/custom.js?ver=1.0.0" type="text/javascript"></script>
Регистрируем таблицу стилей
Для добавления стилей CSS в WordPress имеются две аналогичные функции PHP: wp_register_style и wp_enqueue_style.
Так же как и для примера с JavaScript допустим, что у нас есть пара CSS файлов (например, для организации дизайна сайта на мобильных устройствах).
Файл mobile.css содержит код CSS для построения мобильной версии сайта и не имеет зависимостей.
Файл desktop.css загружается только для настольных версий браузеров. Стили для него строятся на основе мобильной версии, так что есть зависимость от mobile.css.
Как только вы определитесь с номером версии, зависимостями и типами медиа среды нужно зарегистрировать таблицу стилей с помощью функции wp_register_style. Данная функция получает следующие аргументы:
$handle строка, идентификатор файла
$source строка, источник файла
$dependancies массив (опционально, по умолчанию отсутствует), зависимости
$version строка (опционально, по умолчанию текущий номер версии WordPress)
$media_type строка (опционально, по умолчанию all), тип медиа среды
Как и с JavaScript, регистрация с помощью крюка init является лучшим вариантом.
В код файла темы functions.php следует добавить строки:
function mytheme_register_styles(){
//mobile.css для всех устройств
wp_register_style(
'theme-mobile', //идентификатор файла
'/wp-content/themes/my-theme/mobile.css', //источник
null, //нет зависимостей
'1.0.0' //версия
);
//desktop.css для браузеров на больших экранах
wp_register_style(
'theme-desktop',
'/wp-content/themes/my-theme/desktop.css',
array('theme-mobile'),
'1.0.0',
'only screen and (min-width : 960px)' //тип медиа среды
);
/*Для условных комментариев*/
}
add_action('init', 'mytheme_register_styles');
Мы используем медиа запрос CSS3 для предотвращения разбора таблицы стилей для больших экранов браузерами мобильных устройств. Но Internet Explorer 8 и старше не распознают меди запросы CSS3. IE8 всего два года, поэтому следует позаботиться о поддержке его пользователей с помощью условных комментариев.
Условные комментарии
В то время как для регистрации и включения кода CSS в очередь используются функции PHP, условные комментарии требуют более сложных действий. WordPress использует объект $wp_styles для хранения зарегистрированных таблиц стилей.
Чтобы заключить ваш код в условные комментарии, нужно добавить дополнительную информацию к данному объекту.
Для Internet Explorer 8 и старше, исключая мобильную версию IE, нужно зарегистрировать другую копию таблицы стилей для больших экранов (используя тип медиа среды all) и обернуть ее в условный комментарий.
В вышеприведенном примере /*Для условных комментариев*/ нужно заменить следующим кодом:
global $wp_styles;
wp_register_style(
'theme-desktop-ie',
'/wp-content/themes/my-theme/desktop.css',
array('theme-mobile'),
'1.0.0'
);
$wp_styles->add_data(
'theme-desktop-ie', //идентификатор файла
'conditional', //он будет заключен в условный комментарий
'!(IEMobile)&(lte IE 8)' //условие для комментария
);
К сожалению, нет эквивалентной функции для заключения JavaScript файла в условный комментарий.
Если нужно заключать файл JavaScript в условный комментарий, придется добавлять его в файлы header.php или footer.php темы. В качестве альтернативы можно использовать крюки wp_head или wp_footer.
Выводим таблицу стилей в HTML
Вывод таблицы стилей в код HTML осуществляется с помощью крюка wp_print_styles.
В нашем примере нужно поставить в очередь на обработку идентификаторы theme-desktop и theme-desktop-ie. WordPress автоматически выведет версии mobile/all.
Однако если таблицы стилей используют сброс, то нужно зарегистрировать их и включить в очередь. Такое действие поможет отследить, что происходит.
Код, который выводит CSS в HTML коде страницы:
1
function mytheme_enqueue_styles(){
2
if (!is_admin()):
3
wp_enqueue_style('theme-mobile'); //mobile.css
4
wp_enqueue_style('theme-desktop'); //desktop.css
5
wp_enqueue_style('theme-desktop-ie'); //desktop.css lte ie8
6
endif; //!is_admin
7
}
8
add_action('wp_print_styles', 'mytheme_enqueue_styles');
Небольшие ограничения
Если вы используете библиотеку JavaScript в своей теме или плагине, то можете наткнуться на несоответствие используемых в WordPress версий последнему релизу. (Обновление до последней версии технически возможно, но может привести к проблемам с темами или плагинами, которые настроены на то вариант, который поставляется с WordPress.)
Таким образом, использование новинок библиотеки ограничивается той версией, которая включается в WordPress. Но преимуществом является факт, что все авторы тем и плагинов знают, какая версия используется.
Единая точка регистрации
Регистрация ваших стилей и скриптов выполняется в одном блоке кода. Поэтому при обновлении версии очень просто сделать все в одном месте.
Если вы используете разный код в разных местах сайта, вы можете объединить логику вокруг скрипта для постановки в очередь.
Допустим, архивные страницы используют другой код JavaScript в отличие от остального сайта, тогда вы можете зарегистрировать три файла:
общий код JavaScript (регистрируется как theme-base),
архивный код JavaScript (регистрируется как theme-archive),
код JavaScript остального сайта (регистрируется как theme-general).
Общий код JavaScript ничего не добавляет к страницам сайта. Он используется для группировки общих функций, на которые опираются два других файла. Для постановки в очередь обработки можно использовать следующий код:
1
function mytheme_enqueue_js(){
2
if (is_archive()) {
3
wp_enqueue_script('theme-archive');
4
}
5
elseif (!is_admin()) {
6
wp_enqueue_script('theme-general');
7
}
8
}
9
add_action('wp_print_scripts', 'mytheme_enqueue_js');
