Руководство по бесконфликтному включению JavaScript и CSS в WordPress

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

<script src="/wp-includes/js/jquery/jquery.js?ver=1.6.1" type="text/javascript"></script>
<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, который содержит некоторую функцию:

function makeRed(selector){
  var $ = jQuery; //используем псевдоним $ в данном контексте
  $(function(){
    $(selector).css('color','red');
  });
}

Файл base.js зависит от jQuery. Версия данного фала будет 1.0.0, а включать его нужно в нижний колонтитул.

Второй файл custom.js использует код JavaScript на сайте:

Файл 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 будет выглядеть так:

<script src="/wp-includes/js/jquery/jquery.js?ver=1.6.1" type="text/javascript"></script>
<script src="/wp-content/themes/my-theme/base.js?ver=1.0.0" type="text/javascript"></script>
<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 коде страницы:

function mytheme_enqueue_styles(){
  if (!is_admin()):
    wp_enqueue_style('theme-mobile'); //mobile.css
    wp_enqueue_style('theme-desktop'); //desktop.css
    wp_enqueue_style('theme-desktop-ie'); //desktop.css lte ie8
  endif; //!is_admin
}
add_action('wp_print_styles', 'mytheme_enqueue_styles');

Небольшие ограничения

Если вы используете библиотеку JavaScript в своей теме или плагине, то можете наткнуться на несоответствие используемых в WordPress версий последнему релизу. (Обновление до последней версии технически возможно, но может привести к проблемам с темами или плагинами, которые настроены на то вариант, который поставляется с WordPress.)

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

Единая точка регистрации

Регистрация ваших стилей и скриптов выполняется в одном блоке кода. Поэтому при обновлении версии очень просто сделать все в одном месте.

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

Допустим, архивные страницы используют другой код JavaScript в отличие от остального сайта,  тогда вы можете зарегистрировать три файла:

• общий код JavaScript (регистрируется как theme-base),
• архивный код JavaScript (регистрируется как theme-archive),
• код JavaScript остального сайта (регистрируется как theme-general).

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

function mytheme_enqueue_js(){
  if (is_archive()) {
    wp_enqueue_script('theme-archive');
  }
  elseif (!is_admin()) {
    wp_enqueue_script('theme-general');
  }
}
add_action('wp_print_scripts', 'mytheme_enqueue_js');

• Комментарии