Il widget di ricerca fornisce un'interfaccia di ricerca personalizzabile per le applicazioni web. L'implementazione del widget richiede solo una piccola quantità di codice HTML e JavaScript e consente di attivare funzionalità di ricerca comuni, come facet e impaginazione. Puoi anche personalizzare parti dell'interfaccia con CSS e JavaScript.
Se hai bisogno di maggiore flessibilità rispetto a quella offerta dal widget, valuta l'utilizzo dell'API Query. Per informazioni sulla creazione di un'interfaccia di ricerca con l'API Query, consulta Creazione di un'interfaccia di ricerca con l'API Query.
Crea un'interfaccia di ricerca
La creazione dell'interfaccia di ricerca richiede diversi passaggi:
- Configura un'applicazione di ricerca
- Genera un ID client per l'applicazione
- Aggiungi il markup HTML per la casella di ricerca e i risultati
- Carica il widget sulla pagina
- Inizializzare il widget
Configura un'applicazione di ricerca
Per ogni interfaccia di ricerca è necessario definire un'applicazione di ricerca nella Console di amministrazione. L'applicazione di ricerca fornisce informazioni aggiuntive per la query, come origini dati, facet e impostazioni della qualità della ricerca.
Per creare un'applicazione di ricerca, consulta Creare un'esperienza di ricerca personalizzata.
Genera un ID client per l'applicazione
Oltre ai passaggi descritti in Configurare l'accesso all'API Google Cloud Search, devi anche generare un ID client per l'applicazione web.
Quando configuri il progetto:
- Seleziona il tipo di client Browser web.
- Fornisci l'URI di origine della tua app.
- Nota dell'ID client creato. Avrai bisogno dell'ID client per completare i passaggi successivi. Il client secret non è necessario per il widget.
Per ulteriori informazioni, consulta OAuth 2.0 per applicazione web lato client.
Aggiungi markup HTML
Il widget richiede una piccola quantità di codice HTML per funzionare. Devi fornire:
- Un elemento
input
per la casella di ricerca. - Un elemento a cui ancorare il popup del suggerimento.
- Un elemento che contiene i risultati di ricerca.
- (Facoltativo) Fornisci un elemento che contenga i controlli dei facet.
Lo snippet HTML riportato di seguito mostra l'HTML di un widget di ricerca, in cui gli elementi da associare sono identificati dal relativo attributo id
:
Carica il widget
Il widget viene caricato dinamicamente tramite uno script di caricamento. Per includere il caricatore, utilizza il tag <script>
come mostrato di seguito:
Devi fornire un callback onload
nel tag script. La funzione viene richiamata quando il caricatore è pronto. Quando il caricatore è pronto, continua a caricare il widget chiamando gapi.load()
per caricare il client API, i moduli Accedi con Google e Cloud Search.
La funzione initializeApp()
viene richiamata dopo il caricamento di tutti i moduli.
Inizializzare il widget
Innanzitutto, inizializza la libreria client chiamando
gapi.client.init()
o gapi.auth2.init()
con il tuo ID client generato
e l'ambito https://www.googleapis.com/auth/cloud_search.query
. Successivamente, utilizza le classi gapi.cloudsearch.widget.resultscontainer.Builder
e gapi.cloudsearch.widget.searchbox.Builder
per configurare il widget e associarlo ai tuoi elementi HTML.
L'esempio seguente mostra come inizializzare il widget:
L'esempio precedente fa riferimento a due variabili per la configurazione definite come:
Personalizzare l'esperienza di accesso
Per impostazione predefinita, il widget richiede agli utenti di accedere e autorizzare l'app quando iniziano a digitare una query. Puoi utilizzare Accedi con Google per i siti web per offrire un'esperienza di accesso più personalizzata agli utenti.
Autorizza direttamente gli utenti
Utilizza Accedi con Google per monitorare lo stato di accesso degli utenti, nonché quelli degli utenti che eseguono l'accesso o la disconnessione, a seconda delle esigenze. Ad esempio, l'esempio che segue osserva lo stato isSignedIn
per monitorare le modifiche all'accesso e utilizza il metodo GoogleAuth.signIn()
per avviare l'accesso facendo clic su un pulsante:
Per maggiori dettagli, consulta l'articolo Accedere con Google.
Consentire l'accesso automatico agli utenti
Puoi semplificare ulteriormente l'esperienza di accesso pre-autorizzando l'applicazione per conto degli utenti della tua organizzazione. Questa tecnica è utile anche se utilizzi Cloud Identity Aware Proxy per proteggere l'applicazione.
Per ulteriori informazioni, vedi Utilizzare l'opzione Accedi con Google con le app IT.
Personalizzare l'interfaccia
Puoi modificare l'aspetto dell'interfaccia di ricerca utilizzando una combinazione di tecniche:
- Esegui l'override degli stili con CSS
- Decora gli elementi con un adattatore
- Creare elementi personalizzati con un adattatore
Esegui l'override degli stili con CSS
Il widget Ricerca viene fornito con il proprio CSS per lo stile degli elementi di suggerimenti e dei risultati, nonché i controlli di impaginazione. Puoi modificare lo stile di questi elementi in base alle tue esigenze.
Durante il caricamento, il widget di ricerca carica dinamicamente il foglio di stile predefinito. Ciò si verifica dopo il caricamento dei fogli di stile dell'applicazione, aumentando la priorità delle regole. Per assicurarti che i tuoi stili abbiano la precedenza su quelli predefiniti, utilizza i selettori predecessori per aumentare la specificità delle regole predefinite.
Ad esempio, la seguente regola non ha alcun effetto se viene caricata in un tag
link
o style
statico del documento.
.cloudsearch_suggestion_container {
font-size: 14px;
}
qualifica invece la regola con l'ID o la classe del container predecessore dichiarato nella pagina.
#suggestions_anchor .cloudsearch_suggestion_container {
font-size: 14px;
}
Per un elenco delle classi di supporto e un codice HTML di esempio prodotto dal widget, consulta la pagina di riferimento relativa alle classi CSS supportate.
Decora gli elementi con un adattatore
Per decorare un elemento prima del rendering, crea e ricodifica un adattatore che implementi uno dei metodi di decorazione come decorateSuggestionElement
o decorateSearchResultElement.
Ad esempio, gli adattatori seguenti aggiungono una classe personalizzata agli elementi suggerimento e risultato.
Per registrare l'adattatore durante l'inizializzazione del widget, utilizza il metodo setAdapter()
della rispettiva classe Builder
:
I decoratori possono modificare gli attributi dell'elemento contenitore ed eventuali elementi secondari. Gli elementi secondari possono essere aggiunti o rimossi durante la decorazione. Tuttavia, se apporti modifiche strutturali agli elementi, valuta la possibilità di creare gli elementi direttamente anziché decorarli.
Creare elementi personalizzati con un adattatore
Per creare un elemento personalizzato per un suggerimento, un container facet o un risultato di ricerca,
crea e registra un adattatore che implementa
createSuggestionElement
,
createFacetResultElement
o createSearchResultElement
in modo replicativo.
I seguenti adattatori illustrano la creazione di suggerimenti personalizzati e di elementi dei risultati di ricerca
utilizzando i tag HTML <template>
.
Per registrare l'adattatore durante l'inizializzazione del widget, utilizza il metodo setAdapter()
della rispettiva classe Builder
:
La creazione di elementi facet personalizzati con createFacetResultElement
è soggetta a diverse limitazioni:
- Devi collegare la classe CSS
cloudsearch_facet_bucket_clickable
all'elemento su cui gli utenti fanno clic per attivare/disattivare un bucket. - Devi aggregare ogni bucket in un elemento contenitore con la classe CSS
cloudsearch_facet_bucket_container
. - Non puoi eseguire il rendering dei bucket in un ordine diverso da quello che sono visualizzati nella risposta.
Ad esempio, il seguente snippet esegue il rendering dei facet utilizzando link anziché caselle di controllo.
Personalizza il comportamento di ricerca
Le impostazioni dell'applicazione di ricerca rappresentano la configurazione predefinita per un'interfaccia di ricerca e sono statiche. Per implementare filtri o facet dinamici, ad esempio per consentire agli utenti di attivare/disattivare le origini dati, puoi sostituire le impostazioni dell'applicazione di ricerca intercettando la richiesta di ricerca con un adattatore.
Implementa un adattatore con il metodo interceptSearchRequest
per modificare le richieste inviate all'API Search prima dell'esecuzione.
Ad esempio, il seguente adattatore intercetta le richieste per limitare le query a un'origine selezionata dall'utente:
Per registrare l'adattatore durante l'inizializzazione del widget, utilizza il metodo setAdapter()
durante la creazione della ResultsContainer
Il seguente codice HTML viene utilizzato per visualizzare una casella di selezione per l'applicazione di filtri in base alle origini:
Il codice seguente rimane in ascolto della modifica, imposta la selezione ed esegue nuovamente la query, se necessario.
Puoi anche intercettare la risposta di ricerca implementando interceptSearchResponse
nell'adattatore.
Fissa la versione dell'API
Per impostazione predefinita, il widget utilizza l'ultima versione stabile dell'API. Per bloccare una
versione specifica, imposta il parametro di configurazione cloudsearch.config/apiVersion
sulla versione preferita prima di inizializzare il widget.
Se il criterio non viene configurato o se viene impostato un valore non valido, la versione dell'API sarà 1.0 per impostazione predefinita.
Fissa la versione del widget
Per evitare modifiche impreviste alle interfacce di ricerca, imposta il parametro di configurazione cloudsearch.config/clientVersion
come mostrato di seguito:
gapi.config.update('cloudsearch.config/clientVersion', 1.1);
Se il widget non viene configurato o se viene impostato un valore non valido, la versione del widget sarà 1.0 per impostazione predefinita.
Proteggere l'interfaccia di ricerca
I risultati di ricerca contengono informazioni altamente sensibili. Segui le best practice per la protezione delle applicazioni web, in particolare contro gli attacchi clickjacking.
Per ulteriori informazioni, consulta la sezione OWASP Guide Project.
Attiva debug
Utilizza interceptSearchRequest
per attivare il debug per il widget di ricerca. Ad esempio:
if (!request.requestOptions) {
// Make sure requestOptions is populated
request.requestOptions = {};
}
// Enable debugging
request.requestOptions.debugOptions = {enableDebugging: true}
return request;