Як додати JavaScript і CSS у WordPress тему або плагін

Знання правильного способу включення JavaScript и CSS файлів у ваші WordPress теми та плагіни дуже важливо для дизайнерів та розробників. Якщо ви не наслідуватимете кращі підходи, ви ризикуєте вступити в конфлікт з іншими темами та плагінами і потенційно створюєте проблеми, яких можна було б легко уникнути. Ця стаття може бути джерелом інформації про те, як уживатися з JavaScript та CSS у WordPress.

Правильний підхід до справи

Якщо ви коли-небудь розробляли тему або плагін для WordPress або працювали зі створеними кимось, ви, швидше за все, пробували кілька різних методів включення JavaScript та CSS. Незважаючи на те, що є кілька методів, які можуть працювати за певних обставин, є один основний метод, рекомендований WordPress Codex. Завдяки цьому методу ви зможете бути впевненим, що тема або плагін працюватиме в будь-якому випадку (за умови, що інші будуть писати код правильно).

Є певне непорозуміння в тому, що саме Codex говорить із цього приводу, і я намагатимусь допомогти роз'яснити це питання.

Що в коробці?

Коли ви завантажили WordPress, вибір поширених JavaScript бібліотек, які ви можете використовувати для розробки JavaScript, вже включено. Список включених бібліотек можна знайти у статті WordPress Codex wp_enqueue_script.

Всі ці бібліотеки включені, але за замовчуванням WordPress завантажує лише ті, які йому потрібні, і лише тоді, коли вони потрібні йому. Якщо ви пишете JavaScript, який використовує одну з цих бібліотек, вам потрібно сказати WordPress, що вашому скрипту спочатку потрібно завантажити бібліотеку.

Чи знає WordPress про ваш скрипт та його потреби?

Ось деякі речі, про які вам потрібно подумати, коли ви пишете JavaScript для WordPress:

• Чи є вже увімкнена бібліотека, яку я можу використовувати?
• Чи можу я використовувати увімкнену версію?
• Чи потрібно мені завантажувати мій скрипт у клієнтську та адміністраторську частину?
• На яких сторінках клієнтської та адміністраторської частини мені потрібно завантажувати мій скрипт?

Відповіді на ці запитання допоможуть вам дізнатися, що вам потрібно зробити, щоб зареєструвати та завантажити ваш скрипт. Це відбувається за допомогою WordPress функції wp_register_script, і ось як її потрібно використовувати згідно з WordPress Codex:

wp_register_script( $handle, $src, $deps, $ver, $in_footer );

То що це за змінні і чи вони нам потрібні весь час? Це описано на сторінці Кодекс, Так що я коротко опишу:

• $handle — її ви використовуватимете для того, щоб посилатися на цей конкретний скрипт, коли вам потрібно буде додати його до черги, і вам потрібно вставляти цю змінну в самому кінці.
• $src шлях до вихідного файлу вашого плагіна або теми.
• $deps - масив, який включає $handle для всіх скриптів, які можуть знадобитися вашому скрипту (тобто залежності).
• $ver номер версії вашого скрипта, яка може бути використана для знищення кешу. За промовчанням WordPress використовуватиме свою версію як версію вашого скрипта.
• $in_footer - Ви хочете, щоб ваш скрипт завантажувався у підвалі? Встановіть значення цієї змінної правда або false. За замовчуванням воно встановлено false, так що скрипт завантажується в шапці, де wp_head(), а якщо ви вкажете правда, скрипт буде завантажуватись у підвалі, де в темі вказано wp_footer().

Що таке "знищення кешу"?

Браузери запам'ятовують, які скрипти та таблиці стилів вони завантажували для конкретного сайту, ґрунтуючись на URL скрипт і таблиці стилів. Якщо ви зміните URL-адресу, навіть просто додавши туди запит, браузер припустить, що це новий файл, і завантажить його.

Перейдемо до прикладів

Ось простий приклад підключення скрипту:

function wptuts_scripts_basic()  
{  
    // Register the script like this for a plugin:  
    wp_register_script( 'custom-script', plugins_url( '/js/custom-script.js', __FILE__ ) );  
    // or  
    // Register the script like this for a theme:  
    wp_register_script( 'custom-script', get_template_directory_uri() . '/js/custom-script.js' );  
    // For either a plugin or a theme, you can then enqueue the script:  
    wp_enqueue_script( 'custom-script' );  
}  
add_action( 'wp_enqueue_scripts', 'wptuts_scripts_basic' );

