Как разработчик темы или плагина WordPress, в процессе разработки придет время, когда вам потребуется включить сторонние скрипты или таблицы стилей в свой плагин или тему. Конечно, простое связывание ресурсов в верхнем или нижнем колонтитуле определенно будет работать, но следование стандартной практике с использованием предоставляемого WordPress API гарантирует, что ваша тема или плагин будут хорошо работать с другими плагинами в экосистеме WordPress.
Если вы хотите обеспечить максимальную совместимость с другими доступными плагинами и темами, обработка ресурсов в WordPress, безусловно, является навыком, который вы должны освоить.
Эта статья предназначена для начинающего разработчика WordPress, предполагая, что у вас есть практические знания о том, как работают действия WordPress и фильтры.
Основы
WordPress предоставляет несколько основных функций, которые помогают разработчику правильно загружать пользовательские ресурсы своей темы или плагина. Четырьмя основными функциями, которые вы будете часто использовать, являются wp_register_script , wp_enqueue_script , wp_register_style и wp_enqueue_style .
Давайте пройдемся по этим четырем основным функциям одну за другой.
wp_register_script( $handle, $src, $deps, $ver, $in_footer );
Я просто собираюсь вставить описание, приведенное в кодексе для этой функции.
Регистрирует файл скрипта в WordPress для последующей ссылки на страницу, которая безопасно обрабатывает зависимости скрипта.
$src аргументы $handle и $src , а последние три являются необязательными.
$handle это имя скрипта и должно быть уникальным. Это самая важная часть при постановке в очередь вашего скрипта, поскольку $handle будет идентификатором того, какой скрипт должен быть загружен.
$src — это URL-адрес скрипта. Вы можете получить правильный URL с помощью встроенных функций, таких как plugin_url() , get_template_directory_uri() и get_stylesheet_uri() . Для удаленного URL-адреса можно использовать независимый от протокола URL-адрес, такой как //ajax.googleapis.com/ajax/libs/jquery/2.1.3/jquery.min.js .
$deps должен быть массивом дескрипторов скриптов, от которого зависит ваш скрипт. Определив их здесь, WordPress загрузит эти зависимости в первую очередь перед загрузкой ваших пользовательских скриптов.
$ver — это просто версия вашего скрипта, и она будет добавлена в виде строки запроса в ваш параметр src тега script .
$in_footer — это логический флаг, который сообщает WordPress, загружать ли ваш скрипт в $in_footer раздела документа или в нижний колонтитул. Убедитесь, что тема правильно включает wp_head() и wp_footer() правильно, чтобы это работало.
wp_enqueue_script( $handle, $src, $deps, $ver, $in_footer );
Эта функция похожа на wp_register_script за исключением того, что требуется только параметр $handle . Если вы уже зарегистрировали свои сценарии перед выполнением с помощью wp_register_script , вы можете напрямую ставить их в очередь с помощью wp_enqueue_script('your-registered-handle') .
Это реальная функция, которая свяжет ваш скрипт с сгенерированной страницей, поэтому эту функцию необходимо использовать вместе с wp_register_script .
wp_register_style( $handle, $src, $deps, $ver, $media );
Это wp_register_script функция для wp_register_script , только эта функция будет обрабатывать все ваши регистрации таблицы стилей. Давайте рассмотрим каждый из аргументов этой функции.
$handle — это уникальный идентификатор вашей таблицы стилей, аналогичный идентификатору для ваших wp_register_script и wp_enqueue_script . Это обязательный параметр, и ваш дескриптор должен быть уникальным для вашей установки WordPress.
$src будет URL вашего файла CSS. Опять же, вы можете связать его с локальным файлом вашей темы или плагина, и он также работает с удаленным URL.
$deps будет обрабатывать все ваши CSS-зависимости, которые должны быть определены как массив дескрипторов стилей.
$ver — это необязательный параметр, в котором вы можете указать свою версию CSS, и он будет добавлен к URL-адресу в виде строки запроса.
$media — это типы мультимедиа CSS вашего CSS. Полный список допустимых значений можно найти на этой странице .
wp_enqueue_style( $handle, $src, $deps, $ver, $media );
Эта функция свяжет ваш CSS с созданной страницей, подобно тому, как работает wp_enqueue_script . В общем, вы можете ставить в очередь ранее зарегистрированный CSS или ставить CSS на ходу, определяя также параметр $src .
Когда мы ставим их в очередь?
Для постановки в очередь ваших скриптов и таблиц стилей рекомендуется три правильных хука.
Используйте wp_enqueue_scripts действия wp_enqueue_scripts всякий раз, когда вы хотите поставить свой сценарий в очередь на интерфейс вашего сайта. Не путайте с именем, так как тот же хук может быть использован и в вашем стиле.
Как насчет страницы администратора? Ну, вы можете подключить свою функцию enqueue к admin_enqueue_scripts и все ваши скрипты и стили будут загружены на административной стороне вещей правильно. Для загрузки ваших сценариев и стилей, в частности, на странице входа, login_enqueue_scripts хук действия login_enqueue_scripts .
Enqueue Versus Register
На первый взгляд, сначала необходимо зарегистрировать сценарии и таблицы стилей, прежде чем ставить их в очередь. Так почему же нам нужно в первую очередь использовать wp_register_script и wp_register_style , когда на самом деле мы можем вместо этого просто использовать wp_enqueue_script и wp_enqueue_style ? Ну, технически, вам не нужно.
Но если вы хотите динамически загружать свои скрипты и таблицы стилей на основе различных условий, лучше сначала зарегистрировать их, чтобы вы могли ставить их в очередь в любое время в любой точке выполнения, не повторяя себя.
Давайте посмотрим на этот простой пример:
wp_register_script( 'my-custom-js', ... ); wp_register_script( 'my-second-js', ... ); if ( is_page( 32 ) ) { wp_enqueue_script('my-custom-js'); } if ( $var ) { wp_enqueue_script('my-second-js'); }
Основываясь на этом фрагменте, вы можете видеть, что мы сначала регистрируем два пользовательских сценария, my-custom-js и my-second-js . Исходя из нескольких условий, в этом случае, когда загруженная страница имеет ID 32 или для $var установлено значение true , мы можем динамически ставить их в очередь.
Регистрация их в первую очередь также полезна, когда вы хотите использовать один и тот же скрипт в другой части веб-сайта. Как указывалось ранее, для загрузки ваших скриптов и таблиц стилей на лицевой стороне и на стороне администрирования необходимо использовать два разных хука. Поэтому, зарегистрировав их в первую очередь, вам просто нужно зарегистрировать их один раз и поставить их в очередь в оба связанных хука.
Что уже включено?
Многие разработчики прибегают к использованию собственной сторонней библиотеки, что приводит к большим размерам плагинов или тем и потенциальной несовместимости. WordPress включает в себя несколько полезных библиотек JavaScript, так почему бы не использовать их вместо этого?
Полный список того, что уже включено в соответствующий дескриптор, приведен на этой странице в разделе « Дескрипторы и пути их сценариев, зарегистрированные в WordPress ». Этот список может устареть, поэтому, если вы хотите посмотреть прямо на источник, взгляните на исходный код wp-includes/script-loader.php , в частности, внутри функции wp_default_scripts .
Вы можете найти много полезных библиотек, которые можно использовать повторно без необходимости включать их вместе с вашим плагином или темой.
Дополнительные функции
Помимо четырех основных функций для регистрации и постановки в очередь ваших сценариев и стилей, WordPress также предоставляет несколько функций, которые могут помочь в управлении активами вашего плагина или темы. Давайте посмотрим на некоторые из них.
Обеспечение доступности переменных PHP на стороне клиента с помощью wp_localize_script
Хотя эта функция в основном используется для обеспечения надлежащего локализованного перевода строк (таким образом, имени) в ваш код на стороне клиента, она может быть использована практически для того, чтобы любые данные, которые вы имеете на стороне сервера, были доступны и на стороне клиента.
wp_localize_script( $handle, $name, $data );
Как видно из приведенного выше кода, эта функция будет принимать три обязательных параметра. $handle относится к дескриптору сценария, для которого вы присоединяете данные. Важно отметить, что сценарий должен быть либо зарегистрирован, либо помещен в очередь, чтобы убедиться, что wp_localize_script работает правильно.
$name — это имя переменной, которая будет доступна на стороне клиента и будет содержать все указанные вами $data которые вы определили в массиве.
Вот простой фрагмент, чтобы объяснить, что делает эта функция:
wp_register_script( 'my-custom-js', ... ); $args = array( 'foo' => 'bar' ); wp_localize_script( 'my-custom-js', 'my_var', $args ); wp_enqueue_script( 'my-custom-js' );
Когда my-custom-js ставится в очередь, WordPress обрабатывает данные, чтобы сделать их доступными в коде на стороне клиента. Поскольку $args будет закодирован в JSON и назначен переменной my_var , вы всегда можете получить доступ к значению в вашем скрипте, как это обычно my_var любого объекта JavaScript.
<script> console.log( my_var.foo ); // print out "bar" in console </script>
Поставить в очередь все связанные скрипты для библиотеки мультимедиа WordPress с помощью wp_enqueue_media
Если вы хотите использовать собственный загрузчик мультимедиа WordPress в своем плагине или теме, вам нужно будет поставить в очередь все необходимые ресурсы, прежде чем вы сможете получить доступ ко всем доступным связанным API-интерфейсам. Чтобы упростить задачу, WordPress предоставляет вспомогательную функцию, которая поможет вам поставить в очередь все связанные скрипты, стили и шаблоны, связанные с Media API.
wp_enqueue_media( $args );
Единственный параметр — это $args , который является необязательным и может использоваться, если вы хотите поставить в очередь все связанные ресурсы, связанные с определенной публикацией. Я не буду слишком углубляться в то, как использовать доступный API для реализации встроенного загрузчика мультимедиа в вашем плагине или теме, поскольку он заслуживает отдельной статьи, но вот небольшой фрагмент для начала.
wp_enqueue_media(); // basic usage, enqueue all related scripts, styles and templates wp_enqueue_media( array( 'post' => 32 ) ); // enqueue all related assets for post with ID of 32
Добавление метаданных в wp_style_add_data стилей с помощью wp_style_add_data
Эта функция работает только для таблицы стилей и особенно полезна, когда вы хотите добавить метаданные, такие как условные комментарии, поддержку RTL и альтернативный заголовок, к вашей пользовательской таблице стилей.
wp_style_add_data( $handle, $key, $value );
Все три параметра обязательны. Давайте пройдемся по каждому из них, чтобы увидеть, что они представляют.
$handle — это конкретный дескриптор таблицы стилей, в который мы хотим добавить наши метаданные.
$key — это точка данных. Существует пять допустимых значений: rtl , suffix , alt и title
$value — это строка данных в сочетании с ранее указанным $key .
Вот пример фрагмента того, как мы можем использовать эту функцию для загрузки нашей таблицы стилей, специфичной только для Internet Explorer.
wp_enqueue_style( 'custom-ie-style', get_template_directory_uri() . '/css/ie.css' ); wp_style_add_data( 'custom-ie-style', 'conditional', 'IE' );
Это оно! Как только ваша таблица стилей будет связана с созданной страницей, это то, что фактически напечатано в head части документа.
<!--[if IE]> <link rel="stylesheet" id="custom-ie-style-css" href="http://www.example.com/wp-content/themes/example/css/ie.css" type="text/css" media="all"> <![endif]-->
Автоматическое filemtime кеша с помощью filemtime
На самом деле это не относится к WordPress, но я продолжал использовать этот код снова и снова в своих клиентских проектах. На самом деле он использует аргумент версии в wp_enqueue_script и связанных с ним функциях в качестве метода wp_enqueue_script кэша, проверяя время последнего изменения файла. Очевидно, это работает только для локального файла, так как мы используем PHP-функцию filemtime для определения последней измененной временной метки этого файла.
Вот как мы определяем аргумент версии, на примере функции wp_enqueue_script :
wp_enqueue_script( 'my-custom-js', get_template_directory_uri() . '/js/custom.js', array(), get_template_directory() . 'js/custom.js' );
Обратите внимание, что filemtime требует путь вашего файла, а не URL, поэтому в приведенном выше фрагменте мы используем функцию get_template_directory чтобы получить путь к каталогу нашей темы.
Отныне любые изменения в файле будут приводить к другому значению версии, и наша строка запроса будет обновляться соответствующим образом.
Вывод
Как ответственный разработчик WordPress, очень важно, чтобы вы применили лучшие практики к процессу разработки, и это включает в себя обучение правильной загрузке ресурсов в ваш пользовательский плагин или тему. Это обеспечит совместимость вашего плагина или темы с другими плагинами или темами, а также уменьшит конфликты и ошибки по мере развития WordPress.