API Programmable Search Element Control

Vous pouvez intégrer des composants Programmable Search Engine (champs de recherche et pages de résultats de recherche) dans vos pages Web et autres applications Web à l'aide du balisage HTML. Ces moteurs Programmable Search Engine sont des composants affichés en fonction des paramètres stockés par le serveur Programmable Search, ainsi que toutes les personnalisations que vous effectuez.

Le code JavaScript est entièrement chargé de manière asynchrone, ce qui permet à votre page Web continue 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 Programmable Search Engine à votre page Web, ainsi que des explications sur les attributs composants configurables et API JavaScript flexible.

Portée

Ce document explique comment utiliser les fonctions et propriétés spécifiques l'API Programmable Search Engine Control.

Compatibilité du navigateur

Vous trouverez la liste des navigateurs compatibles avec Programmable Search Engine cliquez ici.

Audience

Cette documentation est destinée aux développeurs qui souhaitent ajouter Google Programmable une fonctionnalité de recherche sur leurs pages.

Programmable Search Elements

Vous pouvez utiliser le balisage HTML pour ajouter un Programmable Search Element à votre page. Chaque se compose d'au moins un composant: un champ de recherche, un bloc de recherche résultats, ou les deux. Le champ de recherche accepte les entrées utilisateur pour les éléments suivants : différentes manières:

• Requête de recherche saisie dans le champ de saisie de texte
• Une 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 dans le de différentes manières:

• Une chaîne de requête intégrée dans une URL
• Exécution programmatique

Voici les types de Programmable Search Elements disponibles:

Vous pouvez ajouter autant d'éléments de recherche valides que vous le souhaitez à votre page Web. Pour deux colonnes tous les composants requis (champ de recherche et champ de recherche bloc de résultats) doit être présente.

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>

Créer différentes options de mise en page à l'aide de Programmable Search Elements

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.

En savoir plus sur les options de mise en page

Personnaliser des é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 remplacer les configurations créées dans le Programmable Search Engine panneau de configuration. Cela vous permet de créer une expérience de recherche spécifique à 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 du paramètre L'attribut queryParameterName et la chaîne de requête utilisateur sont utilisée pour 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 Programmable Search Engine pour activer des fonctionnalités telles que la saisie semi-automatique ou les affinements, vous pouvez utiliser des attributs pour personnaliser ces fonctionnalités. Toute personnalisation que vous spécifiez à l'aide de ces attributs remplace les paramètres définis dans le panneau de configuration. L'exemple suivant crée un élément de recherche à deux colonnes avec les fonctionnalités 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

<div class="gcse-searchbox" data-gname="storesearch"></div>
<div class="gcse-searchresults" data-gname="storesearch"></div>

Rappels

</ph>

Les rappels permettent un contrôle détaillé des processus d'initialisation et de recherche des éléments de recherche. Ils sont enregistrés avec le code JavaScript de l'élément de recherche via le __gcse global. . Enregistrer les rappels illustre l'enregistrement de toutes les les rappels pris en charge.

  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 la recherche. dans le DOM. Si parsetags est défini sur explicit dans __gcse, le code JavaScript pour élément de recherche laisse les éléments de recherche à afficher rappel d'initialisation (comme indiqué dans Enregistrer des rappels). Cela peut être utilisé pour sélectionner des éléments à afficher ou pour différer le rendu jusqu'à ce qu'ils soient nécessaires. Elle peut également remplacer les attributs des éléments : par exemple, elle peut transformer de recherche configuré via le panneau de configuration ou les attributs HTML pour utiliser effectuer une recherche dans un champ de recherche d'images, ou indiquer que les requêtes envoyées via un formulaire Programmable Search Engine sont exécuté dans un élément searchresults-only. <ph type="x-smartling-placeholder"></ph> Voir une démonstration

Le rôle du rappel d'initialisation est contrôlé par la valeur de parsetags. de __gcse.

• Si sa valeur est onload, le Search Element JavaScript affiche automatiquement tous les éléments de recherche de la page. Le rappel d'initialisation toujours appelé, mais il n'est pas responsable de l'affichage des éléments de recherche.
• Si sa valeur est explicit, le code JavaScript du Search Element n'affiche pas Search Elements. Le rappel peut les afficher de manière sélective à l'aide de la méthode fonction render(), ou afficher tous les éléments de recherche avec la fonction go()

Le code suivant montre comment afficher un champ de recherche, ainsi que les résultats de recherche, dans une div, à l'aide du rappel d'analyse et d'initialisation explicit:

    <div id="test"></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
};

<script async
  src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>

Rechercher des rappels

Le code JavaScript de l'élément de recherche prend en charge six rappels qui fonctionnent dans le flux de contrôle de la recherche. Les rappels de recherche sont fournis par paires : un rappel de recherche sur le Web et un rappel de recherche d'images correspondant :

