Criar uma interface de pesquisa com o widget de pesquisa

O widget da Pesquisa fornece uma interface de pesquisa personalizada para aplicativos da Web. O widget requer apenas uma pequena quantidade de HTML e JavaScript para implementar e habilita recursos de pesquisa comuns, como atributos e paginação. Também é possível personalizar partes da interface com CSS e JavaScript.

Se você precisar de mais flexibilidade do que a oferecida pelo widget, use a API Query. Para informações sobre como criar uma interface de pesquisa com a API Query, consulte Como criar uma interface de pesquisa com a API Query.

Criar uma interface de pesquisa

A criação da interface de pesquisa requer várias etapas:

1. Configurar um app de pesquisa
2. Gerar um ID do cliente para o app
3. Adicionar marcação HTML à caixa de pesquisa e aos resultados
4. Carregar o widget na página
5. Inicializar o widget

Configurar um app de pesquisa

Cada interface de pesquisa precisa ter um app de pesquisa definido no Admin Console. O aplicativo de pesquisa fornece mais informações para a consulta, como as origens de dados, os atributos e as configurações de qualidade de pesquisa.

Para criar um aplicativo de pesquisa, consulte Criar uma experiência de pesquisa personalizada.

Gerar um ID de cliente para o aplicativo

Além das etapas em Configurar o acesso à API do Google Cloud Search, você também precisa gerar um ID de cliente para o aplicativo da Web.

Configurar um projeto

Ao configurar o projeto:

• Selecione o tipo de cliente do navegador da Web
• Forneça o URI de origem do seu aplicativo.
• Anote o ID do cliente que foi criado. Você precisará dele para concluir as próximas etapas. A chave secreta do cliente não é necessária para o widget.

Para mais informações, consulte OAuth 2.0 para aplicativos da Web do cliente.

Adicionar marcação HTML

O widget requer uma pequena quantidade de HTML para funcionar. Forneça:

• Um elemento input para a caixa de pesquisa.
• um elemento para ancorar a sugestão pop-up;
• um elemento para conter os resultados da pesquisa;
• (opcional) um elemento para conter os controles de atributos.

O snippet HTML a seguir mostra o HTML de um widget de pesquisa, em que os elementos a serem vinculados são identificados pelo atributo id:

<div id="search_bar">
  <div id="suggestions_anchor">
    <input type="text" id="search_input" placeholder="Search for...">
  </div>
</div>
<div id="facet_results"></div>
<div id="search_results"></div>

Carregar o widget

O widget é carregado dinamicamente por meio do script do carregador. Para incluir o carregador, use a tag <script>, conforme mostrado:

<!-- Google API loader -->
<script src="https://apis.google.com/js/api.js?mods=enable_cloud_search_widget&onload=onLoad" async defer></script>

Forneça um callback onload na tag de script. A função é chamada quando o carregador está pronto. Quando o carregador estiver pronto, continue a carregar o widget chamando gapi.load() para carregar os módulos do cliente da API, do Login do Google e do Cloud Search.

/**
* Load the cloud search widget & auth libraries. Runs after
* the initial gapi bootstrap library is ready.
*/
function onLoad() {
  gapi.load('client:auth2:cloudsearch-widget', initializeApp)
}

A função initializeApp() é chamada depois que todos os módulos são carregados.

Inicializar o widget

Primeiro, inicialize a biblioteca de cliente chamando gapi.client.init() ou gapi.auth2.init() com o ID do cliente gerado e o escopo https://www.googleapis.com/auth/cloud_search.query. Em seguida, use as classes gapi.cloudsearch.widget.resultscontainer.Builder e gapi.cloudsearch.widget.searchbox.Builder para configurar o widget e vinculá-lo aos elementos HTML.

No exemplo a seguir, mostramos como inicializar o widget:

/**
 * Initialize the app after loading the Google API client &
 * Cloud Search widget.
 */
