Создание автозаполнения поиска в WordPress с помощью кода

Это руководство предназначено для тех, кто хочет внедрить автозаполнение поиска в WordPress, где мы полностью контролируем возвращаемые совпадения.

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

Что мы будем делать

Автозаполнение — это окно пользовательского интерфейса, которое появляется под полем поиска и показывает совпадения при вводе. При нажатии на совпадение браузер отправит вас на постоянную ссылку этого сообщения. Это обеспечивает конечному пользователю более быстрый способ навигации по вашему контенту, поскольку ему не нужно будет делать дополнительный обход на странице результатов поиска. Мы будем использовать AJAX для постоянного обновления совпадений, пока пользователь печатает.

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

Настройка кода

Вам нужно будет добавить код либо в functions.phpPHP-файл темы, либо в активный файл плагина. Этот учебник основан на добавлении его в тему. Настройте пути в соответствии с вашим проектом.

Первым шагом является создание файла Javascript, который будет содержать наш код для запуска автозаполнения. Что касается этого урока, я создам пустой autocomplete.jsфайл в assets/js/папке моей темы. Место, куда вы поместите свой файл, зависит от вас, просто не забудьте настроить указанные ниже пути. Мы вернемся к этому файлу после того, как правильно поставим его в очередь в WordPress.

Постановка скриптов и стилей в очередь

Нам нужно поставить в очередь наш файл Javascript автозаполнения, а также убедиться, что поставлены в очередь автозаполнение jQuery и jQuery UI. Кроме того, WordPress не включает стилей для библиотек пользовательского интерфейса jQuery, поэтому нам также необходимо поставить в очередь таблицу стилей для пользовательского интерфейса jQuery из 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 в наш экземпляр WordPress.

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

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_localize_script('autocomplete-search', 'AutocompleteSearch', [
        'ajax_url' => admin_url('admin-ajax.php'),
        'ajax_nonce' => wp_create_nonce('autocompleteSearchNonce')
    ]);
});

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

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

add_action('wp_enqueue_scripts', function() {
    ...
 
    $wp_scripts = wp_scripts();
    wp_enqueue_style('jquery-ui-css',
        '//ajax.googleapis.com/ajax/libs/jqueryui/'. $wp_scripts->registered['jquery-ui-autocomplete']->ver. '/themes/smoothness/jquery-ui.css',
        false, null, false
    );
});

Мы используем [wp_enqueue_style](https://developer.wordpress.org/reference/functions/wp_enqueue_style/)()для регистрации и добавления новой таблицы стилей с предоставленным путем CDN в качестве второго аргумента. Чтобы получить действительный номер версии пользовательского интерфейса jQuery, мы используем информацию, предоставленную функцией [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, мы узнаем, что нам нужно создать селектор 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. Мы также передаем введенный термин во входные данные и одноразовый номер в целях безопасности.

Это все, что касается 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. Во всех функциях, которые подключены к хукам wp_ajax AJAX, мы должны убедиться, что всегда die()или exitв конце, чтобы мы не выводили нежелательный вывод. Я использую [wp_die](https://developer.wordpress.org/reference/functions/wp_die/)()функцию WordPress.

Мы можем получить переданные данные из Javascript, используя $_REQUEST(работает как для GET, так и для POST-запросов). В нашем коде Javascript мы передали введенный термин в ключе ‘ term‘. Это означает, что мы можем получить его значение в $_REQUEST['term']. Затем мы можем выполнить запрос на основе этого. Помните, что мы хотим возвращать только те результаты, которые соответствуют этому поисковому запросу.

Это еще один момент, когда вы можете полностью изменить и настроить код в соответствии с вашими потребностями. В этом руководстве будет выполняться стандартный запрос к записям и страницам, но вы можете настроить запрос или выполнить совершенно другой запрос к другим данным. Возможно, вы предпочитаете или должны вместо этого выполнять SQL-запрос вручную (это, безусловно, более эффективно использует память). Важнейшей частью здесь является массив, который мы повторяем в конце, который анализируется нашим кодом автозаполнения Javascript.

add_action('wp_ajax_nopriv_autocompleteSearch', 'awp_autocomplete_search');
add_action('wp_ajax_autocompleteSearch', 'awp_autocomplete_search');
function awp_autocomplete_search() {
    check_ajax_referer('autocompleteSearchNonce', 'security');
    $search_term = $_REQUEST['term'];
    if (!isset($_REQUEST['term'])) {
        echo json_encode([]);
    }
    $suggestions = [];
    $query = new WP_Query([
        's' => $search_term,
        'posts_per_page' => -1,
    ]);
    if ($query->have_posts()) {
        while ($query->have_posts()) {
            $query->the_post();
            $suggestions[] = [
                'id' => get_the_ID(),
                'label' => get_the_title(),
                'link' => get_the_permalink()
            ];
        }
        wp_reset_postdata();
    }
    echo json_encode($suggestions);
    wp_die();
}

Сначала мы проверяем, был ли одноразовый номер действительным, чтобы обеспечить некоторую безопасность наших вызовов 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 требует как минимум свойства 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, но может быть полезно для поиска по определенному контенту или в специальных шаблонах!

Вот окончательный код полностью:

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_localize_script('autocomplete-search', 'AutocompleteSearch', [
        'ajax_url' => admin_url('admin-ajax.php'),
        'ajax_nonce' => wp_create_nonce('autocompleteSearchNonce')
    ]);
 
    $wp_scripts = wp_scripts();
    wp_enqueue_style('jquery-ui-css',
        '//ajax.googleapis.com/ajax/libs/jqueryui/'. $wp_scripts->registered['jquery-ui-autocomplete']->ver. '/themes/smoothness/jquery-ui.css',
        false, null, false
    );
});
 
add_action('wp_ajax_nopriv_autocompleteSearch', 'awp_autocomplete_search');
add_action('wp_ajax_autocompleteSearch', 'awp_autocomplete_search');
function awp_autocomplete_search() {
    check_ajax_referer('autocompleteSearchNonce', 'security');
 
    $search_term = $_REQUEST['term'];
    if (!isset($_REQUEST['term'])) {
        echo json_encode([]);
    }
 
    $suggestions = [];
    $query = new WP_Query([
        's' => $search_term,
        'posts_per_page' => -1,
    ]);
    if ($query->have_posts()) {
        while ($query->have_posts()) {
            $query->the_post();
            $suggestions[] = [
                'id' => get_the_ID(),
                'label' => get_the_title(),
                'link' => get_the_permalink()
            ];
        }
        wp_reset_postdata();
    }
    echo json_encode($suggestions);
    wp_die();
}

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;
        },
    });
});