Widget de pesquisa Freebase

  1. Sobre o Freebase Suggest
  2. Como adicionar o Freebase Suggest ao seu site
  3. Opções de configuração
  4. Modificar o CSS
  5. Como os eventos funcionam
  6. Mais informações e perguntas frequentes
  7. Exemplos e receitas

Sobre o Freebase Suggest

O Freebase Suggest é um plug-in do jQuery que adiciona o preenchimento automático de tópicos do Freebase a caixas de pesquisa em seu site. Os usuários começam a digitar texto, e o widget sugere correspondências relevantes de milhões de temas em Freebase.com ou qualquer subconjunto de tipos como pessoas, locais ou animais. O menu suspenso de tópicos ajuda o usuário a selecionar o item correto que é identificado de forma exclusiva com um ID do Freebase.

Sugestão do Freebase.png

Recursos

  • Vários navegadores, com base no jQuery, testado no IE7+, FF2+, Safari 3+ e Chrome (a versão mínima do jquery é 1.4.4)
  • Vários domínios Sem a necessidade de servidores proxy, graças ao JSONP.
  • Hospedado pelo Google em gstatic.com
  • Sem custo financeiro! Os Termos básicos padrão e os Termos da API Google Developer se aplicam.

Experimente!

Sugestão do Freebase no mundo real

Sites que usam o Freebase Suggest:

Por que usar o Freebase Suggest?

  • Com o preenchimento automático, seus usuários digitam menos para inserir mais dados.
  • A entrada de dados é divertida e precisa.
  • Reduza a carga cognitiva para seus usuários com as imagens e as descrições no menu suspenso do tópico.
  • Use identificadores fortes em vez de palavras-chave de texto. O nome "Sting" é ambíguo, mas os IDs de Freebase /en/sting e /en/sting_1959 não são.
  • Evite nomes duplicados para a mesma entidade. Puff Daddy Diddy, Sean Combs se refere a /en/sean_combs.

Como adicionar o Freebase Suggest ao seu site

Para adicionar a sugestão do Freebase à sua página da Web, inclua o código a seguir na fonte do seu site. Você também pode obter e usar uma chave de API para estender a funcionalidade do Freebase Suggest.

Código a ser incluído no seu site

Inclua o seguinte no <head> do seu documento HTML:

<link type="text/css" rel="stylesheet" href="https://www.gstatic.com/freebase/suggest/4_2/suggest.min.css" />
<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.js"></script>
<script type="text/javascript" src="https://www.gstatic.com/freebase/suggest/4_2/suggest.min.js"></script>
<script type="text/javascript">
$(function() {
  $("#myinput").suggest({filter:'(all type:/film/director)'});
});
</script>

Em seguida, use um campo de entrada no documento <body> semelhante a este:

<input type="text" id="myinput"/>

Obtenção de uma chave de API

Ter uma chave de API permite que seu aplicativo faça solicitações de sugestão. Sem uma chave de API, o widget funcionará para fins de teste limitados. Para receber uma chave, siga as instruções na nossa página Primeiros passos.

Depois de receber uma chave, transmita-a para o Freebase Suggest com algo como:

$(function() {
  $("#myinput").suggest({ "key" : "<your api key>"});
});

Opções de configuração

A tabela a seguir descreve as opções de configuração do Freebase Suggest.

Nome Tipo Padrão Descrição
avançado Booleano verdadeiro Se for verdadeiro, o Freebase Suggest vai analisar e processar pares de name:value in-line na entrada como restrições de filtro adicionais. Por exemplo, para 'bob type:artist contributed_to:"Love and Theft"', uma restrição de filtro adicional, '(all type:artist contributed_to:"Love and Theft")' é transmitido para a pesquisa. Além disso, quando o avançado é verdadeiro, o Freebase Suggest reconhece códigos e MIDs do Freebase para que seja possível pesquisar diretamente uma entidade pelo ID ou MID.
exata Booleano false Se for "true", especificará que a API Search retornará apenas correspondências exatas (daquilo que há na entrada). Esse valor é transmitido de maneira transparente para a API Search.
Função filter String null Especifique as restrições de filtro de pesquisa padrão que serão transmitidas de maneira transparente para a API Search como um parâmetro de filtro. Por exemplo, para restringir o Freebase Suggest para pesquisar apenas em faculdades e/ou universidades, use "(all type:/education/university)" como um filtro. Consulte API Search ou Restrições textuais para ver uma lista abrangente dos filtros de pesquisa disponíveis.
chave String null Forneça uma chave de API para a API Search padrão especificada por service_url + service_path. Acesse uma no Console de APIs.
lang String null O parâmetro lang aceita uma lista separada por vírgulas de códigos de idioma que fazem a pesquisa ser feita em todos os idiomas especificados e os resultados são classificados no primeiro idioma listado e exibido no primeiro idioma da lista que tem um nome para a entidade. Atualmente, 18 idiomas são compatíveis: en (english), es (spanish), fr (french), de (german), it (italian), pt (portuguese), zh (chinese), ja (japanese), ko (korean), ru (russian), sv (swedish), fi (finnish), da (hangish) e dulandês). O idioma inglês é o mais usado e é o idioma padrão. Esse valor é transmitido de maneira transparente para a API Search.
em lote String null Com o parâmetro scoring, é possível controlar quais componentes de pontuação de relevância são usados para calcular a pontuação final. Esse valor é transmitido de maneira transparente para a API Search.
  • entity: usa as pontuações de relevância FREEBASE e do Google, padronizando as pontuações ausentes do Google como 1.0. Esse é o padrão.
  • freebase: use somente a pontuação de relevância do Freebase.
  • schema: use para procurar entidades de esquema, como tipos, propriedades ou domínios. A contagem de links das entidades do esquema é calculada de modo diferente.