function initializeApp() {
  // Load client ID & search app.
  loadConfiguration().then(function() {
    // Set API version to v1.
    gapi.config.update('cloudsearch.config/apiVersion', 'v1');

    // Build the result container and bind to DOM elements.
    var resultsContainer = new gapi.cloudsearch.widget.resultscontainer.Builder()
      .setSearchApplicationId(searchApplicationName)
      .setSearchResultsContainerElement(document.getElementById('search_results'))
      .setFacetResultsContainerElement(document.getElementById('facet_results'))
      .build();

    // Build the search box and bind to DOM elements.
    var searchBox = new gapi.cloudsearch.widget.searchbox.Builder()
      .setSearchApplicationId(searchApplicationName)
      .setInput(document.getElementById('search_input'))
      .setAnchor(document.getElementById('suggestions_anchor'))
      .setResultsContainer(resultsContainer)
      .build();
  }).then(function() {
    // Init API/oauth client w/client ID.
    return gapi.auth2.init({
        'clientId': clientId,
        'scope': 'https://www.googleapis.com/auth/cloud_search.query'
    });
  });
}

O exemplo acima se refere a duas variáveis para configuração definidas como:

/**
* Client ID from OAuth credentials.
*/
var clientId = "...apps.googleusercontent.com";

/**
* Full resource name of the search application, such as
* "searchapplications/<your-id>".
*/
var searchApplicationName = "searchapplications/...";

Personalizar a experiência de login

Por padrão, o widget solicita que os usuários façam login e autorizem o app no momento em que começam a digitar uma consulta. Use o Login do Google para sites para oferecer uma experiência de login mais personalizada para os usuários.

Autorizar usuários diretamente

Use o recurso Fazer login com o Google para monitorar o estado de login e fazer login ou logout dos usuários conforme necessário. Por exemplo, o exemplo a seguir observa o estado isSignedIn para monitorar alterações de login e usa o método GoogleAuth.signIn() para iniciar o login com um clique em um botão:

// Handle sign-in/sign-out.
let auth = gapi.auth2.getAuthInstance();

// Watch for sign in status changes to update the UI appropriately.
let onSignInChanged = (isSignedIn) => {
  // Update UI to switch between signed in/out states
  // ...
}
auth.isSignedIn.listen(onSignInChanged);
onSignInChanged(auth.isSignedIn.get()); // Trigger with current status.

// Connect sign-in/sign-out buttons.
document.getElementById("sign-in").onclick = function(e) {
  auth.signIn();
};
document.getElementById("sign-out").onclick = function(e) {
  auth.signOut();
};

Veja mais detalhes em Fazer login com o Google.

Usuários com login automático

Para simplificar ainda mais a experiência de login, pré-autorize o aplicativo em nome dos usuários da sua organização. Essa técnica também é útil se você usar o Cloud Identity Aware Proxy para proteger o aplicativo.

Para mais informações, consulte Usar o Login do Google com apps de TI.

Personalize a interface

É possível alterar a aparência da interface de pesquisa com uma combinação de técnicas:

• Substituir os estilos por CSS.
• Decorar os elementos com um adaptador.
• Criar elementos personalizados com um adaptador.

Substituir os estilos por CSS

O widget da Pesquisa vem com o próprio CSS para estilizar elementos de sugestão e de resultados, bem como os controles de paginação. É possível alterar esses elementos conforme necessário.

Durante o carregamento, o widget de pesquisa carrega dinamicamente sua folha de estilo padrão. Isso ocorre depois que as folhas de estilo do aplicativo são carregadas, aumentando a prioridade das regras. Para garantir que seus próprios estilos tenham precedência sobre os estilos padrão, use seletores de ancestral para aumentar a especificidade das regras padrão.

Por exemplo, a regra a seguir não tem efeito se carregada em uma tag link ou style estática no documento.

.cloudsearch_suggestion_container {
  font-size: 14px;
}

Em vez disso, qualifique a regra com o código ou a classe do contêiner ancestral declarado na página.

#suggestions_anchor .cloudsearch_suggestion_container {
  font-size: 14px;
}

Para ver uma lista de classes de suporte e exemplos de HTML produzidos pelo widget, consulte a referência Classes CSS compatíveis.

Decorar os elementos com um adaptador

Para decorar um elemento antes da renderização, crie e gere um adaptador que implemente um dos métodos de decoração, como decorateSuggestionElement ou decorateSearchResultElement..

Por exemplo, os adaptadores a seguir adicionam uma classe personalizada aos elementos sugestão e resultado.

/**
 * Search box adapter that decorates suggestion elements by
 * adding a custom CSS class.
 */
function SearchBoxAdapter() {}
SearchBoxAdapter.prototype.decorateSuggestionElement = function(element) {
  element.classList.add('my-suggestion');
}

