Створення автозавершеного пошуку в WordPress за допомогою коду

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

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

Що ми зробимо

Автозаповнення – це поле інтерфейсу користувача, яке з’являється під полем пошуку та показує збіги під час введення. Після натискання на збіг браузер надсилає вас до постійного посилання на цю публікацію. Це надає кінцевому користувачеві швидший спосіб навігації по вашому вмісту, оскільки йому не потрібно буде додатково переходити на сторінку результатів пошуку. Ми будемо використовувати AJAX для постійного оновлення збігів, поки користувач вводить текст.

Автозаповнення генерується за допомогою jQuery UI Autocomplete, сценарію, який включено до WordPress за замовчуванням.

Налаштування коду

Вам потрібно буде додати код у functions.phpPHP-файл теми або активного плагіна. Цей підручник заснований на додаванні його в тему. Налаштуйте шляхи відповідно до вашого проекту.

Першим кроком є ​​створення файлу Javascript, який міститиме наш код для запуску автозаповнення. Що стосується цього підручника, я створю порожній autocomplete.jsфайл у assets/js/папці моєї теми. Ви вирішуєте, куди ви розмістите свій файл, просто не забудьте налаштувати шляхи нижче. Ми повернемося до цього файлу після того, як правильно поставимо його в чергу в WordPress.

Постановка сценаріїв і стилів у чергу

Нам потрібно поставити в чергу наш файл Javascript автозаповнення, а також переконатися, що jQuery та jQuery UI Autocomplete. Крім того, WordPress не містить стилів для бібліотек jQuery UI, тому нам також потрібно поставити таблицю стилів для jQuery UI з Google CDN. Звичайно, це необов’язково. Ви можете додати CSS іншим способом або, можливо, ви віддаєте перевагу стилізувати його самостійно.

Ми поставимо всі сценарії та стилі у функцію, підключену до wp_enqueue_scripts:

add_action('wp_enqueue_scripts', function() {
    wp_enqueue_script('autocomplete-search', get_stylesheet_directory_uri(). '/assets/js/autocomplete.js', 
        ['jquery', 'jquery-ui-autocomplete'], null, true);
});

