Criar uma interface de pesquisa com o widget de pesquisa

O widget da Pesquisa fornece uma interface de pesquisa personalizada para aplicativos da Web. Ele requer o mínimo de HTML e JavaScript para ser implementado e é compatível com recursos comuns, como atributos e paginação. Também é possível personalizar a interface com CSS e JavaScript.

Se você precisar de mais flexibilidade, use 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 estas etapas:

1. Configure um app de pesquisa.
2. Gere um ID de cliente para o aplicativo.
3. Adicione marcação HTML à caixa de pesquisa e aos resultados.
4. Carregue o widget na página.
5. Inicialize o widget.

Configurar um aplicativo de pesquisa

Cada interface de pesquisa precisa de um aplicativo de pesquisa definido no Admin Console. O aplicativo fornece configurações de consulta, como origens de dados, atributos e parâmetros de qualidade de pesquisa.

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

Gerar um ID do cliente para o app

Além das etapas em Configurar o acesso à API Cloud Search, gere um ID de cliente para seu aplicativo da Web.

Configurar um projeto

Ao configurar o projeto:

• Selecione o tipo de cliente Navegador da Web.
• Forneça o URI de origem do seu app.
• Anote o ID do cliente. O widget não exige uma chave secreta do cliente.

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

Adicionar marcação HTML

O widget requer estes elementos HTML:

• Um elemento input para a caixa de pesquisa.
• Um elemento para ancorar a caixa de diálogo de sugestão.
• Um elemento para os resultados da pesquisa.
• (Opcional) Um elemento para controles de atributos.

Este snippet mostra elementos identificados pelos atributos id:

serving/widget/public/with_css/index.html

Ver no GitHub

<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

Inclua o carregador usando uma tag <script>:

serving/widget/public/with_css/index.html

Ver no GitHub

<!-- 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. Quando o carregador estiver pronto, chame gapi.load() para carregar os módulos do cliente API, do Login do Google e do Cloud Search.

serving/widget/public/with_css/app.js

Ver no GitHub

/**
* 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)
}

Inicializar o widget

Inicialize a biblioteca de cliente usando gapi.client.init() ou gapi.auth2.init() com seu ID de cliente e o escopo https://www.googleapis.com/auth/cloud_search.query. Use as classes de builder para configurar e vincular o widget.

Exemplo de inicialização:

serving/widget/public/with_css/app.js

Ver no GitHub

/**
 * 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'
    });
  });
}

Variáveis de configuração:

serving/widget/public/with_css/app.js

Ver no GitHub

/**
* 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

O widget pede que os usuários façam login quando começam a digitar. Use o Login do Google para sites e tenha uma experiência personalizada.

Autorizar usuários diretamente

Use o recurso Fazer login com o Google para monitorar e gerenciar estados de login. Este exemplo usa GoogleAuth.signIn() em um clique de botão:

serving/widget/public/with_signin/app.js

Ver no GitHub

// 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();
};

Fazer login automático dos usuários

Pré-autorize o aplicativo para os usuários da sua organização e simplifique o login. Isso também é útil com o Cloud Identity Aware Proxy. Consulte Usar o Login do Google com aplicativos de TI.

Personalizar a interface

Para mudar a aparência do widget, faça o seguinte:

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

Substituir estilos com CSS

O widget inclui o próprio CSS. Para substituir, use seletores de ancestral para aumentar a especificidade:

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

Consulte a referência Classes CSS compatíveis.

Decorar elementos com um adaptador

Crie e registre um adaptador para modificar elementos antes da renderização. Este exemplo adiciona uma classe CSS personalizada:

serving/widget/public/with_decorated_element/app.js

Ver no GitHub

/**
 * 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');
}

Registre o adaptador durante a inicialização:

serving/widget/public/with_decorated_element/app.js

Ver no GitHub

// 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();

Criar elementos personalizados com um adaptador

Implemente createSuggestionElement, createFacetResultElement ou createSearchResultElement para criar componentes de interface personalizados. Este exemplo usa tags HTML <template>:

serving/widget/public/with_custom_element/app.js

Ver no GitHub

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

Registre o adaptador:

serving/widget/public/with_custom_element/app.js

Ver no GitHub

// 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 elementos de refinamento personalizados precisam seguir estas regras:

• Anexe cloudsearch_facet_bucket_clickable a elementos clicáveis.
• Encapsule cada bucket em um cloudsearch_facet_bucket_container.
• Mantenha a ordem dos intervalos da resposta.

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

serving/widget/public/with_custom_facet/app.js

Ver no GitHub

/**
 * 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

Substitua as configurações do app de pesquisa interceptando solicitações com um adaptador. Implemente interceptSearchRequest para modificar solicitações antes da execução. Este exemplo restringe as consultas a uma fonte selecionada:

serving/widget/public/with_request_interceptor/app.js

Ver no GitHub

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

Registre o adaptador:

serving/widget/public/with_request_interceptor/app.js

Ver no GitHub

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:

serving/widget/public/with_request_interceptor/index.html

Ver no GitHub

<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 mudança, define a seleção e executa a consulta novamente, se necessário.

serving/widget/public/with_request_interceptor/app.js

Ver no GitHub

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

É possível também interceptar a resposta da pesquisa implementando interceptSearchResponse no adaptador.

Fixar versões

• Versão da API: defina cloudsearch.config/apiVersion antes da inicialização.
• Versão do widget: use gapi.config.update('cloudsearch.config/clientVersion', 1.1).

O padrão é 1,0 se não estiver definido.

Por exemplo, para fixar o widget na versão 1.1:

serving/widget/public/basic/app.js

Ver no GitHub

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

Proteja a interface de pesquisa

Siga as práticas recomendadas de segurança para aplicativos da Web, especialmente para evitar clickjacking.

Ativar depuração

Use interceptSearchRequest para ativar a depuração:

if (!request.requestOptions) {
  request.requestOptions = {};
}
request.requestOptions.debugOptions = {enableDebugging: true};
return request;