Das Such-Widget bietet eine anpassbare Suchoberfläche für Webanwendungen. Das Widget benötigt nur wenig HTML- und JavaScript-Code, um gängige Suchfunktionen wie Facetten und die Paginierung zu implementieren und zu aktivieren. Sie können auch Teile der Benutzeroberfläche mit CSS und JavaScript anpassen.
Wenn Sie mehr Flexibilität benötigen als vom Widget angeboten, sollten Sie die Query API verwenden. Informationen zum Erstellen einer Suchoberfläche mit der Query API finden Sie unter Suchoberfläche mit der Query API erstellen.
Suchoberfläche erstellen
Das Erstellen der Suchoberfläche erfordert mehrere Schritte:
- Suchanwendung konfigurieren
- Client-ID für die Anwendung generieren
- HTML-Markup für das Suchfeld und die Ergebnisse hinzufügen
- Widget auf der Seite laden
- Widget initialisieren
Suchanwendung konfigurieren
Für jede Suchoberfläche muss in der Admin-Konsole eine Suchanwendung definiert sein. Die Suchanwendung bietet zusätzliche Informationen für die Abfrage, z. B. Datenquellen, Facetten und Einstellungen für die Suchqualität.
Informationen zum Erstellen einer Suchanwendung finden Sie unter Benutzerdefinierte Suche erstellen.
Client-ID für die Anwendung generieren
Zusätzlich zu den Schritten unter Zugriff auf die Google Cloud Search API konfigurieren müssen Sie auch eine Client-ID für die Webanwendung generieren.
Gehen Sie beim Konfigurieren des Projekts so vor:
- Wählen Sie als Clienttyp Webbrowser aus.
- Geben Sie den Ursprungs-URI Ihrer App an.
- Notieren Sie sich die erstellte Client-ID. Sie benötigen die Client-ID, um die nächsten Schritte auszuführen. Der Clientschlüssel ist für das Widget nicht erforderlich.
Weitere Informationen finden Sie unter OAuth 2.0 für clientseitige Webanwendungen.
HTML-Markup hinzufügen
Damit das Widget funktioniert, ist etwas HTML-Code erforderlich. Sie müssen Folgendes angeben:
- Ein
input
-Element für das Suchfeld. - Ein Element zum Verankern des Vorschlags-Pop-ups.
- Ein Element, das die Suchergebnisse enthalten soll.
- (Optional) Geben Sie ein Element an, das die Facetten-Steuerelemente enthält.
Das folgende HTML-Snippet zeigt den HTML-Code für ein Such-Widget, wobei die zu bindenden Elemente durch ihr id
-Attribut identifiziert werden:
Widget laden
Das Widget wird über ein Ladeskript dynamisch geladen. Verwenden Sie das Tag <script>
wie hier gezeigt, um das Ladeprogramm einzubinden:
Du musst im Skript-Tag einen onload
-Callback angeben. Die Funktion wird aufgerufen, wenn der Loader bereit ist. Fahren Sie dann mit dem Laden des Widgets fort. Rufen Sie dazu gapi.load()
auf, um den API-Client, Google Log-in und Cloud Search zu laden.
Die Funktion initializeApp()
wird aufgerufen, nachdem alle Module geladen wurden.
Widget initialisieren
Initialisieren Sie zuerst die Clientbibliothek, indem Sie gapi.client.init()
oder gapi.auth2.init()
mit der generierten Client-ID und dem Bereich https://www.googleapis.com/auth/cloud_search.query
aufrufen. Verwenden Sie als Nächstes die Klassen gapi.cloudsearch.widget.resultscontainer.Builder
und gapi.cloudsearch.widget.searchbox.Builder
, um das Widget zu konfigurieren und an Ihre HTML-Elemente zu binden.
Das folgende Beispiel zeigt, wie das Widget initialisiert wird:
Im obigen Beispiel wird für die Konfiguration auf zwei Variablen verwiesen, die so definiert sind:
Anmeldung anpassen
Standardmäßig werden Nutzer vom Widget aufgefordert, sich anzumelden und die App zu autorisieren, wenn sie mit der Eingabe einer Abfrage beginnen. Mit Google Log-in für Websites können Sie Ihren Nutzern eine individuellere Anmeldung bieten.
Nutzer direkt autorisieren
Verwende Über Google anmelden, um den Anmeldestatus des Nutzers zu überwachen und Nutzer nach Bedarf an- oder abzumelden. Im folgenden Beispiel wird der Status isSignedIn
beobachtet, um Anmeldeänderungen zu beobachten, und verwendet die Methode GoogleAuth.signIn()
, um die Anmeldung über einen Klick auf eine Schaltfläche zu initiieren:
Weitere Informationen finden Sie unter Über Google anmelden.
Nutzer automatisch anmelden
Sie können die Anmeldung weiter optimieren, indem Sie die Anwendung im Namen der Nutzer in Ihrer Organisation vorab autorisieren. Diese Technik ist auch nützlich, wenn Sie Cloud Identity-Aware Proxy verwenden, um die Anwendung zu schützen.
Weitere Informationen finden Sie unter Google Log-in mit IT-Apps verwenden.
Benutzeroberfläche anpassen
Sie können die Darstellung der Suchoberfläche mithilfe einer Kombination verschiedener Verfahren ändern:
- Stile mit CSS überschreiben
- Elemente mit einem Adapter dekorieren
- Benutzerdefinierte Elemente mit einem Adapter erstellen
Stile mit CSS überschreiben
Das Such-Widget verfügt über einen eigenen CSS-Code, mit dem Sie Vorschlags- und Ergebniselemente sowie die Paginierungssteuerung gestalten können. Sie können diese Elemente nach Bedarf umgestalten.
Während des Ladevorgangs wird das Standard-Stylesheet des Such-Widgets dynamisch geladen. Dies geschieht, nachdem die Stylesheets der Anwendung geladen wurden, wodurch die Priorität der Regeln erhöht wird. Damit Ihre eigenen Stile Vorrang vor den Standardstile haben, verwenden Sie Ancestor-Selektoren, um die Standardregeln spezifischer zu gestalten.
Die folgende Regel hat beispielsweise keine Auswirkungen, wenn sie in ein statisches link
- oder style
-Tag im Dokument geladen wird.
.cloudsearch_suggestion_container {
font-size: 14px;
}
Qualifizieren Sie die Regel stattdessen mit der ID oder Klasse des auf der Seite deklarierten Ancestor-Containers.
#suggestions_anchor .cloudsearch_suggestion_container {
font-size: 14px;
}
Eine Liste der Supportklassen und des vom Widget erstellten Beispiel-HTML-Codes finden Sie in der Referenz zu unterstützten CSS-Klassen.
Elemente mit einem Adapter dekorieren
Wenn Sie ein Element vor dem Rendering dekorieren möchten, erstellen Sie einen Adapter, der eine der Dekorationsmethoden wie decorateSuggestionElement
oder decorateSearchResultElement.
implementiert, und reigsterieren Sie ihn neu.
Mit den folgenden Adaptern wird den Vorschlags- und Ergebniselementen beispielsweise eine benutzerdefinierte Klasse hinzugefügt.
Verwenden Sie die Methode setAdapter()
der jeweiligen Builder
-Klasse, um den Adapter beim Initialisieren des Widgets zu registrieren:
Sie können die Attribute des Containerelements sowie aller untergeordneten Elemente ändern. Untergeordnete Elemente können während der Dekoration hinzugefügt oder entfernt werden. Wenn Sie jedoch strukturelle Änderungen an den Elementen vornehmen, sollten Sie sie direkt erstellen, statt sie zu dekorieren.
Benutzerdefinierte Elemente mit einem Adapter erstellen
Wenn Sie ein benutzerdefiniertes Element für einen Vorschlag, einen Attributcontainer oder ein Suchergebnis erstellen möchten, erstellen und registrieren Sie einen Adapter, der createSuggestionElement
, createFacetResultElement
oder createSearchResultElement
entsprechend implementiert.
Die folgenden Adapter veranschaulichen, wie benutzerdefinierte Vorschlags- und Suchergebniselemente mithilfe von HTML-<template>
-Tags erstellt werden.
Verwenden Sie die Methode setAdapter()
der jeweiligen Builder
-Klasse, um den Adapter bei der Initialisierung des Widgets zu registrieren:
Das Erstellen benutzerdefinierter Attributelemente mit createFacetResultElement
unterliegt mehreren Einschränkungen:
- Sie müssen die CSS-Klasse
cloudsearch_facet_bucket_clickable
an das Element anhängen, auf das Nutzer klicken, um einen Bucket umzuschalten. - Sie müssen jeden Bucket in einem Element mit der CSS-Klasse
cloudsearch_facet_bucket_container
zusammenfassen. - Sie können die Buckets nicht in einer anderen Reihenfolge rendern, als sie in der Antwort angezeigt werden.
Mit dem folgenden Snippet werden beispielsweise Facetten mithilfe von Links anstelle von Kästchen gerendert.
Suchverhalten anpassen
Die Einstellungen der Suchanwendung stellen die Standardkonfiguration für eine Suchoberfläche dar und sind statisch. Wenn Sie dynamische Filter oder Attribute implementieren möchten, z. B. um Nutzern zu ermöglichen, zwischen Datenquellen zu wechseln, können Sie die Einstellungen der Suchanwendung überschreiben, indem Sie die Suchanfrage mit einem Adapter abfangen.
Implementieren Sie einen Adapter mit der Methode interceptSearchRequest
, um Anfragen zu ändern, die vor der Ausführung an die Search API gesendet wurden.
Der folgende Adapter fängt beispielsweise Anfragen ab, um Abfragen auf eine vom Nutzer ausgewählte Quelle zu beschränken:
Verwenden Sie zum Registrieren des Adapters beim Initialisieren des Widgets die Methode setAdapter()
beim Erstellen des ResultsContainer
-Elements.
Der folgende HTML-Code wird verwendet, um ein Auswahlfeld für das Filtern nach Quellen anzuzeigen:
Der folgende Code überwacht die Änderung, legt die Auswahl fest und führt die Abfrage bei Bedarf noch einmal aus.
Sie können die Suchantwort auch abfangen, indem Sie interceptSearchResponse
im Adapter implementieren.
API-Version anpinnen
Standardmäßig verwendet das Widget die neueste stabile Version der API. Wenn Sie eine bestimmte Version sperren möchten, legen Sie den Konfigurationsparameter cloudsearch.config/apiVersion
vor dem Initialisieren des Widgets auf die bevorzugte Version fest.
Wenn die API-Version nicht konfiguriert oder auf einen ungültigen Wert festgelegt ist, wird standardmäßig 1.0 verwendet.
Widget-Version anpinnen
Um unerwartete Änderungen an den Suchoberflächen zu vermeiden, legen Sie den Konfigurationsparameter cloudsearch.config/clientVersion
so fest:
gapi.config.update('cloudsearch.config/clientVersion', 1.1);
Die Widget-Version wird standardmäßig auf 1.0 gesetzt, wenn sie nicht konfiguriert oder auf einen ungültigen Wert festgelegt ist.
Suchoberfläche schützen
Suchergebnisse enthalten streng vertrauliche Informationen. Folgen Sie den Best Practices, um Webanwendungen zu schützen, insbesondere vor Clickjacking-Angriffen.
Weitere Informationen findest du im OWASP Guide Project.
Fehlerbehebung aktivieren
Verwenden Sie interceptSearchRequest
, um die Fehlerbehebung für das Such-Widget zu aktivieren. Beispiel:
if (!request.requestOptions) {
// Make sure requestOptions is populated
request.requestOptions = {};
}
// Enable debugging
request.requestOptions.debugOptions = {enableDebugging: true}
return request;