Виклик [wp_enqueue_script](https://developer.wordpress.org/reference/functions/wp_enqueue_script/)()функції вище додасть наш щойно створений файл Javascript із правильними залежностями (масив як третій параметр). Це гарантує, що WordPress додає сценарії jQuery та jQuery UI Autocomplete у наш екземпляр WordPress.

Далі нам потрібно надати деякі змінні, до яких ми можемо отримати доступ із нашого сценарію автозаповнення. Нам потрібно знати URL-адресу AJAX, і ми також хочемо додати nonce для безпеки. Ми можемо зробити це за допомогою [wp_localize_script](https://developer.wordpress.org/reference/functions/wp_localize_script/)():

Функція wp_localize_script()створить глобальну змінну Javascript AutocompleteSearchіз двома властивостями; ajax_urlі ajax_nonce. Завдяки цьому ми можемо в нашому файлі Javascript автозаповнення отримати, наприклад, значення URL-адреси WordPress AJAX за допомогою AutocompleteSearch.ajax_url.

Нарешті нам потрібно додати трохи стилю. Як уже згадувалося, WordPress не містить жодних стилів інтерфейсу користувача jQuery, тому нам потрібно додати деякі самі. Я вибрав додавання таблиці стилів через Google CDN. Але нам потрібно знати номер версії jQuery UI, щоб отримати його таблицю стилів. Ми могли б жорстко закодувати номер версії, але я не прихильник жорсткого кодування. Нижче ви знайдете гарний трюк, щоб заздалегідь отримати інформацію про версію інтерфейсу jQuery, що зберігається в WordPress.

Ми використовуємо [wp_enqueue_style](https://developer.wordpress.org/reference/functions/wp_enqueue_style/)()для реєстрації та додавання нової таблиці стилів із наданим шляхом CDN як другим аргументом. Щоб отримати дійсний номер версії jQuery UI, ми використовуємо інформацію, надану функцією [wp_scripts](https://developer.wordpress.org/reference/functions/wp_scripts/)().

І це все, що нам потрібно для постановки сценаріїв у чергу!

Написання автозавершення Javascript

Повернемося до нашого autocomplete.jsфайлу. Ми знаємо, що коли цей сценарій завантажується, jQuery та jQuery UI Autocomplete вже завантажуються, і ми також маємо доступ до глобальної змінної з необхідною інформацією. Давайте почнемо з налаштування функції готовності документа jQuery, щоб забезпечити виконання нашого коду після того, як DOM буде готовий.

jQuery(function($) {
    // All code in here
});

Якщо ми звернемося до документації jQuery UI Autocomplete, то дізнаємося, що нам потрібно створити селектор jQuery, націлений на поле введення, і запустити функцію autocomplete()на ньому.

Це момент, де ви можете налаштувати код відповідно до своїх потреб. У цьому підручнику буде застосовано автозаповнення до стандартного поля пошуку WordPress (яке зазвичай додається в тему шляхом включення шаблону пошуку або як віджет). Назви класів пошукових даних можуть відрізнятися від теми до теми. Але ви можете націлитися на спеціальне поле введення або виконати пошук у спеціальному шаблоні. Все, що вам потрібно зробити, це змінити селектор jQuery на потрібний вам вхід.

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

Відповідно до документації автозаповнення ми можемо виконати виклик AJAX у властивості source(який має повернути масив елементів для відображення в автозавершенні). Для цього ми використаємо Ajax-функцію jQuery :

jQuery(function($) {
    $('.search-form .search-field').autocomplete({
        source: function(request, response) {
            $.ajax({
                dataType: 'json',
                url: AutocompleteSearch.ajax_url,
                data: {
                    term: request.term,
                    action: 'autocompleteSearch',
                    security: AutocompleteSearch.ajax_nonce,
                },
                success: function(data) {
                    response(data);
                }
            });
        },
    });
});

У рядку #2ми повідомляємо jQuery UI Autocomplete, до якого поля введення ми хочемо застосувати автозаповнення. Змініть цей селектор відповідно до ваших потреб.

У найпростішій формі автозаповнення очікує масив об’єктів елемента для sourceвластивості. Тут ми створюємо функцію з двома параметрами; requestмістить інформацію про наше введене значення (request.term), а responseтакож про функцію зворотного виклику, яку нам потрібно викликати та надати дані. Це те, що ми робимо у функції AJAX successу рядку #13.

Сам виклик AJAX досить стандартний. Ми визначаємо тип даних як JSON – це важливо, інакше jQuery UI Autocomplete не зможе проаналізувати результати. Оскільки urlми отримуємо доступ ajax_urlдо глобальної змінної, яку ми локалізували до нашого сценарію раніше; AutocompleteSearch. І як dataми передаємо об’єкт інформації. Властивість actionє обов’язковою та необхідною для наступного кроку – визначення цього конкретного запиту AJAX у PHP. Ми також передаємо введений термін у input і nonce з метою безпеки.

Це все для sourcesвласності. Є ще одна річ, яку нам потрібно додати в наш сценарій автозаповнення. За замовчуванням у jQuery UI Autocomplete вибір елемента просто автоматично заповнює введені дані вибраним елементом. Ми хочемо переспрямовувати користувача на URL-адресу публікації під час вибору елемента зі списку. Отже, ми додаємо функцію до selectвластивості:

                ...
                success: function(data) {
                    response(data);
                }
            });
        },      
        select: function(event, ui) {
            window.location.href = ui.item.link;
        },
    });
});