soletrar String always Os valores válidos são: always, no_results e no_spelling. Se a ortografia for solicitada e a pesquisa retornar uma correção ortográfica, o Freebase Suggest exibirá a correção na lista de sugestões. Esse valor é transmitido de forma transparente para o serviço de pesquisa.
voar Booleano, bottom verdadeiro Determina se uma descrição do menu suspenso é exibida ou não ao passar o cursor sobre ela. Se bottom, exibir menu suspenso na parte inferior da lista de sugestões. Quando a lista "Sugerir" aparece acima da caixa de entrada, o menu suspenso aparece na parte de cima da lista. Se verdadeiro, o Suggest fará o melhor para mostrar o menu suspenso do lado esquerdo ou direito da lista.
sugira_novo String null Texto a ser exibido abaixo da lista de sugestões. Na seleção, um fb-select-new é acionado.
css Objeto Substitua os nomes de classes CSS padrão usados para os vários elementos do Freebase Suggest. Consulte Como modificar o CSS para saber mais detalhes.
Prefixo de CSS String null Você pode especificar um prefixo para ser anexado aos nomes das classes dos elementos de "Suggest". Por exemplo, se css_prefix for "foo-" os nomes dos contêineres serão "foo-fbs-pane" e "foo-fbs-flyoutpane".
show_id Booleano verdadeiro Exibe o valor &&39;notable' retornado pela pesquisa. No entanto, se não estiver disponível e se for verdadeiro, o código do item será exibido.
service_url String O valor é https://www.googleapis.com/freebase/v1 Esse é o URL base do serviço Suggest.
service_path String /search service_url + service_path = URL do serviço do Suggest.
flyout_service_url String null O URL de base do serviço flyout. Se for nulo, o padrão será service_url.
fly__service_path String O valor é /search?filter=(all mid:${id})&output=(notable:/client/summary description type)&key=${key} flyout_service_url + flyout_service_path = url para o serviço de voo. '${id}' e '{key}' são substituídos pelo ID do item em passar o cursor e pela chave de API, respectivamente.
URL de serviço de imagem de saída String null É o URL de base da imagem no menu suspenso. Se for nulo, o padrão será service_url.
caminho_da_imagem_do_voo_de_voo String O valor é /image${id}?maxwidth=75&key=${key}&errorid=/freebase/no_image_png flyout_image_service_url + flyout_image_service_path = URL do serviço de imagem. '${id}' e '{key}' serão substituídos pelo ID do item em passar o cursor e pela chave de API, respectivamente.
flyout_parent String (seletor jQuery) null Por padrão, o contêiner de menu suspenso é anexado ao corpo do documento e posicionado absolutamente. O flyout_parent especifica um pai diferente, e o voo não será posicionado de forma absoluta.
alinhar String null Se align não for definido, a lista de sugestões vai ser alinhada à "esquerda" ou "direita" da caixa de entrada, dependendo da posição dela no documento. Para substituir esse comportamento e definir o alinhamento explicitamente, defina align como "left" ou "right"
status Matriz[4](String) ["Comece a digitar para receber sugestões...", "Pesquisando...", "Selecione um item da lista:", "Algo deu errado. Tente novamente mais tarde"] Mensagens de status que aparecem nos quatro estágios diferentes da sugestão; [0] quando a caixa de entrada está vazia e recebe foco. [1] ao recuperar os resultados, [2] ao exibir os resultados, [3] quando houver um erro no serviço do Suggest. É possível substituir essas mensagens de status padrão transmitindo uma matriz diferente de strings correspondentes aos quatro estágios diferentes.
primária String (seletor jQuery) null Por padrão, a lista "Sugerir" é anexada ao corpo do documento e posicionada de forma absoluta. Use parent para especificar um pai diferente, e a lista não será absolutamente posicionada.
animate Booleano false Se verdadeiro, a exibição da lista de sugestões será animada usando o efeito deslizante para baixo do jQuery.
xhr_delay Número inteiro (ms) 200 Especifica um atraso antes de retornar os resultados. Isso é útil nos casos em que mql_filters são complexos e a API Suggest pode levar mais tempo ou semelhante para responder do que o atraso codificado, causando uma experiência um pouco prejudicada para o usuário e carga desnecessária.
Zindex Inteiro null Define o Z-index do maior número de contêineres externos (fbs-pane, fbs-flyoutpane). Isso é útil ao usar o Freebase Suggest em caixas de diálogo para que os elementos de "Suggest" sejam exibidos no topo.

