Ten samouczek jest dla tych, którzy chcą zaimplementować wyszukiwanie autouzupełniania w WordPress, gdzie mamy pełną kontrolę nad zwracanymi dopasowaniami.
Zastosujemy autouzupełnianie do standardowego wyszukiwania WordPress, ale kod jest bardzo elastyczny, dzięki czemu możesz dostosować zapytanie do swoich potrzeb. Niezależnie od tego, czy jest to bardziej szczegółowe zapytanie według niestandardowego typu postu, meta postu, kategorii lub zapytania dotyczące zupełnie innego rodzaju treści, takich jak użytkownicy lub coś ręcznego z bazy danych. Możesz również łatwo zastosować autouzupełnianie do niestandardowych danych wejściowych wyszukiwania zamiast standardowego wyszukiwania WordPress.
Co zrobimy
Autouzupełnianie to pole interfejsu użytkownika, które pojawia się pod polem wyszukiwania, pokazując dopasowania podczas pisania. Po kliknięciu na dopasowanie przeglądarka prześle Ci bezpośredni link do tego posta. Zapewnia to użytkownikowi końcowemu szybszy sposób poruszania się po treści, ponieważ nie będzie musiał omijać strony wyników wyszukiwania. Użyjemy AJAX do ciągłej aktualizacji dopasowań podczas pisania przez użytkownika.
Autouzupełnianie jest generowane za pomocą jQuery UI Autocomplete, skryptu domyślnie zawartego w WordPressie.
Konfigurowanie kodu
Będziesz musiał dodać kod w functions.phppliku PHP motywu lub aktywnej wtyczki. Ten samouczek polega na dodaniu go do motywu. Dostosuj ścieżki do swojego projektu.
Pierwszym krokiem jest utworzenie pliku JavaScript, który będzie zawierał nasz kod uruchamiający autouzupełnianie. Jeśli chodzi o ten samouczek, utworzę pusty autocomplete.jsplik w folderze mojego motywu assets/js/. To, gdzie umieścisz plik, zależy od Ciebie, pamiętaj tylko o dostosowaniu poniższych ścieżek. Powrócimy do tego pliku po prawidłowym umieszczeniu go w kolejce w WordPressie.
Kolejkowanie skryptów i stylów
Musimy umieścić w kolejce nasz autouzupełniający plik JavaScript, a także upewnić się, że wstawiliśmy do kolejki jQuery i jQuery UI Autocomplete. Ponadto WordPress nie zawiera żadnych stylów dla bibliotek jQuery UI, więc musimy również zakolejkować arkusz stylów dla jQuery UI z Google CDN. Jest to oczywiście opcjonalne. Możesz dodać CSS w inny sposób, a może wolisz sam go ostylować.
Wszystkie skrypty i style umieścimy w kolejce w funkcji podłączonej do 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);
});Powyższe [wp_enqueue_script](https://developer.wordpress.org/reference/functions/wp_enqueue_script/)()wywołanie funkcji doda nasz nowo utworzony plik JavaScript z poprawnymi zależnościami (tablica jako trzeci parametr). Gwarantuje to, że WordPress doda skrypty jQuery i jQuery UI Autocomplete w naszej instancji WordPress.
Następnie musimy podać kilka zmiennych, do których możemy uzyskać dostęp z naszego skryptu autouzupełniania. Musimy znać adres URL AJAX, a także chcemy dodać jednorazową wartość dla bezpieczeństwa. Możemy to zrobić za pomocą [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')
]);
});Funkcja wp_localize_script()utworzy globalną zmienną JavaScript AutocompleteSearchz dwiema właściwościami; ajax_urli ajax_nonce. Dzięki temu możemy w naszym autouzupełnianym pliku JavaScript pobrać na przykład wartość adresu URL WordPress AJAX z AutocompleteSearch.ajax_url.
Na koniec musimy dodać trochę stylizacji. Jak wspomniano, WordPress nie zawiera żadnych stylów jQuery UI, więc musimy dodać trochę sami. Zdecydowałem się dodać arkusz stylów przez Google CDN. Ale musimy znać numer wersji jQuery UI, aby pobrać arkusz stylów. Moglibyśmy zakodować numer wersji na sztywno, ale nie jestem fanem zapisywania niczego na sztywno. Poniżej znajdziesz fajną sztuczkę, która pozwoli wyprzedzić informacje o wersji jQuery UI przechowywane w WordPressie.
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
);
});Używamy [wp_enqueue_style](https://developer.wordpress.org/reference/functions/wp_enqueue_style/)()do zarejestrowania i dodania nowego arkusza stylów z podaną ścieżką CDN jako drugim argumentem. W celu pobrania prawidłowego numeru wersji jQuery UI korzystamy z informacji dostarczonych z funkcji [wp_scripts](https://developer.wordpress.org/reference/functions/wp_scripts/)().
I to wszystko, czego potrzebujemy do kolejkowania skryptów!
Pisanie autouzupełniania JavaScript
Wróćmy do naszych autocomplete.jsakt. Wiemy, że kiedy ten skrypt jest załadowany, jQuery i jQuery UI Autocomplete są już załadowane, a także mamy dostęp do zmiennej globalnej z niezbędnymi informacjami. Zacznijmy od skonfigurowania funkcji gotowości dokumentu jQuery, aby upewnić się, że nasz kod zostanie uruchomiony po przygotowaniu DOM.
jQuery(function($) {
// All code in here
});Jeśli odwołamy się do dokumentacji autouzupełniania jQuery UI, dowiemy się, że musimy utworzyć selektor jQuery nakierowany na pole wejściowe i uruchomić na autocomplete()nim funkcję.
Jest to punkt, w którym możesz dostosować kod do swoich potrzeb. Ten samouczek zastosuje autouzupełnianie do standardowego pola wyszukiwania WordPress (które jest zwykle dodawane do motywu poprzez dołączenie szablonu wyszukiwania lub jako widżet). Nazwy klas danych wejściowych wyszukiwania mogą się różnić w zależności od motywu. Ale możesz chcieć kierować na niestandardowe pole wprowadzania lub wyszukiwać w specjalnym szablonie. Wszystko, co musisz zrobić, to zmienić selektor jQuery tak, aby kierować na dane wejściowe, które chcesz.
W moim motywie standardowe pole wyszukiwania WordPress ma klasę .search-field. Dodaję również nazwę klasy formularza nadrzędnego, aby jeszcze bardziej ją zawęzić, więc nie ryzykujemy zastosowania autouzupełniania do czegoś innego przy użyciu tej samej klasy.
Zgodnie z dokumentacją Autocomplete możemy wykonać wywołanie AJAX we właściwości source(która musi zwrócić tablicę elementów do wyświetlenia w autouzupełnianiu). W tym celu użyjemy funkcji 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);
}
});
},
});
});W wierszu #2mówimy jQuery UI Autocomplete na którym polu wejściowym chcemy zastosować autouzupełnianie. Zmień ten selektor, aby dopasować go do swoich potrzeb.
W najprostszej formie Autouzupełnianie oczekuje tablicy obiektów pozycji do sourcewłaściwości. Tutaj tworzymy funkcję z dwoma parametrami; requestzawiera informacje o wprowadzonej przez nas wartości (request.term) oraz responsefunkcji zwrotnej, którą musimy wywołać i podać dane. To właśnie robimy w funkcji AJAX successw line #13.
Samo wywołanie AJAX jest dość standardowe. Definiujemy typ danych jako JSON – jest to ważne, w przeciwnym razie autouzupełnianie jQuery UI nie będzie w stanie przeanalizować wyników. Ponieważ urluzyskujemy dostęp ajax_urldo zmiennej globalnej, zlokalizowaliśmy ją wcześniej w naszym skrypcie; AutocompleteSearch. I jak datamijamy obiekt informacji. Właściwość actionjest obowiązkowa i niezbędna do następnego kroku – czyli identyfikacji tego konkretnego żądania AJAX w PHP. Przekazujemy również wprowadzony termin w wejściu i nonce ze względów bezpieczeństwa.
To wszystko na sourceswłasność. Jest jeszcze jedna rzecz, którą musimy dodać do naszego skryptu autouzupełniania. Domyślnie w jQuery UI Autocomplete wybieranie elementu po prostu automatycznie wypełnia dane wejściowe wybranym elementem. Chcemy przekierować użytkownika na adres URL posta przy wyborze pozycji z listy. Więc dodajemy funkcję do selectwłaściwości:
...
success: function(data) {
response(data);
}
});
},
select: function(event, ui) {
window.location.href = ui.item.link;
},
});
});W tablicy elementów, które zwrócimy z naszego wywołania AJAX (o czym napiszemy dalej), każdy element jest obiektem z właściwościami. Do każdego elementu () dodamy niestandardową linkwłaściwość ui.item, która będzie zawierała linki bezpośrednie do każdego posta. Przekazujemy ten adres URL, na [window.location.href](https://www.w3schools.com/js/js_window_location.asp)który wywoła przekierowanie przeglądarki.
I to wszystko dla części JavaScript! Pozostaje tylko napisać część PHP, która nasłuchuje żądań AJAX za pomocą akcji autocompleteSearch.
Zwracanie wyników w PHP do żądań AJAX
W celu napisania funkcji odpowiadających na konkretne żądania AJAX wykorzystujemy hooki wp_ajax_{action}(zalogowani goście) i wp_ajax_nopriv_{action}(niezalogowani goście). Zdefiniowaliśmy akcję tak, jak autocompleteSearchw powyższym żądaniu AJAX. Zapoznaj się z moim postem, który wyjaśnia, jak AJAX działa w WordPressie, jeśli nie znasz tego.
Ustawmy to w functions.php(lub gdziekolwiek w PHP dodasz swój kod):
add_action('wp_ajax_nopriv_autocompleteSearch', 'awp_autocomplete_search');
add_action('wp_ajax_autocompleteSearch', 'awp_autocomplete_search');
function awp_autocomplete_search() {
// echo result
die();
}W powyższym kodzie podpinamy tę samą funkcję do dwóch hooków AJAX. We wszystkich funkcjach, które są zaczepione do zaczepów wp_ajax AJAX, musimy upewnić się, że zawsze die()lub exitna końcu, aby nie wywoływać niepożądanego wyniku. Korzystam z [wp_die](https://developer.wordpress.org/reference/functions/wp_die/)()funkcji WordPressa.
Możemy pobrać przekazane dane z Javascriptu $_REQUEST(działa zarówno dla żądań GET, jak i POST). W naszym kodzie JavaScript przekazaliśmy termin wprowadzony w kluczu „ term". Oznacza to, że możemy pobrać jego wartość w $_REQUEST['term']. Na tej podstawie możemy wykonać zapytanie. Pamiętaj, że chcemy zwracać tylko wyniki pasujące do tego wyszukiwanego hasła.
To kolejny punkt, w którym możesz w pełni zmienić i dostosować kod do swoich potrzeb. Ten samouczek wykona standardowe zapytanie na postach i stronach, ale możesz dostosować zapytanie lub wykonać zupełnie inne zapytanie na różnych danych. Być może wolisz lub musisz wykonać ręczne zapytanie SQL (z pewnością jest to bardziej wydajne pod względem pamięci). Kluczową częścią jest tablica, której echo pojawia się na końcu, która jest analizowana przez kod autouzupełniania naszego JavaScriptu.
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();
}Najpierw sprawdzamy, czy numer jednorazowy był prawidłowy, aby zapewnić pewne bezpieczeństwo naszych wywołań AJAX. Możemy to zrobić, wywołując funkcję [check_ajax_referer](https://developer.wordpress.org/reference/functions/check_ajax_referer/)(). Dodałem również kod, aby upewnić się, że nie wykonamy dużego żądania, jeśli zwrócony wyszukiwany termin jest pusty. Powinniśmy wtedy zwrócić pustą tablicę zakodowaną w formacie json.
Powyższy przykładowy kod wykonuje a [WP_Query](https://developer.wordpress.org/reference/classes/wp_query/)z wyszukiwaniem wprowadzonego terminu. Musimy ustawić posts_per_pagetak, -1aby zapewnić, że zwrócimy wszystkie mecze. Zapoznaj się z dokumentacją WP_Query, jeśli chcesz jeszcze bardziej ulepszyć zapytanie.
Następnie przeglądamy wyniki w pętli (line #17) i wypełniamy tablicę dopasowaniami (line #19-23). Autouzupełnianie jQuery UI wymaga co najmniej uprawnień labeldo oznaczania, co powinno być wyświetlane w polu autouzupełniania. Przekazujemy również permalinki w kluczu „ link„, którego używamy w naszym kodzie JavaScript do przekierowywania użytkownika.
Na koniec w linii #27powtarzamy wygenerowaną tablicę jako JSON za pomocą [json_encode](https://www.php.net/manual/en/function.json-encode.php)().
Po zainstalowaniu tej części PHP nasze autouzupełnianie powinno działać! Odśwież swoją witrynę i wypróbuj ją!
Opcjonalne ulepszenia
Jednym z powszechnych problemów jest zbyt duża liczba dopasowań i zbyt duże pole autouzupełniania. Są na to dwa rozwiązania.
Jednym z rozwiązań jest dodanie właściwości minLengthdo autocomplete()funkcji w JavaScript. Ta właściwość uruchomi okno autouzupełniania dopiero po wprowadzeniu określonej liczby znaków. Jako przykład możemy wymagać co najmniej 3 znaków przed uruchomieniem autouzupełniania:
...
select: function(event, ui) {
window.location.href = ui.item.link;
},
minLength: 3,
});
});jQuery UI Autocomplete proponuje tutaj inne rozwiązanie. Pokazuje przykład dodania odrobiny CSS, aby dodać stałą wysokość i wewnętrzny pasek przewijania w polu autouzupełniania.
Wniosek i kompletny kod
Pomyślnie dodaliśmy autouzupełnianie do funkcji wyszukiwania WordPressa, gdzie mamy pełną kontrolę nad zwracanymi dopasowaniami. Daje odwiedzającym szybszy sposób poruszania się po treści, ponieważ kliknięcie dopasowania spowoduje przekierowanie bezpośrednio do posta, zamiast najpierw objazdu strony wyników wyszukiwania. Wdrożenie autouzupełniania może nie zawsze mieć sens we wszystkich witrynach WordPress, ale może być świetne do wyszukiwania określonych treści lub w specjalnych szablonach!
Oto ostateczny kod w całości:
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;
},
});
});