/**
 * Results container adapter that decorates suggestion elements by
 * adding a custom CSS class.
 */
function ResultsContainerAdapter() {}
ResultsContainerAdapter.prototype.decorateSearchResultElement = function(element) {
  element.classList.add('my-result');
}

Para registrar o adaptador ao inicializar o widget, use o método setAdapter() da respectiva classe Builder:

// Build the result container and bind to DOM elements.
var resultsContainer = new gapi.cloudsearch.widget.resultscontainer.Builder()
  .setAdapter(new ResultsContainerAdapter())
  // ...
  .build();

// Build the search box and bind to DOM elements.
var searchBox = new gapi.cloudsearch.widget.searchbox.Builder()
  .setAdapter(new SearchBoxAdapter())
  // ...
  .build();

Os decoradores podem modificar os atributos do elemento de contêiner, bem como quaisquer elementos filhos. Elementos filho podem ser adicionados ou removidos durante a decoração. No entanto, se você for fazer alterações estruturais nos elementos, é melhor criá-los diretamente em vez de decorar.

Criar elementos personalizados com um adaptador

Para criar um elemento personalizado para uma sugestão, um contêiner de atributo ou um resultado da pesquisa, crie e registre um adaptador que implemente createSuggestionElement, createFacetResultElement ou createSearchResultElement respectivamente.

Os adaptadores a seguir ilustram a criação de elementos personalizados de sugestão e de pesquisa usando tags HTML <template>.

/**
 * Search box adapter that overrides creation of suggestion elements.
 */
function SearchBoxAdapter() {}
SearchBoxAdapter.prototype.createSuggestionElement = function(suggestion) {
  let template = document.querySelector('#suggestion_template');
  let fragment = document.importNode(template.content, true);
  fragment.querySelector('.suggested_query').textContent = suggestion.suggestedQuery;
  return fragment.firstElementChild;
}

/**
 * Results container adapter that overrides creation of result elements.
 */
function ResultsContainerAdapter() {}
ResultsContainerAdapter.prototype.createSearchResultElement = function(result) {
  let template = document.querySelector('#result_template');
  let fragment = document.importNode(template.content, true);
  fragment.querySelector('.title').textContent = result.title;
  fragment.querySelector('.title').href = result.url;
  let snippetText = result.snippet != null ?
    result.snippet.snippet : '';
  fragment.querySelector('.query_snippet').innerHTML = snippetText;
  return fragment.firstElementChild;
}

Para registrar o adaptador ao inicializar o widget, use o método setAdapter() da respectiva classe Builder:

// Build the result container and bind to DOM elements.
var resultsContainer = new gapi.cloudsearch.widget.resultscontainer.Builder()
  .setAdapter(new ResultsContainerAdapter())
  // ...
  .build();

// Build the search box and bind to DOM elements.
var searchBox = new gapi.cloudsearch.widget.searchbox.Builder()
  .setAdapter(new SearchBoxAdapter())
  // ...
  .build();

A criação de elementos de atributos personalizados com createFacetResultElement está sujeita a várias restrições:

• É preciso anexar a classe CSS cloudsearch_facet_bucket_clickable ao elemento em que os usuários clicam para alternar um bucket.
• É preciso unir cada bucket em um elemento com a classe CSS cloudsearch_facet_bucket_container.
• Não é possível renderizar os buckets em uma ordem diferente da que eles aparecem na resposta.

Por exemplo, o snippet a seguir renderiza atributos usando links em vez de caixas de seleção.

/**
 * Results container adapter that intercepts requests to dynamically
 * change which sources are enabled based on user selection.
 */
function ResultsContainerAdapter() {
  this.selectedSource = null;
}

ResultsContainerAdapter.prototype.createFacetResultElement = function(result) {
  // container for the facet
  var container = document.createElement('div');

  // Add a label describing the facet (operator/property)
  var label = document.createElement('div')
  label.classList.add('facet_label');
  label.textContent = result.operatorName;
  container.appendChild(label);

  // Add each bucket
  for(var i in result.buckets) {
    var bucket = document.createElement('div');
    bucket.classList.add('cloudsearch_facet_bucket_container');

    // Extract & render value from structured value
    // Note: implementation of renderValue() not shown
    var bucketValue = this.renderValue(result.buckets[i].value)
    var link = document.createElement('a');
    link.classList.add('cloudsearch_facet_bucket_clickable');
    link.textContent = bucketValue;
    bucket.appendChild(link);
    container.appendChild(bucket);
  }
  return container;
}

