Widżet wyszukiwania udostępnia dostosowywany interfejs wyszukiwania dla aplikacji internetowych. Widżet wymaga tylko niewielkiej ilości kodu HTML i JavaScriptu do zaimplementowania i umożliwia korzystanie z popularnych funkcji wyszukiwania, takich jak aspekty i podział na strony. Możesz też dostosowywać fragmenty interfejsu za pomocą CSS i JavaScriptu.
Jeśli potrzebujesz większej elastyczności niż zapewnia widżet, rozważ użycie interfejsu Query API. Informacje o tworzeniu interfejsu wyszukiwania za pomocą interfejsu Query API znajdziesz w artykule Tworzenie interfejsu wyszukiwania za pomocą interfejsu Query API.
Utwórz interfejs wyszukiwania
Utworzenie interfejsu wyszukiwania składa się z kilku kroków:
- Konfigurowanie wyszukiwarki
- Wygeneruj identyfikator klienta dla aplikacji
- Dodaj znaczniki HTML pola wyszukiwania i wyników
- Wczytaj widżet na stronie
- Inicjowanie widżetu
Konfigurowanie wyszukiwarki
Każdy interfejs wyszukiwania musi mieć zdefiniowaną w konsoli administracyjnej wyszukiwarkę. Wyszukiwarka udostępnia dodatkowe informacje na temat zapytania, takie jak źródła danych, aspekty i ustawienia jakości wyszukiwania.
Aby dowiedzieć się, jak utworzyć wyszukiwarkę, zapoznaj się z informacjami o tworzeniu niestandardowego środowiska wyszukiwania.
Wygeneruj identyfikator klienta dla aplikacji
Oprócz czynności opisanych w sekcji Konfigurowanie dostępu do interfejsu Google Cloud Search API musisz też wygenerować identyfikator klienta dla aplikacji internetowej.
Podczas konfigurowania projektu:
- Wybierz typ klienta Przeglądarka internetowa.
- Podaj identyfikator URI źródła aplikacji.
- Zapisz utworzony identyfikator klienta. Do wykonania kolejnych kroków będzie Ci potrzebny identyfikator klienta. Widżet nie wymaga tajnego klucza klienta.
Więcej informacji znajdziesz w artykule na temat protokołu OAuth 2.0 dla aplikacji internetowej po stronie klienta.
Dodaj znaczniki HTML
Do działania widżetu wymagana jest niewielka ilość kodu HTML. Musisz podać:
- Element
input
pola wyszukiwania. - Element, do którego będzie zakotwiczone wyskakujące okienko sugestii.
- Element zawierający wyniki wyszukiwania.
- (Opcjonalnie) Podaj element, który będzie zawierał elementy sterujące aspektów.
Poniższy fragment kodu HTML zawiera kod HTML widżetu wyszukiwania. Elementy, które mają być powiązane, są oznaczone atrybutem id
:
Wczytywanie widżetu
Widżet jest ładowany dynamicznie przez skrypt wczytujący. Aby uwzględnić moduł wczytywania, użyj tagu <script>
w podany niżej sposób:
W tagu skryptu musisz podać wywołanie zwrotne onload
. Funkcja jest wywoływana, gdy program wczytywania będzie gotowy. Gdy moduł wczytywania będzie gotowy, kontynuuj wczytywanie widżetu, wywołując metodę gapi.load()
, aby wczytać klienta interfejsu API, Logowanie przez Google i Cloud Search.
Funkcja initializeApp()
jest wywoływana po załadowaniu wszystkich modułów.
Inicjowanie widżetu
Najpierw zainicjuj bibliotekę klienta, wywołując metodę gapi.client.init()
lub gapi.auth2.init()
z wygenerowanym identyfikatorem klienta i zakresem https://www.googleapis.com/auth/cloud_search.query
. Następnie użyj klas gapi.cloudsearch.widget.resultscontainer.Builder
i gapi.cloudsearch.widget.searchbox.Builder
do skonfigurowania widżetu i powiązania go z elementami HTML.
Poniższy przykład pokazuje, jak zainicjować widżet:
Powyższy przykład odwołuje się do 2 zmiennych na potrzeby konfiguracji zdefiniowanej jako:
Dostosowywanie procesu logowania
Domyślnie widżet prosi użytkowników o zalogowanie się i autoryzację aplikacji w momencie, gdy rozpoczynają wpisywanie zapytania. Możesz używać Logowania przez Google w witrynach, aby zapewnić użytkownikom większą wygodę logowania.
Bezpośrednie autoryzowanie użytkowników
Użyj funkcji Zaloguj się przez Google, aby monitorować stan logowania użytkownika oraz logować się lub wylogowywać użytkowników w razie potrzeby. Na przykład w tym przykładzie zaobserwowano stan isSignedIn
służący do monitorowania zmian w logowaniu się oraz wykorzystuje metodę GoogleAuth.signIn()
do inicjowania logowania po kliknięciu przycisku:
Więcej informacji znajdziesz w artykule Logowanie przez Google.
Automatycznie loguj użytkowników
Możesz jeszcze bardziej uprościć logowanie, autoryzując aplikację w imieniu użytkowników w organizacji. Ta metoda jest też przydatna, gdy używasz Cloud Identity Aware Proxy do ochrony aplikacji.
Więcej informacji znajdziesz w artykule Korzystanie z Logowania przez Google w aplikacjach IT.
Dostosowywanie interfejsu
Wygląd interfejsu wyszukiwania możesz zmienić, korzystając z różnych metod:
- Zastąp style za pomocą CSS
- Udekoruj elementy adapterem
- Tworzenie elementów niestandardowych za pomocą adaptera
Zastąp style za pomocą CSS
Widżet wyszukiwania zawiera własny styl CSS do określania stylu sugestii i elementów wyników, a także elementy sterujące podziału na strony. W razie potrzeby możesz zmienić ich styl.
Podczas wczytywania widżet wyszukiwania dynamicznie wczytuje swój domyślny arkusz stylów. Dzieje się tak po wczytaniu arkuszy stylów aplikacji, co zwiększa priorytet reguł. Aby mieć pewność, że Twoje własne style mają pierwszeństwo przed stylami domyślnymi, użyj selektorów elementów nadrzędnych, aby zwiększyć specyfikę reguł domyślnych.
Na przykład ta reguła nie będzie działać, jeśli zostanie załadowana w statycznym tagu link
lub style
w dokumencie.
.cloudsearch_suggestion_container {
font-size: 14px;
}
Zamiast tego wyklucz regułę za pomocą identyfikatora lub klasy kontenera nadrzędnego zadeklarowanego na stronie.
#suggestions_anchor .cloudsearch_suggestion_container {
font-size: 14px;
}
Listę klas pomocy i przykładowy kod HTML wygenerowany przez widżet znajdziesz w dokumentacji obsługiwanych klas CSS.
Udekoruj elementy adapterem
Aby udekorować element przed renderowaniem, utwórz i ponownie użyj adaptera, który stosuje jedną z metod dekorowania, np. decorateSuggestionElement
lub decorateSearchResultElement.
.
Na przykład poniższe adaptery dodają klasę niestandardową do elementów sugestii i wyników.
Aby zarejestrować adapter podczas inicjowania widżetu, użyj metody setAdapter()
odpowiedniej klasy Builder
:
Dekoracje mogą zmieniać atrybuty elementu kontenera oraz elementów podrzędnych. Elementy podrzędne można dodawać lub usuwać podczas dekoracji. Jeśli jednak wprowadzasz zmiany strukturalne elementów, rozważ utworzenie ich bezpośrednio, a nie dekorowanie.
Tworzenie elementów niestandardowych za pomocą adaptera
Aby utworzyć element niestandardowy dla sugestii, kontenera aspektu lub wyniku wyszukiwania, utwórz i zarejestruj adapter, który implementuje interfejs createSuggestionElement
, createFacetResultElement
lub createSearchResultElement
.
Poniższe adaptery pokazują tworzenie niestandardowych elementów sugestii i wyników wyszukiwania za pomocą tagów HTML <template>
.
Aby zarejestrować adapter podczas inicjowania widżetu, użyj metody setAdapter()
odpowiedniej klasy Builder
:
Tworzenie niestandardowych elementów aspektów za pomocą createFacetResultElement
podlega kilku ograniczeniom:
- Musisz dołączyć klasę CSS
cloudsearch_facet_bucket_clickable
do elementu, który klikają użytkownicy, aby przełączyć zasobnik. - Każdy zasobnik musisz umieścić w elemencie zawierającym klasę CSS
cloudsearch_facet_bucket_container
. - Nie można wyrenderować zasobników w innej kolejności niż występuje w odpowiedzi.
Na przykład ten fragment kodu renderuje aspekty za pomocą linków zamiast pól wyboru.
Dostosowywanie działania wyszukiwania
Ustawienia wyszukiwarki reprezentują domyślną konfigurację interfejsu wyszukiwania i są statyczne. Aby wdrożyć filtry dynamiczne lub aspekty, np. umożliwić użytkownikom przełączanie źródeł danych, możesz zastąpić ustawienia wyszukiwarki przez przechwycenie żądania wyszukiwania za pomocą adaptera.
Zaimplementuj adapter z metodą interceptSearchRequest
, aby modyfikować żądania wysyłane do interfejsu Search API przed wykonaniem.
Na przykład ten adapter przechwytuje żądania ograniczenia zapytań do źródła wybranego przez użytkownika:
Aby zarejestrować adapter podczas inicjowania widżetu, użyj metody setAdapter()
podczas tworzenia komponentu ResultsContainer
.
Ten kod HTML służy do wyświetlania pola wyboru do filtrowania według źródeł:
Podany niżej kod nasłuchuje zmiany, ustawia wybór i w razie potrzeby wykonuje zapytanie ponownie.
Możesz też przechwycić odpowiedź na wyszukiwanie, implementując w adapterze interceptSearchResponse
.
Przypnij wersję interfejsu API
Domyślnie widżet używa najnowszej stabilnej wersji interfejsu API. Aby zablokować konkretną wersję, przed zainicjowaniem widżetu ustaw parametr konfiguracji cloudsearch.config/apiVersion
na preferowaną wersję.
Jeśli wersja interfejsu API jest nieskonfigurowana lub ustawiona na nieprawidłową wartość, domyślnie będzie to 1.0.
Przypnij wersję widżetu
Aby uniknąć nieoczekiwanych zmian w interfejsach wyszukiwania, ustaw parametr konfiguracji cloudsearch.config/clientVersion
w podany niżej sposób:
gapi.config.update('cloudsearch.config/clientVersion', 1.1);
Jeśli wersja widżetu jest nieskonfigurowana lub ustawiona jest nieprawidłowa wartość, domyślnie będzie to 1.0.
Zabezpieczanie interfejsu wyszukiwania
Wyniki wyszukiwania zawierają informacje poufne. Postępuj zgodnie ze sprawdzonymi metodami zabezpieczania aplikacji internetowych, w szczególności przed atakami typu clickjacking.
Więcej informacji znajdziesz w dokumencie OWASP Guide Project
Włącz debugowanie
Użyj interceptSearchRequest
, aby włączyć debugowanie widżetu wyszukiwania. Na przykład:
if (!request.requestOptions) {
// Make sure requestOptions is populated
request.requestOptions = {};
}
// Enable debugging
request.requestOptions.debugOptions = {enableDebugging: true}
return request;