Спочатку ми реєструємо скрипт, тому тепер WordPress знає, з чим ми працюємо. Шлях до нашого JavaScript файлу може бути різним, залежно від того, ми пишемо тему або плагін, так що вище я включив приклади і того, і іншого. Потім ми додамо його в чергу на додавання в HTML для сторінки, коли її буде згенеровано, за замовчуванням — у блоціголова> у місці виклику в темі wp_head().

Ось що ми отримаємо з цього прикладу:

<script type="text/javascript" src="http://yourdomain.com/wp-content/plugins/yourplugin/js/custom-script.js?ver=3.3.1"></script>

Тепер, якщо ваш скрипт базується на одній із бібліотек, включених до WordPress, наприклад jQuery, ви можете зробити просту зміну в коді:

function wptuts_scripts_with_jquery()  
{  
    // Register the script like this for a plugin:  
    wp_register_script( 'custom-script', plugins_url( '/js/custom-script.js', __FILE__ ), array( 'jquery' ) );  
    // or  
    // Register the script like this for a theme:  
    wp_register_script( 'custom-script', get_template_directory_uri() . '/js/custom-script.js', array( 'jquery' ) );  
    // For either a plugin or a theme, you can then enqueue the script:  
    wp_enqueue_script( 'custom-script' );  
}  
add_action( 'wp_enqueue_scripts', 'wptuts_scripts_with_jquery' );

Примітка: За замовчуванням, jQuery завантажується з noConflict, щоб запобігти конфліктам з іншими бібліотеками (наприклад, Prototype). Подивіться розділ noConflict у Codexякщо ви не знаєте, як це працює.

То що ми тут зробили? Ми просто додали масив з вказівником 'jquery' як залежність. Тут використовується масив, так як ваш скрипт може мати кілька залежностей. Якщо ваш скрипт використовує jQuery и Інтерфейс користувача jQuery, ви можете додати Інтерфейс користувача jQuery у ваш масив залежностей, наприклад так:
array( 'jquery', 'jquery-ui-core')

Тепер результат змінився, і ми бачимо, що jQuery також був доданий вголова>сторінки.

<script type='text/javascript' src='http://yourdomain.com/wp-includes/js/jquery/jquery.js?ver=1.7.1'></script>  
<script type='text/javascript' src='http://yourdomain.com/wp-content/plugins/yourplugin/js/custom-script.js?ver=3.3.1'></script>

Спробуємо приклад із усіма прибамбасами:

function wptuts_scripts_with_the_lot()  
{  
    // Register the script like this for a plugin:  
    wp_register_script( 'custom-script', plugins_url( '/js/custom-script.js', __FILE__ ), array( 'jquery', 'jquery-ui-core' ), '20120208', true );  
    // or  
    // Register the script like this for a theme:  
    wp_register_script( 'custom-script', get_template_directory_uri() . '/js/custom-script.js', array( 'jquery', 'jquery-ui-core' ), '20120208', true );  
    // For either a plugin or a theme, you can then enqueue the script:  
    wp_enqueue_script( 'custom-script' );  
}  
add_action( 'wp_enqueue_scripts', 'wptuts_scripts_with_the_lot' );

Так тепер я додав версію і вказав, що скрипт потрібно завантажувати в підвалі. Як версію я вирішив використати сьогоднішню дату, тому що так простіше відстежувати, але ви можете використовувати будь-який підхід до нумерації версій. Результат цього прикладу не особливо відрізняється, jQuery вголова>, а наш скрипт разом з Інтерфейс користувача jQuery - Прямо перед/тіло>, наприклад:

<head>  
...  
<script type='text/javascript' src='http://yourdomain.com/wp-includes/js/jquery/jquery.js?ver=1.7.1'></script>  
...  
</head>  
<body>  
...  
<script type='text/javascript' src='http://yourdomain.com/wp-includes/js/jquery/ui/jquery.ui.core.min.js?ver=1.8.16'></script>  
<script type='text/javascript' src='http://yourdomain.com/wp-content/plugins/yourplugin/js/custom-script.js?ver=20120208'></script>  
</body>

розставляємо пріоритети

Деякі вважають за краще не використовувати правильні методи постановки в чергу, тому що їм здається, що вони будуть менше контролю над порядком завантаження скриптів. Наприклад, у темі, яка використовує модернізр, автор теми, можливо, захоче переконатися, що модернізр завантажується заздалегідь.

Дещо, про що я не згадав раніше, — деталі того, як працює функція add_actionоскільки тут у нас може бути трохи впливу на порядок речей. Ось використання функції відповідно до сторінки WordPress Codex:

