Vous pouvez intégrer des composants Programmable Search Engine (champs de recherche et pages de résultats de recherche) à vos pages Web et autres applications Web à l'aide du balisage HTML. Ces éléments Programmable Search Engine sont constitués de composants affichés conformément aux paramètres stockés par le serveur Programmable Search, ainsi que de toute personnalisation que vous effectuez.
L'ensemble du code JavaScript est chargé de manière asynchrone, ce qui permet au site Web de continuer de se charger pendant que le navigateur récupère le code JavaScript Programmable Search Engine.
Présentation
Ce document fournit un modèle de base pour ajouter des éléments Programmable Search Engine à votre page Web, ainsi que des explications sur les composants configurables de l'élément et sur l'API JavaScript flexible.
Portée
Ce document explique comment utiliser les fonctions et les propriétés spécifiques à l'API Programmable Search Engine Control.
Compatibilité du navigateur
La liste des navigateurs compatibles avec Programmable Search Engine est disponible sur cette page.
Audience
Cette documentation est destinée aux développeurs qui souhaitent ajouter la fonctionnalité Programmable Search à leurs pages.
Éléments Programmable Search
Vous pouvez utiliser le balisage HTML pour ajouter un élément Programmable Search Element à votre page. Chaque élément comporte au moins un composant: un champ de recherche, un bloc de résultats de recherche ou les deux. Le champ de recherche accepte les entrées utilisateur de l'une des manières suivantes:
- Requête de recherche saisie dans le champ de saisie de texte
- Chaîne de requête intégrée dans une URL
- Exécution programmatique
De plus, le bloc de résultats de recherche accepte les entrées comme suit:
- Chaîne de requête intégrée dans une URL
- Exécution programmatique
Les types d'éléments Programmable Search Éléments suivants sont disponibles:
| Type d'élément | Composant(s) | Description |
|---|---|---|
| standard | <div class="gcse-search"> |
Un champ de recherche et des résultats de recherche affichés dans le même <div> |
| deux colonnes | <div class="gcse-searchbox"> et <div class="gcse-searchresults"> |
Mise en page à deux colonnes avec des résultats de recherche d'un côté et un champ de recherche de l'autre. Si vous prévoyez d'insérer plusieurs éléments sur une page Web en mode à deux colonnes, vous pouvez utiliser l'attribut gname pour associer un champ de recherche à un bloc de résultats de recherche. |
| champ de recherche uniquement | <div class="gcse-searchbox-only"> |
Un champ de recherche autonome |
| résultats de recherche uniquement | <div class="gcse-searchresults-only"> |
Bloc de résultats de recherche autonome. |
Vous pouvez ajouter autant d'éléments de recherche valides que vous le souhaitez à votre page Web. Pour le mode à deux colonnes, tous les composants requis (un champ de recherche et un bloc de résultats de recherche) doivent être présents.
Voici un exemple d'élément de recherche simple:
<!-- Put the following javascript before the closing </head> tag and replace 123456 with your own Programmable Search Engine ID. --> <script async src="https://cse.google.com/cse.js?cx=123456"></script> <!-- Place this tag where you want both of the search box and the search results to render --> <div class="gcse-search"></div>
Rédiger différentes options de mise en page à l'aide d'éléments Programmable SearchElements
Les options de mise en page suivantes sont disponibles sur la page "Apparence" du panneau de configuration de Programmable Search Engine. Voici quelques consignes générales concernant la composition des options de mise en page à l'aide de Programmable Search Elements. Pour voir une démonstration de l'une de ces options, cliquez sur le lien.
| Option | Composant(s) |
|---|---|
| Pleine largeur | <div class="gcse-search"> |
| Compact | <div class="gcse-search"> |
| Deux colonnes | <div class="gcse-searchbox">, <div class="gcse-searchresults"> |
| Deux pages | <div class="gcse-searchbox-only"> sur la première page, <div class="gcse-searchresults-only"> (ou d'autres composants) sur la deuxième page. |
| Résultats uniquement | <div class="gcse-searchresults-only"> |
| Hébergé par Google | <div class="gcse-searchbox-only"> |
En savoir plus sur les options de mise en page
Personnaliser les éléments Programmable Search
Pour personnaliser les couleurs, la police ou le style des liens, accédez à la page "Apparence" de votre moteur de recherche programmable.
Vous pouvez utiliser des attributs facultatifs pour écraser les configurations créées dans le panneau de configuration de Programmable Search Engine. Vous pouvez ainsi créer une expérience de recherche propre à la page.
Par exemple, le code suivant crée un champ de recherche qui ouvre une page de résultats (http://www.example.com?search=lady+gaga) dans une nouvelle fenêtre. La valeur de l'attribut queryParameterName et la chaîne de requête de l'utilisateur permettent de créer l'URL des résultats.
Notez que l'attribut queryParameterName est précédé de data-.
Ce préfixe est obligatoire pour tous les attributs.
<div class="gcse-searchbox-only" data-resultsUrl="http://www.example.com" data-newWindow="true" data-queryParameterName="search">
Si vous avez utilisé le panneau de configuration de Programmable Search Engine pour activer des fonctionnalités telles que la saisie semi-automatique ou les filtres, vous pouvez les personnaliser à l'aide d'attributs. Toutes les personnalisations que vous spécifiez à l'aide de ces attributs remplacent les paramètres définis dans le panneau de configuration. L'exemple suivant crée un élément de recherche à deux colonnes avec les caractéristiques suivantes:
- La gestion de l'historique est activée
- Le nombre maximal de termes de saisie semi-automatique affichés est défini sur 5
- Les filtres s'affichent sous forme de liens.
<div class="gcse-searchbox" data-enableHistory="true" data-autoCompleteMaxCompletions="5"> <div class="gcse-searchresults" data-refinementStyle="link">
Attributs acceptés
| Attribut | Type | Description | Élément |
|---|---|---|---|
| Généralités | |||
gname |
Chaîne | (Facultatif) Nom de l'objet "Search Element". Ce nom permet de récupérer un composant associé par son nom ou d'associer un composant searchbox à un composant searchresults. Si cet élément n'est pas fourni, Programmable Search Engine génère automatiquement une gname en fonction de l'ordre des composants sur la page Web. Par exemple, le premier élément searchbox-only sans nom contient le champ gname "searchbox-only0" et le second contient le champ "seachbox-only1" gname, et ainsi de suite.
Notez que la valeur gname générée automatiquement pour un composant dans une mise en page à deux colonnes sera two-column. L'exemple suivant utilise le nom de domaine storesearch pour associer un composant searchbox à un composant searchresults : <div class="gcse-searchbox" data-gname="storesearch"></div> <div class="gcse-searchresults" data-gname="storesearch"></div> Lors de la récupération d'un objet, si plusieurs composants ont le même |
N'importe laquelle |
autoSearchOnLoad |
Booléen | Indique si la recherche doit être exécutée par la requête intégrée à l'URL de la page en cours de chargement. Notez qu'une chaîne de requête doit être présente dans l'URL pour que la recherche automatique puisse être exécutée. Valeur par défaut : true |
N'importe laquelle |
enableHistory |
Booléen | Si la valeur est true, active la gestion de l'historique pour les boutons "Retour" et "Suivant" du navigateur. Voir la démonstration |
champ de recherche champ de recherche uniquement |
queryParameterName |
Chaîne | Nom du paramètre de requête, par exemple q (par défaut) ou query. Elle sera intégrée à l'URL (par exemple, http://www.example.com?q=lady+gaga). Notez que spécifier uniquement le nom du paramètre de requête ne déclenche pas de recherche automatique lors du chargement. L'URL doit comporter une chaîne de requête pour exécuter la recherche automatique. |
N'importe laquelle |
resultsUrl |
URL | URL de la page de résultats. (Par défaut, il s'agit de la page hébergée par Google.) | champ de recherche uniquement |
newWindow |
Booléen | Indique si la page de résultats s'ouvre dans une nouvelle fenêtre.
Valeur par défaut : false |
champ de recherche uniquement |
personalizedAds |
Booléen |
Indique si les utilisateurs ont autorisé l'éditeur à partager des informations personnelles avec Google pour la publicité personnalisée.
Valeur par défaut : Exemple d'utilisation: |
résultats de recherche résultats de recherche uniquement |
mobileLayout |
Chaîne |
Indique si les styles de mise en page pour mobile doivent être utilisés pour les appareils mobiles.
Valeur par défaut : Exemple d'utilisation: |
N'importe laquelle |
| Saisie semi-automatique | |||
enableAutoComplete |
Booléen | Disponible uniquement si la saisie semi-automatique a été activée dans le panneau de configuration de Programmable Search Engine.
true active la saisie semi-automatique. |
N'importe laquelle |
autoCompleteMaxCompletions |
Nombre entier | Nombre maximal de termes de saisie semi-automatique à afficher. | champ de recherche champ de recherche uniquement |
autoCompleteMaxPromotions |
Nombre entier | Nombre maximal de résultats mis en avant à afficher dans la saisie semi-automatique. | champ de recherche champ de recherche uniquement |
autoCompleteValidLanguages |
Chaîne | Liste des langues pour lesquelles la saisie semi-automatique doit être activée, séparées par une virgule. Langues acceptées. | champ de recherche champ de recherche uniquement |
| Filtres | |||
defaultToRefinement |
Chaîne | Disponible uniquement si des filtres ont été créés dans le panneau de configuration de Programmable Search Engine. Spécifie le libellé de filtre par défaut à afficher.Remarque: Cet attribut n'est pas compatible avec la mise en page hébergée par Google. | N'importe laquelle |
refinementStyle |
Chaîne | Les valeurs acceptées sont tab (par défaut) et link.
link n'est disponible que si la recherche d'images est désactivée ou si la recherche d'images est activée, mais la recherche sur le Web est désactivée. |
résultats de recherche résultats de recherche uniquement |
| Recherche d'images | |||
enableImageSearch |
Booléen | Disponible uniquement si la
recherche d'images a été activée dans le panneau de configuration de Programmable Search Engine.
Si la valeur est |
résultats de recherche résultats de recherche uniquement |
defaultToImageSearch |
Booléen | Disponible uniquement si la
recherche d'images a été activée dans le panneau de configuration de Programmable Search Engine.
Si la valeur est |
N'importe laquelle |
imageSearchLayout |
Chaîne | Disponible uniquement si la
recherche d'images a été activée dans le panneau de configuration de Programmable Search Engine.
Spécifie la mise en page de la page de résultats de recherche d'images. Les valeurs acceptées sont |
résultats de recherche résultats de recherche uniquement |
imageSearchResultSetSize |
Entier, chaîne | Disponible uniquement si la
recherche d'images a été activée dans le panneau de configuration de Programmable Search Engine.
Spécifie la taille maximale de l'ensemble de résultats de recherche pour la recherche d'images.
Par exemple, |
N'importe laquelle |
image_as_filetype |
Chaîne | Disponible uniquement si la
recherche d'images a été activée dans le panneau de configuration de Programmable Search Engine.
Limite les résultats aux fichiers d'une extension spécifiée. Les extensions compatibles sont | N'importe laquelle |
image_as_oq |
Chaîne | Disponible uniquement si la
recherche d'images a été activée dans le panneau de configuration de Programmable Search Engine.
Filtrez les résultats de recherche avec l'opérateur logique OU. Exemple d'utilisation si vous souhaitez obtenir des résultats de recherche incluant "term1" ou "term2": | N'importe laquelle |
image_as_rights |
Chaîne | Disponible uniquement si la
recherche d'images a été activée dans le panneau de configuration de Programmable Search Engine.
Filtres basés sur les licences. Les valeurs acceptées sont Consultez la section Combinaisons habituelles. | N'importe laquelle |
image_as_sitesearch |
Chaîne | Disponible uniquement si la
recherche d'images a été activée dans le panneau de configuration de Programmable Search Engine.
Limiter les résultats aux pages d'un site spécifique. Exemple d'utilisation: | N'importe laquelle |
image_colortype |
Chaîne | Disponible uniquement si la
recherche d'images a été activée dans le panneau de configuration de Programmable Search Engine.
Limite la recherche aux images en noir et blanc (mono), en nuances de gris ou en couleurs. Les valeurs acceptées sont | N'importe laquelle |
image_cr |
Chaîne | Disponible uniquement si la
recherche d'images a été activée dans le panneau de configuration de Programmable Search Engine.
Limite les résultats de recherche aux documents provenant d'un pays donné. | N'importe laquelle |
image_dominantcolor |
Chaîne | Disponible uniquement si la
recherche d'images a été activée dans le panneau de configuration de Programmable Search Engine.
Limite la recherche aux images d'une couleur dominante spécifique.
Les valeurs acceptées sont | N'importe laquelle |
image_filter |
Chaîne | Disponible uniquement si la
recherche d'images a été activée dans le panneau de configuration de Programmable Search Engine.
Filtrage automatique des résultats de recherche Valeurs acceptées: 0/1 Exemple d'utilisation: | N'importe laquelle |
image_gl |
Chaîne | Disponible uniquement si la recherche d'images a été activée dans le panneau de configuration de Programmable Search Engine. Booster les résultats de recherche dont le pays d'origine correspond à la valeur du paramètre. | N'importe laquelle |
image_size |
Chaîne | Disponible uniquement si la
recherche d'images a été activée dans le panneau de configuration de Programmable Search Engine.
Renvoie des images d'une taille spécifiée, où la taille peut être | N'importe laquelle |
image_sort_by |
Chaîne | Disponible uniquement si la
recherche d'images a été activée dans le panneau de configuration de Programmable Search Engine.
Triez les résultats en fonction de la date ou d'un autre contenu structuré. Pour trier par pertinence, utilisez une chaîne vide (image_sort_by="). Exemple d'utilisation: | N'importe laquelle |
image_type |
Chaîne | Disponible uniquement si la
recherche d'images a été activée dans le panneau de configuration de Programmable Search Engine.
Limite la recherche aux images d'un certain type.
Les valeurs acceptées sont | N'importe laquelle |
| Recherche sur le Web | |||
disableWebSearch |
Booléen | Si la valeur est true, la recherche sur le Web est désactivée. Généralement utilisé uniquement si la
recherche d'images a été activée dans le panneau de configuration de Programmable Search Engine. |
résultats de recherche résultats de recherche uniquement |
webSearchQueryAddition |
Chaîne | Termes supplémentaires ajoutés à la requête de recherche avec l'opérateur logique OU.
Exemple d'utilisation: |
N'importe laquelle |
webSearchResultSetSize |
Entier, chaîne | Taille maximale de l'ensemble de résultats. S'applique à la fois à la recherche d'images et à la recherche sur le Web. La valeur par défaut dépend de la mise en page et de la configuration de Programmable Search Engine pour effectuer une recherche sur l'ensemble du Web ou uniquement sur des sites spécifiés. Voici les valeurs acceptées :
|
N'importe laquelle |
webSearchSafesearch |
Chaîne |
Indique si SafeSearch est activé pour les résultats websearch. Les valeurs acceptées sont off et active.
|
N'importe laquelle |
as_filetype |
Chaîne | Limite les résultats aux fichiers d'une extension spécifiée. La liste des types de fichiers indexables par Google est disponible dans le Centre d'aide de la Search Console. | N'importe laquelle |
as_oq |
Chaîne | Filtrez les résultats de recherche avec l'opérateur logique OU.
Exemple d'utilisation si vous souhaitez obtenir des résultats de recherche incluant "term1" ou "term2": |
N'importe laquelle |
as_rights |
Chaîne | Filtres basés sur les licences.
Les valeurs acceptées sont Pour obtenir des combinaisons types, consultez la page https://wiki.iframe.org/wiki/CC_Search_integration. | N'importe laquelle |
as_sitesearch |
Chaîne | Limiter les résultats aux pages d'un site spécifique.
Exemple d'utilisation: |
N'importe laquelle |
cr |
Chaîne | Limite les résultats de recherche aux documents provenant d'un pays donné.
Exemple d'utilisation: |
N'importe laquelle |
filter |
Chaîne | Filtrage automatique des résultats de recherche
Valeurs acceptées: 0/1 Exemple d'utilisation: |
N'importe laquelle |
gl |
Chaîne | Booster les résultats de recherche dont le pays d'origine correspond à la valeur du paramètre.
Cette option ne fonctionne qu'avec le paramètre valeur de la langue. Exemple d'utilisation: |
N'importe laquelle |
lr |
Chaîne | Limite les résultats de recherche aux documents rédigés dans une langue spécifique.
Exemple d'utilisation: |
N'importe laquelle |
sort_by |
Chaîne | Triez les résultats en fonction de la date ou d'un autre contenu structuré. La valeur de l'attribut doit correspondre à l'une des options fournies dans les paramètres de tri des résultats de l'API de recherche programmable.
Pour trier par pertinence, utilisez une chaîne vide (sort_by="). Exemple d'utilisation: |
N'importe laquelle |
| Résultats de recherche | |||
enableOrderBy |
Booléen | Active le tri des résultats par pertinence, date ou libellé. | N'importe laquelle |
linkTarget |
Chaîne | Définit la cible du lien. Valeur par défaut : _blank |
résultats de recherche résultats de recherche uniquement |
noResultsString |
Chaîne | Spécifie le texte par défaut à afficher lorsqu'aucun résultat ne correspond à la requête. La chaîne de résultat par défaut peut être utilisée pour afficher une chaîne localisée dans toutes les langues prises en charge, contrairement à la chaîne personnalisée. | résultats de recherche résultats de recherche uniquement |
resultSetSize |
Entier, chaîne | Taille maximale de l'ensemble de résultats. Par exemple, large, small, filtered_cse, 10. La valeur par défaut dépend de la mise en page et de la configuration du moteur de recherche sur l'ensemble du Web ou uniquement sur des sites spécifiés. |
N'importe laquelle |
safeSearch |
Chaîne | Indique si
SafeSearch est activé pour la recherche sur le Web et dans les images. Les valeurs acceptées sont off et active. |
N'importe laquelle |
Rappels
Les rappels permettent de contrôler précisément l'initialisation des éléments de recherche et les processus de recherche.
Ils sont enregistrés auprès du JavaScript de l'élément de recherche via l'objet __gcse global. La section Enregistrer des rappels illustre l'enregistrement de tous les rappels compatibles.
window.__gcse = {
parsetags: 'explicit', // Defaults to 'onload'
initializationCallback: myInitializationCallback,
searchCallbacks: {
image: {
starting: myImageSearchStartingCallback,
ready: myImageResultsReadyCallback,
rendered: myImageResultsRenderedCallback,
},
web: {
starting: myWebSearchStartingCallback,
ready: myWebResultsReadyCallback,
rendered: myWebResultsRenderedCallback,
},
},
};
Rappel d'initialisation
Le rappel d'initialisation est invoqué avant que le code JavaScript de l'élément de recherche n'affiche les éléments de recherche dans le DOM. Si parsetags est défini sur explicit dans __gcse, le JavaScript de l'élément de recherche laisse le rendu des éléments de recherche dans le rappel d'initialisation (comme illustré dans Enregistrer les rappels).
Elle peut être utilisée pour sélectionner les éléments à afficher ou pour différer les éléments de rendu jusqu'à ce qu'ils soient nécessaires. Elle peut également remplacer les attributs des éléments. Par exemple, elle peut transformer un champ de recherche configuré via le panneau de configuration ou des attributs HTML par défaut afin d'effectuer une recherche sur le Web dans un champ de recherche d'images, ou spécifier que les requêtes envoyées via un formulaire Programmable Search Engine sont exécutées dans un élément uniquement résultats de recherche.
Voir la démonstration
Le rôle du rappel d'initialisation est contrôlé par la valeur de la propriété parsetags de __gcse.
- Si sa valeur est
onload, le JavaScript de l'élément de recherche affiche automatiquement tous les éléments de recherche sur la page. Le rappel d'initialisation est toujours appelé, mais il n'est pas responsable de l'affichage des éléments de recherche. - Si sa valeur est
explicit, le JavaScript de l'élément de recherche n'affiche pas les éléments de recherche. Le rappel peut les afficher de manière sélective à l'aide de la fonctionrender()ou afficher tous les éléments de recherche avec la fonctiongo()
Le code suivant montre comment afficher un champ de recherche avec les résultats de recherche dans un div à l'aide de l'analyse et du rappel d'initialisation de explicit:
Nous devons inclure un élément <div> avec un ID dans lequel insérer le code de l'élément de recherche:
<div id="test"></div>
Ajoutez ce JavaScript après <div>. Notez qu'il fait référence à test, le id que nous avons utilisé pour identifier <div>const myInitCallback = function() {
if (document.readyState == 'complete') {
// Document is ready when Search Element is initialized.
// Render an element with both search box and search results in div with id 'test'.
google.search.cse.element.render(
{
div: "test",
tag: 'search'
});
} else {
// Document is not ready yet, when Search Element is initialized.
google.setOnLoadCallback(function() {
// Render an element with both search box and search results in div with id 'test'.
google.search.cse.element.render(
{
div: "test",
tag: 'search'
});
}, true);
}
};
// Insert it before the Search Element code snippet so the global properties like parsetags and callback
// are available when cse.js runs.
window.__gcse = {
parsetags: 'explicit',
initializationCallback: myInitCallback
};
Incluez ce code HTML pour lancer le chargement de l'élément de recherche. Remplacez la valeur cx dans la clause src par votre propre cx.
<script async
src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>
Rechercher des rappels
Le JavaScript de l'élément de recherche est compatible avec six rappels qui fonctionnent dans le flux de contrôle de recherche. Les rappels de recherche sont organisés par paires, un rappel de recherche sur le Web et un rappel de recherche d'images correspondant:
- Démarrage de la recherche
- Pour la recherche d'images
- Pour la recherche sur le Web
- Résultats prêts
- Pour la recherche d'images
- Pour la recherche sur le Web
- Résultats affichés
- Pour la recherche d'images
- Pour la recherche sur le Web
Comme les rappels d'initialisation,les rappels de recherche sont configurés à l'aide d'entrées dans l'objet __gcse. Cela se produit au démarrage du JavaScript de l'élément de recherche. Les modifications apportées à __gcse après le démarrage sont ignorées.
Chacun de ces rappels reçoit le gName de l'élément Search en tant qu'argument.
gname s'avère utile lorsqu'une page contient plusieurs recherches. Attribuez une valeur gname à un élément de recherche à l'aide de l'attribut data-gname:
<div class="gcse-searchbox" data-gname="storesearch"></div>
Si le code HTML n'identifie pas le nom gname, le code JavaScript de l'élément de recherche génère une valeur qui restera cohérente jusqu'à ce que le code HTML soit modifié.
Rappel d'image/de recherche sur le Web
Les rappels de début de la recherche sont appelés immédiatement avant que le code JavaScript de l'élément de recherche demande des résultats à son serveur. Exemple de cas d'utilisation : utiliser l'heure locale pour contrôler les modifications apportées à la requête.
searchStartingCallback(gname, query)
gname- Chaîne d'identification de l'élément de recherche
query- valeur saisie par l'utilisateur (peut-être modifiée par le code JavaScript de l'élément de recherche).
Le rappel renvoie la valeur à utiliser comme requête pour cette recherche. Si elle renvoie une chaîne vide, la valeur renvoyée est ignorée, et l'appelant utilise la requête non modifiée.
Vous pouvez également placer la fonction de rappel dans l'objet __gcse ou ajouter le rappel de manière dynamique à l'objet avec JavaScript:
window.__gcse['searchCallbacks']['web']['starting'] = function(gname, query) {...};
Exemple de rappel de démarrage de la recherche
Dans l'exemple de rappel de début de la recherche, l'exemple de rappel de recherche ajoute morning ou afternoon à la requête en fonction de l'heure.
const myWebSearchStartingCallback = (gname, query) => {
const hour = new Date().getHours();
return query + (hour < 12 ? ' morning' : ' afternoon');
};
window.myImageSearchStartingCallbackName = myWebSearchStartingCallback;
Installer ce rappel dans window.__gcse:
window.__gcse || (window.__gcse = {});
window.__gcse.searchCallbacks = {
image: {
starting: 'myImageSearchStartingCallbackName',
},
web: {
starting: myWebSearchStartingCallback,
},
};
<script
async src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>
<div class="gcse-searchbox"></div>
<div class="gcse-searchresults"></div>
Image/Rappel pour les résultats de recherche sur le Web
Ces rappels sont appelés immédiatement avant que le code JavaScript de l'élément de recherche affiche des promotions et des résultats. Exemple de cas d'utilisation : rappel qui affiche les promotions et génère un style qui ne peut pas être spécifié avec une personnalisation normale.
resultsReadyCallback(gname, query, promos, results, div)
gname- Chaîne d'identification de l'élément de recherche
query- requête qui a produit ces résultats
promos- : tableau d'objets de promotion, qui correspond aux promotions correspondantes pour la requête de l'utilisateur. Consultez la définition de l'objet Promotion.
results- Tableau d'objets de résultat. Consultez la définition de l'objet de résultat.
div- Une balise div HTML placée dans le DOM, là où l'élément Search insérerait généralement des promotions et des résultats de recherche. Normalement, le code JavaScript de l'élément de recherche gère le remplissage de ce div, mais ce rappel peut choisir d'arrêter l'affichage automatique des résultats et d'utiliser ce
divpour afficher les résultats.
Si ce rappel renvoie une valeur true, le code JavaScript de l'élément de recherche passe à son travail de pied de page.
Exemple de rappel "Résultats prêts"
L'exemple de rappel resultsReady dans le rappel Exemple de résultats prêts remplace la présentation par défaut des résultats de recherche et des résultats par un remplacement très simple.
const myResultsReadyCallback = function(name, q, promos, results, resultsDiv) {
const makePromoElt = (promo) => {
const anchor = document.createElement('a');
anchor.href = promo['url'];
anchor.target = '_blank';
anchor.classList.add('gs-title');
const span = document.createElement('span');
span.innerHTML = 'Promo: ' + promo['title'];
anchor.appendChild(span);
return anchor;
};
const makeResultParts = (result) => {
const anchor = document.createElement('a');
anchor.href = result['url'];
anchor.target = '_blank';
anchor.classList.add('gs_title');
anchor.appendChild(document.createTextNode(result['visibleUrl']));
const span = document.createElement('span');
span.innerHTML = ' ' + result['title'];
return [anchor, span];
};
const table = document.createElement('table');
if (promos) {
for (const promo of promos) {
const row = table.insertRow(-1);
const cell = row.insertCell(-1);
cell.appendChild(makePromoElt(promo));
}
resultsDiv.appendChild(table);
resultsDiv.appendChild(document.createElement('br'));
}
if (results) {
const table = document.createElement('table');
for (const result of results) {
const row = table.insertRow(-1);
const cell = row.insertCell(-1);
const [anchor, span] = makeResultParts(result);
cell.appendChild(anchor);
const cell2 = row.insertCell(-1);
cell2.appendChild(span);
}
resultsDiv.appendChild(table);
}
return true;
};
Installer ce rappel dans window.__gcse:
window.__gcse || (window.__gcse = {});
window.__gcse.searchCallbacks = {
web: {
ready: myResultsReadyCallback,
},
};
<script async
src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>
<div class="gcse-searchbox"></div>
<div class="gcse-searchresults"></div>
Comme pour le rappel de début de la recherche, l'une des nombreuses méthodes suivantes permet de placer le rappel dans l'objet __gcse.
Rappel d'affichage des résultats de recherche sur le Web/des images
Ces rappels sont invoqués juste avant que le code JavaScript de l'élément de recherche affiche le pied de page. Parmi les cas d'utilisation, citons un rappel qui ajoute du contenu aux résultats qui n'est pas affiché par l'élément de recherche, comme une case à cocher Save this (Enregistrer cette option) ou des informations qui ne s'affichent pas automatiquement, ou un rappel qui ajoute des boutons for more information (pour plus d'informations).
Si un rappel renvoyé dans les résultats a besoin d'informations qui se trouvaient dans les paramètres promos et results du rappel prêt sur les résultats, il peut les transmettre entre eux:
callback(gname, query, promoElts, resultElts);
gname- Chaîne d'identification de l'élément de recherche
query- chaîne de recherche.
promoElts- Tableau des éléments DOM contenant des promotions.
resultElts- Tableau des éléments DOM contenant les résultats.
Aucune valeur renvoyée.
Exemple de rappel de résultats affichés
L'exemple de rappel resultsRendered dans Exemple de rappel de résultats affichés ajoute une case à cocher Keep factice à chaque promotion et résultat.
myWebResultsRenderedCallback = function(name, q, promos, results) {
for (const div of promos.concat(results)) {
const innerDiv = document.createElement('div');
innerDiv.appendChild(document.createTextNode('Keep: '));
const checkBox = document.createElement('input');
checkBox.type = 'checkbox';
checkBox.name = 'save';
innerDiv.appendChild(checkBox);
div.insertAdjacentElement('afterbegin', innerDiv);
}
};
Installer ce rappel dans window.__gcse:
window.__gcse || (window.__gcse = {});
window.__gcse.searchCallbacks = {
web: {
rendered: 'myWebResultsRenderedCallback',
},
};
<script async
src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>
<div class="gcse-searchbox"></div>
<div class="gcse-searchresults"></div>
Si le rappel des résultats a besoin d'informations transmises au rappel prêt des résultats, ces données peuvent être transmises entre les rappels. L'exemple suivant montre l'une des nombreuses façons de transmettre une valeur de note de richSnippet du rappel prêt aux résultats au rappel rendu des résultats.
const makeTwoPartCallback = () => {
let saveForRenderCallback;
const readyCallback = (name, q, promos, results, resultsDiv) =>
{
saveForRenderCallback = [];
for (const result of results) {
const {
richSnippet: {
answer = []
} = {},
} = result;
const firstAnswer = answer[0];
if (firstAnswer) {
const upVotes = firstAnswer['upvotecount'];
if (upVotes) {
saveForRenderCallback.push(
{upvotes: parseInt(upVotes, 10)}
);
continue;
}
}
saveForRenderCallback.push({});
}
};
const renderedCallback = (name, q, promos, results) => {
for (let i = 0; i < results.length; ++i) {
const div = results[i];
const votes = saveForRenderCallback[i]['upvotes'];
if (votes) {
const innerDiv = document.createElement('div');
innerDiv.innerHTML = '<b>Upvotes: ' + votes + '</b>';
div.insertAdjacentElement('afterbegin', innerDiv);
}
}
};
return {readyCallback, renderedCallback};
};__gcse :
const {
readyCallback: webResultsReadyCallback,
renderedCallback: webResultsRenderedCallback,
} = makeTwoPartCallback();
window.__gcse || (window.__gcse = {});
window.__gcse.searchCallbacks = {
web: {
ready: webResultsReadyCallback,
rendered: webResultsRenderedCallback,
},
};
<script async
src="https://cse.google.com/cse.js?cx=000888210889775888983:kdroeu4mwju"></script>
<div class="gcse-searchbox"></div>
<div class="gcse-searchresults"></div>
Autres exemples de rappels
Vous trouverez d'autres exemples de rappels dans le document Autres exemples de rappels.
Propriétés de la promotion et des résultats
Utilisant la notation JSDoc, il s'agit des propriétés des objets promotion et result. Nous répertorions ici toutes les propriétés susceptibles d'être présentes. La présence d'un grand nombre de propriétés dépend des détails de la promotion ou du résultat de recherche.
{
content: string,
image: {
height: number,
url: string,
width: number,
},
title: string,
url: string,
visibleUrl: string,
}
{
content: string,
contentNoFormatting: string,
contextUrl: string, // For image search results only
fileFormat: string,
image: { // For image search reseults only
height: number,
url: string,
width: number,
},
perResultLabels: !Array<{
anchor: string,
label: string,
labelWithOp: string,
}>,
richSnippet: !Array<!Object>, // For web search results only
thumbnailImage: {
height: number,
url: string,
width: number,
},
title: string,
titleNoFormatting: string,
url: string,
visibleUrl: string,
}
Dans les résultats, richSnippet présente un type de tableau d'objets. Les valeurs des entrées de ce tableau sont contrôlées par les données structurées de la page Web pour chaque résultat de recherche. Par exemple, un site Web d'avis peut inclure des données structurées qui ajoutent cette entrée de tableau à richSnippet :
'review': {
'ratingstars': '3.0',
'ratingcount': '1024',
},
API Programmable Search Element Control (V2)
L'objet google.search.cse.element publie les fonctions statiques suivantes:
| Fonction | Description | ||||||
|---|---|---|---|---|---|---|---|
.render(componentConfig, opt_componentConfig) |
Affiche un élément de recherche.
Paramètres
|
||||||
.go(opt_container) |
affiche toutes les balises/classes de l'élément de recherche dans le conteneur spécifié.
Paramètres
|
||||||
.getElement(gname) |
Récupère l'objet élément par gname. Sinon, renvoyez la valeur "null".
L'objet
Le code suivant exécute la requête "news" dans l'élément de recherche "element1": var element = google.search.cse.element.getElement('element1');
element.execute('news');
|
||||||
.getAllElements() |
Renvoie une map de tous les objets d'élément créés, associés par gname. |