• Démarrage de la recherche <ph type="x-smartling-placeholder">
  </ph>
  • Recherche d'images
  • Pour la recherche sur le Web
• Résultats prêts <ph type="x-smartling-placeholder">
  </ph>
  • Recherche d'images
  • Pour la recherche sur le Web
• Résultats affichés <ph type="x-smartling-placeholder">
  </ph>
  • Recherche d'images
  • Pour la recherche sur le Web

Comme le rappel d'initialisation,les rappels de recherche sont configuré à l'aide d'entrées dans l'objet __gcse. Cela se produit lorsque l'élément de recherche JavaScript démarre. Les modifications apportées à __gcse après le démarrage sont ignorées.

Chacun de ces rappels reçoit le gName pour l'élément de recherche en tant qu'argument. Le gname est utile lorsqu'une page contient plusieurs recherches. Effectuez une recherche d'un élément gname à l'aide de l'attribut data-gname:

<div class="gcse-searchbox" data-gname="storesearch"></div>

Si le code HTML n'identifie pas le gname, le code JavaScript de l'élément de recherche génère une valeur qui restent cohérents jusqu'à ce que le code HTML soit modifié.

Rappel de démarrage de la recherche d'images/sur le Web

Les rappels de démarrage de la recherche sont invoqués immédiatement avant les requêtes JavaScript du composant Search Element les résultats de recherche à partir de son serveur. Exemple de cas d'utilisation : utiliser l'heure locale pour 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 (éventuellement modifiée par la recherche) l'élément JavaScript.)

Le rappel renvoie la valeur à utiliser comme requête pour cette recherche. Si une valeur 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 Ajoutez dynamiquement le rappel à l'objet avec JavaScript:

window.__gcse['searchCallbacks']['web']['starting'] = function(gname, query) {...};

Exemple de rappel de démarrage de la recherche

L'exemple de rappel de démarrage de la recherche dans Example Search Start Callback ajoute soit morning ou afternoon à la requête selon 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>

Rappel prêt pour les résultats de la recherche d'images/Web

Ces rappels sont invoqués immédiatement avant que le code JavaScript du Search Element affiche les résultats mis en avant. résultats. Un exemple de cas d'utilisation serait un rappel qui affiche des promotions et aboutit à 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 généré ces résultats

promos

Un tableau d'objets promotion, qui correspondent aux valeurs correspondantes promotions pour à la requête de l'utilisateur. Consultez la définition de l'objet Promotion.

results

Tableau d'objets de résultat. Consultez le définition de l'objet "result".

div

Un tag div HTML placé dans le DOM à l'emplacement habituel de l'élément de recherche placer des promotions et des résultats de recherche. Normalement, le code JavaScript de l'élément de recherche gère insère cet élément div, mais ce rappel peut choisir d'arrêter l'affichage automatique des résultats. et utilisez ce div pour afficher les résultats eux-mêmes.

Si ce rappel renvoie une valeur true, le code JavaScript de l'élément de recherche passe à son le pied de page de la page.

Exemple de résultats de rappel prêts

L'exemple de rappel resultsReady dans L'exemple de rappel prêt pour les résultats remplace la présentation par défaut. des promotions et des résultats, avec 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;
    };

  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>

Rappel affiché dans les résultats de la recherche d'images/sur le Web

Ces rappels sont invoqués immédiatement avant que le code JavaScript du Search Element n'affiche la page. pied de page. Des exemples de cas d'utilisation incluent un rappel qui ajoute le contenu des résultats que la recherche ne s'affiche pas, comme une case à cocher Enregistrer cette ou des informations affiché automatiquement, ou un rappel qui ajoute des boutons for more information (pour plus d'informations).

Si un rappel des résultats rendus a besoin d'informations qui se trouvaient dans promos et results du rappel "results ready", il peut les transmettre entre eux, comme ceci:

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 des résultats.

Aucune valeur renvoyée.

Exemple de rappel de résultats affichés

L'exemple de rappel resultsRendered dans Example Results Rendered Callback ajoute un élément 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);
    }
  };

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 affichés a besoin Les informations transmises au rappel "results ready" peuvent transmettre ces données les rappels. L'exemple suivant illustre l'une des nombreuses méthodes permettant de transmettre une valeur de note d'un richSnippet du rappel "results ready" vers les résultats affichés de commande.

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};
};

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 Autres exemples de rappel

Propriétés des résultats mis en avant et des résultats

En utilisant la notation JSDoc, voici les propriétés de promotion et result. Ici, nous indiquons toutes les propriétés qui peuvent être présentes. La présence de nombreuses propriétés dépendent 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 a le type non précis d'un tableau de d'objets. Les valeurs des entrées de ce tableau sont contrôlées par le paramètre données structurées trouvés sur la page Web pour chaque résultat de recherche. Par exemple, un site de critiques 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 éléments suivants : fonctions statiques:

var element = google.search.cse.element.getElement('element1');
            element.execute('news');