add_action( $tag, $function_to_add, $priority, $accepted_args );

Зверніть увагу, що часто використовуються лише параметри тег $ и $function_to_add. Параметр $priority за умовчанням дорівнює 10, а параметр $accepted_args - 1. Якщо ми хочемо, щоб наші скрипти або стилі були викликані раніше, ми просто зменшуємо значення $priority. наприклад:

function wptuts_scripts_important()  
{  
    // Register the script like this for a plugin:  
    wp_register_script( 'custom-script', plugins_url( '/js/custom-script.js', __FILE__ ) );  
    // or  
    // Register the script like this for a theme:  
    wp_register_script( 'custom-script', get_template_directory_uri() . '/js/custom-script.js' );  
    // For either a plugin or a theme, you can then enqueue the script:  
    wp_enqueue_script( 'custom-script' );  
}  
add_action( 'wp_enqueue_scripts', 'wptuts_scripts_important', 5 );

Результат буде таким самим, як ми бачили раніше, але він з'явиться в HTML документ раніше.

Перевизначення стандартних бібліотек та використання мереж доставки контенту

Можливо, ви захочете використовувати іншу версію бібліотеки, що включена до WordPress. Можливо, ви захочете використовувати найновішу версію або ви не хочете чекати наступного релізу WordPress для того, щоб використати останню стабільну версію jQuery. Інша причина – можливо, ви захочете скористатися Google CDN версія бібліотеки.

Важливо звернути увагу, що це може бути зроблено лише у плагінах або темах на сайтах, які ви особисто підтримуватимете. Будь-які плагіни або теми, які ви випускаєте для публічного використання, повинні використовувати бібліотеки, що включені в WordPress.

Я чую, як ви питаєте: "Чому?Проста причина - ви не контролюєте ті сайти. Ви не знаєте, які ще плагіни і теми можуть бути там використані, і ви не знаєте, як часто вони будуть оновлювати вашу плагін або тему. Використання бібліотек з пакету WordPress - найбільш безпечний варіант.

Тепер, якщо ви дійсно хочете зробити це на сайті, яким ви керуєте, ось як це можна зробити:

function wptuts_scripts_load_cdn()  
{  
    // Deregister the included library  
    wp_deregister_script( 'jquery' );  
    // Register the library again from Google's CDN  
    wp_register_script( 'jquery', 'http://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js', array(), null, false );  
    // Register the script like this for a plugin:  
    wp_register_script( 'custom-script', plugins_url( '/js/custom-script.js', __FILE__ ), array( 'jquery' ) ); 
    // or 
    // Register the script like this for a theme: 
    wp_register_script( 'custom-script', get_template_directory_uri() . '/js/custom-script.js', array( 'jquery' ) ); 
    // For either a plugin or a theme, you can then enqueue the script: 
    wp_enqueue_script( 'custom-script' ); 
} 
add_action( 'wp_enqueue_scripts', 'wptuts_scripts_load_cdn' );

Спочатку я скасовую реєстрацію включеної версії бібліотеки, інакше можуть виникнути конфлікти між різними версіями. Потім реєструємо альтернативну версію, використовуючи той самий покажчик. Я вирішив присвоїти версії значення нулю (він вже міститься в URL) і визначив, що відображатиметься не в підвалі. Решта коду буде той же, тому що ми залежимо від скрипта, який використовував покажчик 'jquery'. Результат, який ми отримаємо, виглядатиме приблизно так:

<script type='text/javascript' src='http://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js'></script>  
<script type='text/javascript' src='http://yourdomain.com/wp-content/plugins/yourplugin/js/custom-script.js?ver=3.3.1'></script>

Примітка: Одна з причин вважати це поганою ідеєю для плагінів або тем для громадського використання — всі інші плагіни та теми, використані на цьому сайті, тепер використовуватимуть цю версію jQuery. Також заново зареєстрована версія jQuery не містить noConflictтак що якщо будь-який інший скрипт плагіна або теми використовує, наприклад, Prototype, це все поламає.

Не скупіться

Поки що ми не згадували нічого про те, як все це робити в адмін частині, тільки з клієнтської сторони. Основна відмінність у тому, який дію використовувати. Замість
add_action( 'wp_enqueue_scripts', 'wptuts_scripts_basic');
який ми використали для клієнтської частини, для адміністратора буде
add_action( 'admin_enqueue_scripts', 'wptuts_scripts_basic');