// Renders a value for user display
ResultsContainerAdapter.prototype.renderValue = function(value) {
  // ...
}

Personalizar o comportamento da pesquisa

As configurações do app de pesquisa representam a configuração padrão de uma interface de pesquisa e são estáticas. Para implementar filtros ou atributos dinâmicos, por exemplo, permitir que os usuários alternem as origens de dados, é possível substituir as configurações do app de pesquisa interceptando a solicitação de pesquisa com um adaptador.

Implemente um adaptador com o método interceptSearchRequest para modificar solicitações feitas à API de pesquisa antes da execução.

Por exemplo, o seguinte adaptador intercepta solicitações para restringir consultas a uma origem selecionada pelo usuário:

/**
 * Results container adapter that intercepts requests to dynamically
 * change which sources are enabled based on user selection.
 */
function ResultsContainerAdapter() {
  this.selectedSource = null;
}
ResultsContainerAdapter.prototype.interceptSearchRequest = function(request) {
  if (!this.selectedSource || this.selectedSource == 'ALL') {
    // Everything selected, fall back to sources defined in the search
    // application.
    request.dataSourceRestrictions = null;
  } else {
    // Restrict to a single selected source.
    request.dataSourceRestrictions = [
      {
        source: {
          predefinedSource: this.selectedSource
        }
      }
    ];
  }
  return request;
}

Para registrar o adaptador ao inicializar o widget, use o método setAdapter() ao criar o ResultsContainer

var resultsContainerAdapter = new ResultsContainerAdapter();
// Build the result container and bind to DOM elements.
var resultsContainer = new gapi.cloudsearch.widget.resultscontainer.Builder()
  .setAdapter(resultsContainerAdapter)
  // ...
  .build();

O HTML a seguir é usado para exibir uma caixa de seleção para filtragem por origens:

<div>
  <span>Source</span>
  <select id="sources">
    <option value="ALL">All</option>
    <option value="GOOGLE_GMAIL">Gmail</option>
    <option value="GOOGLE_DRIVE">Drive</option>
    <option value="GOOGLE_SITES">Sites</option>
    <option value="GOOGLE_GROUPS">Groups</option>
    <option value="GOOGLE_CALENDAR">Calendar</option>
    <option value="GOOGLE_KEEP">Keep</option>
  </select>
</div>

O código a seguir escuta a alteração, define a seleção e executa a consulta novamente, se necessário.

// Handle source selection
document.getElementById('sources').onchange = (e) => {
  resultsContainerAdapter.selectedSource = e.target.value;
  let request = resultsContainer.getCurrentRequest();
  if (request.query) {
    // Re-execute if there's a valid query. The source selection
    // will be applied in the interceptor.
    resultsContainer.resetState();
    resultsContainer.executeRequest(request);
  }
}

Você também pode interceptar a resposta da pesquisa implementando interceptSearchResponse no adaptador.

Fixar a versão da API

Por padrão, o widget usa a versão estável mais recente da API. Para bloquear uma versão específica, defina o parâmetro de configuração cloudsearch.config/apiVersion como a versão preferida antes de inicializar o widget.

gapi.config.update('cloudsearch.config/apiVersion', 'v1');

A versão da API será definida como 1.0 por padrão caso não seja configurada ou tenha um valor inválido.

Fixar a versão do widget

Para evitar alterações inesperadas nas interfaces de pesquisa, defina o parâmetro de configuração cloudsearch.config/clientVersion como mostrado:

gapi.config.update('cloudsearch.config/clientVersion', 1.1);

A versão do widget será definida como 1.0 por padrão caso não seja configurada ou tenha um valor inválido.

Proteja a interface de pesquisa

Os resultados da pesquisa contêm informações altamente confidenciais. Siga as práticas recomendadas para proteger aplicativos da Web, especialmente contra ataques de clickjacking (link em inglês).

Para mais informações, consulte o Projeto guia OWASP (em inglês).

Ativar depuração

Use interceptSearchRequest para ativar a depuração do widget de pesquisa. Exemplo:

  if (!request.requestOptions) {
  // Make sure requestOptions is populated
  request.requestOptions = {};
  }
  // Enable debugging
  request.requestOptions.debugOptions = {enableDebugging: true}

  return request;