У масиві елементів, який ми повернемо після виклику AJAX (ми напишемо це далі), кожен елемент є об’єктом із властивостями. Ми додамо спеціальну linkвластивість до кожного елемента (ui.item), яка міститиме постійні посилання на кожну публікацію. Ми передаємо цю URL-адресу, на [window.location.href](https://www.w3schools.com/js/js_window_location.asp)яку ініціюватиметься переспрямування браузера.

І це все для частини Javascript! Все, що залишилося, це написати частину PHP, яка слухає запити AJAX з дією autocompleteSearch.

Повернення результатів із PHP до запитів AJAX

Щоб написати функції, які відповідають на певні запити AJAX, ми використовуємо хуки wp_ajax_{action}(відвідувачі, які ввійшли в систему) і wp_ajax_nopriv_{action}(відвідувачі, які не ввійшли в систему). Ми визначили дію, як autocompleteSearchу нашому запиті AJAX вище. Зверніться до моєї публікації, яка пояснює, як працює AJAX у WordPress, якщо ви з цим не знайомі.

Давайте налаштуємо це в functions.php(або в іншому місці PHP, де ви додаєте свій код):

add_action('wp_ajax_nopriv_autocompleteSearch', 'awp_autocomplete_search');
add_action('wp_ajax_autocompleteSearch', 'awp_autocomplete_search');
function awp_autocomplete_search() {
    // echo result
    die();
}

За допомогою наведеного вище коду ми підключаємо ту саму функцію до двох хуків AJAX. У всіх функціях, які підключені до хуків AJAX wp_ajax, ми повинні переконатися, що завжди die()або exitв кінці, щоб ми не повторювали небажаний вихід. Я використовую [wp_die](https://developer.wordpress.org/reference/functions/wp_die/)()функцію WordPress.

Ми можемо отримати передані дані з Javascript за допомогою $_REQUEST(працює як для запитів GET, так і для POST). У нашому коді Javascript ми передали введений термін у ключ " term". Це означає, що ми можемо отримати його значення в $_REQUEST['term']. Потім ми можемо виконати запит на основі цього. Пам’ятайте, що ми хочемо повертати лише результати, які відповідають цьому пошуковому терміну.

Це ще один пункт, де ви можете повністю змінити та налаштувати код відповідно до своїх потреб. Цей підручник виконуватиме стандартний запит до публікацій і сторінок, але ви можете налаштувати запит або виконати зовсім інший запит до інших даних. Можливо, ви віддаєте перевагу або потребуєте замість цього виконати запит SQL вручну (це, звичайно, більш ефективно використовувати пам’ять). Важливою частиною тут є масив, який ми повторюємо в кінці, який аналізується нашим кодом автозаповнення Javascript.

Спочатку ми перевіряємо, чи був одноразовий номер дійсним для встановлення певної безпеки наших викликів AJAX. Ми можемо зробити це, викликавши функцію [check_ajax_referer](https://developer.wordpress.org/reference/functions/check_ajax_referer/)(). Я також додав код, щоб гарантувати, що ми не виконуємо важкий запит, якщо повернутий пошуковий термін був порожнім. Потім ми повинні повернути порожній масив, закодований у форматі json.

Наведений вище приклад коду виконує [WP_Query](https://developer.wordpress.org/reference/classes/wp_query/)пошук за введеним терміном. Нам потрібно встановити posts_per_pageas, -1щоб гарантувати повернення всіх збігів. Перегляньте документацію, WP_Queryякщо ви хочете додатково налаштувати запит.

Потім ми переглядаємо результати (рядок #17) і заповнюємо масив збігами (рядок #19-23). Функція автозаповнення jQuery UI вимагає як мінімум можливості вказувати label, що має відображатися у вікні автозаповнення. Ми також передаємо постійні посилання в ключі «link», який ми використовуємо в нашому коді Javascript для перенаправлення користувача.

Нарешті, у рядку #27ми повторюємо згенерований масив як JSON за допомогою [json_encode](https://www.php.net/manual/en/function.json-encode.php)().

З цією частиною PHP наше автозаповнення має працювати! Оновіть свій сайт і спробуйте!

Додаткові покращення

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

Одним із рішень є додавання властивості minLengthдо autocomplete()функції в Javascript. Ця властивість запускатиме вікно автозаповнення лише після введення певної кількості символів. Як приклад, ми можемо вимагати щонайменше 3 символи перед запуском автозаповнення:

        ...
        select: function(event, ui) {
            window.location.href = ui.item.link;
        },
        minLength: 3,
    });
});

jQuery UI Autocomplete пропонує інше рішення тут. Він показує приклад додавання трохи CSS, щоб додати фіксовану висоту та внутрішню смугу прокручування у полі автозаповнення.

Висновок і повний код

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

Ось остаточний код повністю:

jQuery(function($) {
    $('.search-form .search-field').autocomplete({
        source: function(request, response) {
            $.ajax({
                dataType: 'json',
                url: AutocompleteSearch.ajax_url,
                data: {
                    term: request.term,
                    action: 'autocompleteSearch',
                    security: AutocompleteSearch.ajax_nonce,
                },
                success: function(data) {
                    response(data);
                }
            });
        },
        select: function(event, ui) {
            window.location.href = ui.item.link;
        },
    });
});