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 realizar a implementação 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 esta página.
Criar uma interface de pesquisa
A criação da interface de pesquisa requer várias etapas:
- Configurar um app de pesquisa
- Gerar um ID do cliente para o app
- Adicionar marcação HTML à caixa de pesquisa e aos resultados
- Carregar o widget na página
- Inicializar o widget
Configurar um aplicativo de pesquisa
Cada interface de pesquisa precisa ter um aplicativo 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 mais informações sobre aplicativos 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 REST do Google Cloud Search, também é preciso gerar um ID de cliente para o aplicativo da Web.
Ao configurar o projeto:
- Selecione o tipo de cliente do navegador da Web
- Forneça o URI de origem (em inglês) do seu aplicativo.
- Anote o ID de 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 lado 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
:
Carregar o widget
O widget é carregado dinamicamente por meio do script do carregador. Para incluir o carregador, use a tag <script>
, conforme mostrado:
Forneça um callback onload
na tag do script. A função é chamada quando o carregador está pronto. Quando isso acontecer, continue a carregar o widget chamando gapi.load()
para carregar os módulos de cliente da API, do Login do Google e do Cloud Search.
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 seu ID de 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:
O exemplo acima se refere a duas variáveis para configuração definidas como:
Personalizar a experiência de login
Por padrão, o widget solicita que os usuários façam login e autorizem o aplicativo 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 a biblioteca do Login do Google para sites para monitorar o estado de login e fazer login ou logout dos usuários conforme necessário. Por exemplo, a amostra a seguir observa o estado isSignedIn
para monitorar as alterações de login e usa o método GoogleAuth.signIn()
para iniciar o login com o clique em um botão:
Para mais detalhes, consulte Como integrar o Login do Google no seu app da Web.
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 aplicativos de TI.
Personalizar 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 o estilo desses 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 estática link
ou style
no documento.
.cloudsearch_suggestion_container {
font-size: 14px;
}
Em vez disso, qualifique a regra com o ID ou a classe do contêiner de ancestral declarado na página.
#suggestions_anchor .cloudsearch_suggestion_container {
font-size: 14px;
}
Para ver uma lista de classes compatíveis 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 de renderizar, crie e registre 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.
Para registrar o adaptador ao inicializar o widget, use o método setAdapter()
da respectiva classe Builder
:
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, contêiner de atributo ou resultado de 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 resultados de sugestão e pesquisa usando tags HTML <template>
.
Para registrar o adaptador ao inicializar o widget, use o método setAdapter()
da respectiva classe Builder
:
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 intervalo. - É preciso unir cada intervalo em um elemento com a classe CSS
cloudsearch_facet_bucket_container
. - Não é possível renderizar os intervalos em uma ordem diferente da usada para exibi-los na resposta.
Por exemplo, o snippet a seguir renderiza atributos usando links em vez de caixas de seleção.
Personalizar o comportamento da pesquisa
As configurações de aplicativo de pesquisa são estáticas e representam a configuração padrão de uma interface de pesquisa. Para implementar filtros ou atributos dinâmicos, como, por exemplo, permitir que os usuários alternem as origens de dados, é possível substituir as configurações do aplicativo 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 search antes da execução.
Por exemplo, o seguinte adaptador intercepta solicitações para restringir consultas a uma origem selecionada pelo usuário:
Para registrar o adaptador ao inicializar o widget, use o método setAdapter()
ao criar ResultsContainer
O HTML a seguir é usado para exibir uma caixa de seleção para filtragem por origens:
O código a seguir escuta a alteração, define a seleção e executa a consulta novamente, se necessário.
É possível também 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 manter uma versão específica, defina o parâmetro de configuração cloudsearch.config/apiVersion
para a versão preferida antes de inicializar o widget.
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
conforme 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 (em inglês).
Para mais informações, consulte o Projeto guia OWASP (em inglês).
Ativar a depuração
Use interceptSearchRequest
para ativar a depuração do widget de pesquisa. Por exemplo:
if (!request.requestOptions) {
// Make sure requestOptions is populated
request.requestOptions = {};
}
// Enable debugging
request.requestOptions.debugOptions = {enableDebugging: true}
return request;