Modificar o CSS

As classes CSS padrão usadas pelo Freebase Suggest podem ser substituídas transmitindo um mapa de valores alternativos para os nomes de classes CSS usando a opção de configuração css. A tabela a seguir descreve as classes no CSS padrão.

painel O contêiner externo da lista de sugestões.

Padrão: 'fbs-pane'
list Lista de sugestões.

Padrão: 'fbs-list'
item Itens da lista "Suggest".

Padrão: 'fbs-item'.
item_name O elemento que contém o nome do item.

Padrão: 'fbs-item-name'
selecionado Item atual/selecionado. Padrão: 'fbs-selected'.
status O elemento que contém as mensagens de status. Padrão: 'fbs-status'.
item_type O elemento que contém o tipo notável de um item. Padrão: 'fbs-item-type'.
panfleto de voo O contêiner externo para voo.

Padrão: 'fbs-flyoutpane'

Exemplo:

$("#myinput").suggest({
  "css": {
    "pane": "custom-pane-class",
    "list": "custom-list-class"
  }
});

Como os eventos funcionam

O Freebase Suggest aciona os seguintes eventos dentro do contexto da entrada com que ele é inicializado.

fb-select: quando um item é selecionado na lista de sugestões. O evento é acompanhado por um objeto de dados em que data.name e data.id representam o nome e o ID do item selecionado.

$("#myinput").suggest().bind("fb-select", function(e, data) { ... });

fb-select-new: quando a opção suggest_new está ativada, esse evento é acionado quando o item sugira_new é selecionado. O evento é acompanhado pelo valor de entrada.

$("#myinput").suggest({'suggest_new': 'This is the suggest new text'}).bind("fb-select-new", function(e, val) { ... });

Perguntas frequentes e mais informações

Perguntas, relatórios de bugs e feedback são muito bem-vindos no Grupo do Google dos desenvolvedores do Freebase ou na Lista de problemas (escolha o componente "Pesquisar/Sugerir").

Acabei de criar um novo tópico, mas ele não está aparecendo no Suggest. O que está acontecendo?

O Freebase Suggest usa a API Search para fornecer resultados, que são atualizados quase em tempo real. Novos tópicos costumam aparecer em cerca de um minuto, mas podem ser mais longos se o sistema estiver sob carga alta.

Exemplos e receitas

Uso básico

$("#example1")
 .suggest()
 .bind("fb-select", function(e, data) {
   alert(data.name + ", " + data.id);
});

Experimente!

Sugerir nova

$("#example2")
 .suggest({
   "suggest_new": "Click on me if you don't see anything in the list"
 })
 .bind("fb-select", function(e, data) {
   alert(data.name + ", " + data.id);
 })
 .bind("fb-select-new", function(e, val) {
   alert("Suggest new: " + val);
 });

Experimente!

Restringir sugestões usando um filtro

Sugira filmes dirigidos por Steven Spielberg.

$("#example5")
.suggest({
   "filter": "(all type:/film/film contributor:\"Steven Spielberg #directed_by\")"
})
.bind("fb-select", function(e, data) {
   alert(data.name + ", " + data.id);
});

Experimente!

Como filtrar na caixa de texto

É possível filtrar os resultados digitando qualquer uma das restrições de filtro diretamente na caixa "Sugerir". Por exemplo, para pesquisar livros de jardinagem, tente:

gardening type:/book/book
gardening type:book

Na verdade, é possível usar quaisquer restrições do metaesquema de pesquisa para filtrar os resultados. Por exemplo, para pesquisar todas as pessoas que "contributed_to" o filme "Salvando o Ryan Ryan", tente:

contributed_to:"Saving Private Ryan" type:/people/person

Conforme indicado nas Opções de configuração, lang, scoring, spell, exact são transmitidos de forma transparente para a API Search. Também é possível substituí-los in-line. Por exemplo, se o Freebase Suggest for inicializado com lang:"en" e você também quiser pesquisar nomes franceses, tente o seguinte:

babar lang:fr,en

Para outras restrições de filtragem e pesquisa, consulte o Manual de pesquisa.