Що важливо зробити і для клієнтської, і для адмінної частини — вибирати, на яких сторінках завантажувати ваші скрипти. Якщо ваш плагін або тема має скрипт, який робить щось тільки на одній клієнтській або адмін сторінці, наприклад, на сторінці налаштувань теми або сторінці з конкретним віджетом, вам потрібно завантажити ваш скрипт тільки на цій сторінці. Нема рації завантажувати скрипти на сторінках, на яких вони не використовуються!

В WordPress Codex є чудовий приклад того, як завантажувати скрипти тільки на сторінках плагіна. Оскільки плагіни та теми можуть відрізнятися в написанні коду, я не заглиблюватимусь у тому, як вибирати, на яких сторінках вантажити скрипти, але було важливо це згадати, щоб ви знали це, коли писатимете код.

Зі скриптами закінчили, тепер стилі

Процес для стилів практично такий самий, як для скриптів. Все відбувається за допомогою WordPress функції wp_register_style, і ось її використання згідно з WordPress Codex:

wp_register_style( $handle, $src, $deps, $ver, $media );

Зверніть увагу, що єдина різниця між wp_register_script и wp_register_style - те, що замість параметра $in_footer у нас параметр $media. Цей параметр може бути встановлений у значення 'всі','екран','портативний'і'друк', або будь-який інший медіа тип, що розпізнається W3C.

Отже приклад того, як може бути викликаний стиль, може бути таким:

function wptuts_styles_with_the_lot()  
{  
    // Register the style like this for a plugin:  
    wp_register_style( 'custom-style', plugins_url( '/css/custom-style.css', __FILE__ ), array(), '20120208', 'all' );  
    // or  
    // Register the style like this for a theme:  
    wp_register_style( 'custom-style', get_template_directory_uri() . '/css/custom-style.css', array(), '20120208', 'all' );  
    // For either a plugin or a theme, you can then enqueue the style:  
    wp_enqueue_style( 'custom-style' );  
}  
add_action( 'wp_enqueue_scripts', 'wptuts_styles_with_the_lot' );

Це досить складний приклад, який використовує більшість параметрів і ось що вийде на виході:

<link rel='stylesheet' id='custom-style-css'  href='http://yourdomain.com/wp-content/plugins/yourplugin/css/custom-style.css?ver=20120208' type='text/css' media='all' />

Чому не всі так роблять?

Гарне питання. Ще одне питання, яке ви могли б поставити, це «Чому ви думаєте, що це правильний спосіб, а не просто ваша перевага?» Зазвичай відповідь у цьому, що це підхід, рекомендований WordPress. Його використання дозволяє бути впевненими, що будь-яка комбінація плагінів і тим самим буде щасливо працювати разом без проблем.

Я бачив кілька тем і фреймворків, які використовують тегисценарій></ сценарій> іlink /> у своїх файлах header.php і навіть в footer.php для завантаження скриптів та стилів для теми. Немає причин для того, щоб робити це так. Як я показав раніше, цілком можна задати в пріоритет скрипти та стилі та вказати, чи повинні вони бути завантажені у шапці або у підвалі, зробити все це зручно та надійно у вашому functions.php. Вигода в тому, що ваша тема або фреймворк буде працювати з ширшим спектром інших плагінів та тем-нащадків.

В одному прикладі jQuery завантажувався з використанням тегівсценарій></ сценарій>, що в принципі може працювати добре, але це може призвести до того, що jQuery може завантажитися двічі! Завантаження jQuery таким чином не зупинить WordPress від завантаження своєї версії jQuery для інших плагінів, оскільки версії WordPress за замовчуванням у режимі noConflict, і плагін може визначити його як залежність. Отже, тепер у вас буде jQuery, який працює і в режимі noConflict и $, і також можливо зламає будь-який плагін, який використовує бібліотеку Прототип.

Висновок

WordPress - фантастична система, і вона була розроблена з розумом. Якщо є механізм, який був створений для чогось, краще використовувати його. Розробляючи ваші плагіни та теми, постарайтеся пам'ятати, що потрібно писати з розумом і думати про інших.

Що ви думаєте про використання wp_enqueue_script та пов'язаних з нею функціях та дію? Чи знаєте ви приклади неправильного використання? Чи є у вас причина не дотримуватися вищевикладених порад? Поділіться своїми думками у коментарях.

Джерело: WP.tutsplus.com

Олексій Шевченко

редактор wpcafe

Вивчає сайтобудування з 2008 року. Практикуючий вебмайстер, що спеціалізується на створенні сайтів WordPress. Задати питання Олексію можна на https://profiles.wordpress.org/wpthemeus/