Le widget Recherche fournit une interface de recherche personnalisable pour les applications Web. Le widget ne nécessite qu'une petite quantité de code HTML et JavaScript pour implémenter et activer les fonctionnalités de recherche courantes telles que les attributs et la pagination. Vous pouvez également personnaliser certaines parties de l'interface avec CSS et JavaScript.
Si vous avez besoin de plus de flexibilité que le widget, envisagez d'utiliser l'API Query. Pour plus d'informations sur la création d'une interface de recherche avec l'API Query, consultez la section Créer une interface de recherche avec l'API Query.
Créer une interface de recherche
La création de l'interface de recherche nécessite plusieurs étapes:
- Configurer une application de recherche
- Générer un ID client pour l'application
- Ajouter un balisage HTML pour le champ de recherche et les résultats
- Charger le widget sur la page
- Initialiser le widget
Configurer une application de recherche
Une application de recherche doit être définie dans la console d'administration pour chaque interface de recherche. L'application de recherche fournit des informations supplémentaires pour la requête, telles que les sources de données, les attributs et les paramètres de qualité de la recherche.
Pour créer une application de recherche, consultez Créer une expérience de recherche personnalisée.
Générer un ID client pour l'application
En plus des étapes décrites sur la page Configurer l'accès à l'API Google Cloud Search, vous devez également générer un ID client pour l'application Web.
Lorsque vous configurez le projet:
- Sélectionnez le type de client Navigateur Web.
- Indiquez l'URI d'origine de votre application.
- Notez l'ID client créé. Vous en aurez besoin pour effectuer les étapes suivantes. Le widget ne requiert pas de code secret du client.
Pour en savoir plus, consultez OAuth 2.0 pour les applications Web côté client.
Ajouter un balisage HTML
Le widget nécessite une petite quantité de code HTML pour fonctionner. Vous devez fournir les informations suivantes:
- Un élément
input
pour le champ de recherche. - Élément auquel ancrer le pop-up de suggestion.
- Élément qui contiendra les résultats de recherche.
- (Facultatif) Fournissez un élément qui contiendra les commandes d'attributs.
L'extrait de code HTML suivant correspond à un widget Recherche, où les éléments à lier sont identifiés par leur attribut id
:
Charger le widget
Le widget est chargé de manière dynamique via un script de chargement. Pour inclure le chargeur, utilisez la balise <script>
comme indiqué ci-dessous:
Vous devez fournir un rappel onload
dans la balise de script. Cette fonction est appelée lorsque le chargeur est prêt. Lorsque le chargeur est prêt, continuez à charger le widget en appelant gapi.load()
pour charger le client API, Google Sign-In et les modules Cloud Search.
La fonction initializeApp()
est appelée une fois tous les modules chargés.
Initialiser le widget
Commencez par initialiser la bibliothèque cliente en appelant gapi.client.init()
ou gapi.auth2.init()
avec l'ID client généré et le champ d'application https://www.googleapis.com/auth/cloud_search.query
. Utilisez ensuite les classes gapi.cloudsearch.widget.resultscontainer.Builder
et gapi.cloudsearch.widget.searchbox.Builder
pour configurer le widget et le lier à vos éléments HTML.
L'exemple suivant montre comment initialiser le widget:
L'exemple ci-dessus fait référence à deux variables de configuration définies comme suit:
Personnaliser l'expérience de connexion
Par défaut, le widget invite les utilisateurs à se connecter et à autoriser l'application au moment où ils commencent à saisir une requête. Vous pouvez utiliser Google Sign-In pour les sites Web afin d'offrir une expérience de connexion plus personnalisée aux utilisateurs.
Autoriser directement les utilisateurs
Utilisez Se connecter avec Google pour surveiller l'état de connexion de l'utilisateur, et le connecter ou le déconnecter si nécessaire. Par exemple, l'exemple suivant observe l'état isSignedIn
pour surveiller les modifications de la connexion et utilise la méthode GoogleAuth.signIn()
pour lancer la connexion à partir d'un clic sur un bouton:
Pour en savoir plus, consultez Se connecter avec Google.
Connecter automatiquement les utilisateurs
Vous pouvez simplifier davantage l'expérience de connexion en pré-autorisant l'application au nom des utilisateurs de votre organisation. Cette technique est également utile si vous protégez l'application à l'aide de Cloud Identity-Aware Proxy.
Pour en savoir plus, consultez Utiliser Google Sign-In avec des applications informatiques.
Personnaliser l'interface
Vous pouvez modifier l'apparence de l'interface de recherche à l'aide d'une combinaison de techniques:
- Remplacer les styles avec du CSS
- Décorer les éléments avec un adaptateur
- Créer des éléments personnalisés avec un adaptateur
Remplacer les styles avec du CSS
Le widget Recherche est fourni avec son propre code CSS pour définir le style des éléments de suggestion et de résultat, ainsi que les commandes de pagination. Vous pouvez modifier le style de ces éléments si nécessaire.
Lors du chargement, le widget Recherche charge sa feuille de style par défaut de manière dynamique. Cela se produit après le chargement des feuilles de style de l'application, ce qui augmente la priorité des règles. Pour vous assurer que vos propres styles prévalent sur les styles par défaut, augmentez la spécificité des règles par défaut à l'aide de sélecteurs d'ancêtre.
Par exemple, la règle suivante n'a aucun effet si elle est chargée dans une balise statique link
ou style
dans le document.
.cloudsearch_suggestion_container {
font-size: 14px;
}
Qualifiez plutôt la règle avec l'ID ou la classe du conteneur ancêtre déclaré sur la page.
#suggestions_anchor .cloudsearch_suggestion_container {
font-size: 14px;
}
Pour obtenir la liste des classes compatibles et un exemple de code HTML généré par le widget, consultez la documentation de référence sur les classes CSS acceptées.
Décorer les éléments avec un adaptateur
Pour décorer un élément avant de le rendre, créez et recommencez un adaptateur qui implémente l'une des méthodes de décoration telles que decorateSuggestionElement
ou decorateSearchResultElement.
.
Par exemple, les adaptateurs suivants ajoutent une classe personnalisée aux éléments de suggestion et de résultat.
Pour enregistrer l'adaptateur lors de l'initialisation du widget, utilisez la méthode setAdapter()
de la classe Builder
correspondante:
Les décorateurs peuvent modifier les attributs de l'élément conteneur ainsi que les éléments enfants. Des éléments enfants peuvent être ajoutés ou supprimés pendant la décoration. Toutefois, si vous apportez des modifications structurelles aux éléments, envisagez de les créer directement au lieu de les décorer.
Créer des éléments personnalisés avec un adaptateur
Pour créer un élément personnalisé pour une suggestion, un conteneur d'attributs ou un résultat de recherche, créez et enregistrez un adaptateur qui implémente respectivement createSuggestionElement
, createFacetResultElement
ou createSearchResultElement
.
Les adaptateurs suivants illustrent la création d'éléments de suggestion et de résultats de recherche personnalisés à l'aide de balises HTML <template>
.
Pour enregistrer l'adaptateur lors de l'initialisation du widget, utilisez la méthode setAdapter()
de la classe Builder
correspondante:
La création d'éléments d'attribut personnalisés avec createFacetResultElement
est soumise à plusieurs restrictions:
- Vous devez associer la classe CSS
cloudsearch_facet_bucket_clickable
à l'élément sur lequel les utilisateurs cliquent pour activer/désactiver un bucket. - Vous devez encapsuler chaque bucket dans un élément conteneur avec la classe CSS
cloudsearch_facet_bucket_container
. - Vous ne pouvez pas afficher les buckets dans un ordre différent de celui indiqué dans la réponse.
Par exemple, l'extrait de code suivant affiche les attributs à l'aide de liens au lieu de cases à cocher.
Personnaliser le comportement de recherche
Les paramètres de l'application de recherche représentent la configuration par défaut d'une interface de recherche et sont statiques. Pour implémenter des filtres ou des attributs dynamiques (par exemple, autoriser les utilisateurs à activer/désactiver les sources de données), vous pouvez remplacer les paramètres de l'application de recherche en interceptant la requête de recherche à l'aide d'un adaptateur.
Implémentez un adaptateur avec la méthode interceptSearchRequest
pour modifier les requêtes envoyées à l'API Search avant l'exécution.
Par exemple, l'adaptateur suivant intercepte les requêtes pour limiter les requêtes à une source sélectionnée par l'utilisateur:
Pour enregistrer l'adaptateur lors de l'initialisation du widget, utilisez la méthode setAdapter()
lors de la création de ResultsContainer
.
Le code HTML suivant permet d'afficher une zone de sélection pour le filtrage par sources:
Le code suivant écoute la modification, définit la sélection et réexécute la requête si nécessaire.
Vous pouvez également intercepter la réponse de la recherche en implémentant interceptSearchResponse
dans l'adaptateur.
Épingler la version de l'API
Par défaut, le widget utilise la dernière version stable de l'API. Pour verrouiller une version spécifique, définissez le paramètre de configuration cloudsearch.config/apiVersion
sur la version préférée avant d'initialiser le widget.
Si elle n'est pas définie ou si elle est définie sur une valeur non valide, la version de l'API est définie par défaut sur 1.0.
Épingler la version du widget
Pour éviter toute modification inattendue des interfaces de recherche, définissez le paramètre de configuration cloudsearch.config/clientVersion
comme suit:
gapi.config.update('cloudsearch.config/clientVersion', 1.1);
Si elle n'est pas définie ou si elle est définie sur une valeur non valide, la version du widget est définie par défaut sur 1.0.
Sécuriser l'interface de recherche
Les résultats de recherche contiennent des informations hautement sensibles. Suivez les bonnes pratiques pour sécuriser les applications Web, en particulier contre les attaques par détournement de clic.
Pour en savoir plus, consultez la page OWASP Guide Project (Projet du guide OWASP).
Activer le débogage
Utilisez interceptSearchRequest
pour activer le débogage du widget Recherche. Exemple :
if (!request.requestOptions) {
// Make sure requestOptions is populated
request.requestOptions = {};
}
// Enable debugging
request.requestOptions.debugOptions = {enableDebugging: true}
return request;