Widget de suggestion Freebase

  1. À propos de la suggestion Freebase
  2. Ajouter la suggestion Freebase à votre site
  3. Options de configuration
  4. Modifier le CSS
  5. Fonctionnement des événements
  6. Plus d'infos et questions fréquentes
  7. Exemples et recettes

À propos de la suggestion Freebase

Freebase Suggest est un plug-in jQuery qui ajoute la saisie semi-automatique de sujets à des champs de recherche sur votre site. Les utilisateurs commencent à saisir du texte, et le widget suggère des correspondances pertinentes parmi les millions de sujets sur Freebase.com ou n'importe quel sous-ensemble de types comme "Personnes", "Zones" ou "Animaux". Les thèmes permettent à l'utilisateur de sélectionner l'élément identifié de manière unique par un ID Freebase.

Freebase Suggest.png

Fonctionnalités

Essayez !

Suggestions de base libres

Sites connus pour utiliser la suggestion Freebase:

Pourquoi utiliser Freebase Suggest ?

  • La saisie semi-automatique permet de saisir moins de données.
  • La saisie des données est amusante et précise.
  • Réduisez la charge cognitive de vos utilisateurs grâce aux images et aux descriptions des sujets.
  • Utilisez des identifiants forts plutôt que des mots clés textuels. Le nom "Sting" est ambigu, mais pas les ID Freebase /en/sting et /en/sting_1959.
  • Évitez les noms en double pour une même entité. Puff Daddy, P. Diddy, Sean Pebs font tous référence à /en/sean_combs.

Ajouter la suggestion Freebase à votre site Web

Pour ajouter la suggestion Freebase à votre page Web, incluez le code suivant dans le code source de votre site Web. Vous pouvez également obtenir et utiliser une clé API pour étendre les fonctionnalités de Freebase Suggest.

Code à inclure dans votre site Web

Incluez les éléments suivants dans le fichier <head> de votre document HTML:

<link type="text/css" rel="stylesheet" href="https://www.gstatic.com/freebase/suggest/4_1/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_1/suggest.min.js"></script>
<script type="text/javascript">
$(function() {
  $("#myinput").suggest({filter:'(all type:/film/director)'});
});
</script>

Ensuite, utilisez dans votre document un champ de saisie <body> semblable à celui-ci:

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

Obtenir une clé API

L'obtention d'une clé API permet à votre application d'envoyer des requêtes Suggestion. Sans clé API, le widget fonctionnera à des fins de test limitées. Pour obtenir une clé, suivez les instructions de la page Premiers pas.

Une fois que vous avez obtenu une clé, transmettez-la à Freebase Suggest comme suit:

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

Options de configuration

Le tableau suivant décrit les options de configuration pour Freebase Suggest.

Nom Type Par défaut Description
avancé Booléen true Si la valeur est "true", la suggestion Freebase analyse et gère les paires name:value intégrées dans l'entrée en tant que contraintes de filtre supplémentaires. Par exemple, pour 'bob type:artist contributed_to:"Love and Theft"', une contrainte de filtre supplémentaire, '(all type:artist contributed_to:"Love and Theft")' est transmise à la recherche. De plus, lorsque la valeur "true" est définie sur "true", la suggestion Freebase reconnaît les ID et MID Freebase, afin que l'utilisateur puisse rechercher directement une entité à l'aide de son ID ou de son MID.
mot clé exact Booléen false Si la valeur est "true", l'API Search Search ne renvoie que des correspondances exactes (de ce qui figure dans l'entrée). Cette valeur est transmise de manière transparente à l'API Search.
filter String nul Spécifiez une ou plusieurs contraintes de filtre de recherche par défaut qui seront transmises de manière transparente à l'API Search en tant que paramètre(s) de filtre. Par exemple, pour limiter la recherche Freebase à la recherche sur les universités et/ou les universités, utilisez le filtre (all type:/education/university). Pour obtenir la liste complète des filtres de recherche disponibles, consultez API Search ou Contraintes de texte.
clé String nul Fournissez une clé API pour l'API Search par défaut spécifiée par service_url + service_path. Vous pouvez en obtenir un à partir de la console des API.
lang String nul Le paramètre lang accepte une liste de codes de langues séparés par une virgule, ce qui permet d'effectuer la recherche dans toutes les langues spécifiées. Les résultats sont alors classés dans la première langue de la liste, puis affichés dans la première langue de la liste, dont le nom correspond à l'entité. 18 langues sont actuellement acceptées: en (anglais), es (espagnol), fr (français), de (allemand), it (italien), pt (portugais), zh (chinois), ja (japonais), ko (coréen), ru (russe), sv (suédois), fi (finnois), da (danois), né en néerlandais (néerlandais), néerlandais, tchèque L'anglais est de loin le champ d'action le plus étendu et est la langue par défaut. Cette valeur est transmise de manière transparente à l'API Search.
par lot String nul Le paramètre scoring permet de contrôler les composants du score de pertinence utilisés pour calculer le score final. Cette valeur est transmise de manière transparente à l'API Search.
  • entity: utilisez à la fois FREEBASE et les scores de pertinence Google, qui affichent par défaut la note Google 1.0. Il s'agit de la valeur par défaut.
  • freebase: n'utilisez que le score de pertinence Freebase.
  • schema: à utiliser pour rechercher des entités de schéma telles que des types, des propriétés ou des domaines. Le nombre de liens des entités de schéma est calculé différemment.
sortilège String always Les valeurs possibles sont always, no_results et no_spelling. Si une correction orthographique est demandée et que la recherche renvoie une correction orthographique, Freebase Suggest affiche la correction dans la liste de suggestions. Cette valeur est transmise de manière transparente au service de recherche.
faire sortir Booléen, bottom true Détermine si une description du survol doit s'afficher au passage de la souris. Si la valeur est bottom, l'élément de développement s'affiche en bas de la liste de suggestions. Si la liste de suggestions s'affiche au-dessus de la zone de saisie, l'élément de menu déroulant s'affiche en haut de la liste. Si la valeur est "true", Suggest fait en sorte d'afficher le menu déroulant à gauche ou à droite de la liste.
suggérer_nouveau String nul Texte à afficher sous la liste des suggestions. Lors de la sélection, un fb-select-new est déclenché.
css Objet Remplacer les noms de classe CSS par défaut utilisés pour les différents éléments de la suggestion Freebase Pour en savoir plus, consultez Modifier le code CSS.
CSS_préfixe String nul Vous pouvez indiquer un préfixe à ajouter aux noms de classe des éléments Suggest. Par exemple, si css_prefix est "foo-", les noms de conteneurs seront "foo-fbs-pane" et "foo-fbs-flyoutpane".
show_id Booléen true Affiche la valeur"notable"renvoyée par la recherche. Toutefois, si elle n'est pas disponible et que la valeur est définie sur "true", l'ID de l'article est affiché.
service_url String La valeur est https://www.googleapis.com/freebase/v1 Il s'agit de l'URL de base du service Suggest.
service_path [chemin_service] String /search service_url + service_path = URL du service de suggestion.
Flyout_service_url [URL_de_service_flyout] String nul URL de base du service flyout. Si la valeur est nulle, la valeur par défaut est service_url.
flyout_service_path (chemin d'accès pour le départ) String La valeur est /topic${id}?filter=suggest&limit=3&key=${key} flyout_service_url + flyout_service_path = URL du service de lancement. "${id}" et "{key}" sont respectivement remplacés par l'ID d'élément pointé et la clé API.
flyout_image_service_url String nul URL de base de l'image dans le menu déroulant. Si la valeur est nulle, la valeur par défaut est service_url.
Flyout_image_service_path (chemin d'accès pour l'image de départ) String /image${id}?maxwidth=75&key=${key} flyout_image_service_url + flyout_image_service_path = URL vers le service d'images. "${id}"et"{key}"seront respectivement remplacés par l'ID d'élément pointé et la clé API.
parent_volant Chaîne (sélecteur jQuery) nul Par défaut, le conteneur est ajouté au corps du document et positionné de manière absolue. flyout_parent spécifie un parent différent et l'élément de survol ne sera pas placé dans la position exacte.
align String nul Si align n'est pas défini, la liste de suggestions est alignée à gauche ou à droite de la zone de saisie en fonction de sa position dans le document. Pour ignorer ce comportement et définir son alignement explicitement, définissez align sur "left ou "right".
état Tableau[4](Chaîne) ["Commencez à saisir du texte pour obtenir des suggestions...", "Recherche en cours...", "Sélectionnez un élément de la liste:", "Désolé, un problème est survenu. Veuillez réessayer plus tard.] Messages d'état qui s'affichent lors des quatre étapes différentes de la fonctionnalité de suggestion [0]. Lorsque le champ de saisie est vide et qu'il est sélectionné, [1] lors de la récupération des résultats, [2] lors de l'affichage des résultats, [3] lorsqu'une erreur provient du service de suggestion. Vous pouvez remplacer ces messages d'état par défaut en transmettant un tableau de chaînes différent correspondant aux quatre étapes différentes.
parent Chaîne (sélecteur jQuery) nul Par défaut, la liste de suggestions est ajoutée au corps du document et positionnée de manière absolue. Utilisez parent pour spécifier un parent différent, et la liste ne sera pas positionnée de manière absolue.
animate Booléen false Si la valeur est "true", l'affichage de la liste de suggestions est animé avec l'effet "jQuery slidesDown".
xh_delay Entier (ms) 200 Spécifie un délai avant de renvoyer les résultats. Cette approche est utile dans les cas où mql_filters est complexe et que la réponse de l'API Suggest peut prendre plus ou moins de temps que le délai codé en dur, ce qui nuit à l'expérience utilisateur et entraîne une charge inutile.
z-index Integer nul Définit le z-index de la plupart des conteneurs externes (fbs-pane, fbs-flyoutpane). Il est utile lorsque vous utilisez la fonctionnalité de suggestion Freebase dans des boîtes de dialogue afin que les éléments de la suggestion s'affichent en haut.

Modifier le CSS

Les classes CSS par défaut utilisées par Freebase Suggest peuvent être remplacées en transmettant une carte de valeurs alternatives pour les noms de classes CSS à l'aide de l'option de configuration css. Le tableau suivant décrit les classes du CSS par défaut.

volet Conteneur externe de la liste de suggestions.

Par défaut: 'fbs-pane'
list Liste de suggestions.

Par défaut: 'fbs-list'
article Éléments de la liste de suggestions.

Valeur par défaut : fbs-item.
item_name Élément contenant le nom de l'article.

Par défaut: 'fbs-item-name'
sélectionné Élément sélectionné/sélectionné. Valeur par défaut : fbs-selected.
état Élément contenant les messages d'état. Valeur par défaut : fbs-status.
item_type [type_d'article] Élément contenant le type notable d'un élément. Valeur par défaut : fbs-item-type.
volet panaché Conteneur externe à développer.

Par défaut: 'fbs-flyoutpane'

Exemple :

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

Fonctionnement des événements

Freebase Suggest déclenche les événements suivants dans le contexte de l'entrée avec laquelle il est initialisé.

fb-select : lorsqu'un élément est sélectionné dans la liste de suggestions. L'événement est accompagné d'un objet de données où data.name et data.id représentent le nom et l'ID de l'élément sélectionné.

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

fb-select-new : lorsque l'option suggest_new est activée, cet événement se déclenche lorsque l'élément suggest_new est sélectionné. L'événement est accompagné de la valeur saisie.

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

Questions fréquentes et autres informations

Les questions, les rapports de bugs et les commentaires sont les bienvenus dans le groupe Google destiné aux développeurs Freebase ou dans la liste des problèmes (choisissez le composant "Rechercher/Suggérer".).

Je viens de créer un sujet, mais il ne s'affiche pas dans Suggérer. Pourquoi ?

Freebase Suggest utilise l'API Search pour fournir ses résultats, qui est mis à jour quasiment en temps réel. Les nouveaux sujets apparaissent généralement dans la minute, mais le délai peut être plus long si le système est surchargé.

Exemples et recettes

Utilisation de base

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

Essayez !

Suggérer une nouvelle

$("#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);
 });

Essayez !

Limiter les suggestions à l'aide d'un filtre

Suggérez des films réalisés par 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);
});

Essayez !

Filtrer à partir de la zone de texte

Vous pouvez filtrer les résultats en saisissant l'une des contraintes de filtre directement dans la zone de suggestion. Par exemple, pour rechercher des livres sur le jardinage:

gardening type:/book/book
gardening type:book

Vous pouvez donc utiliser n'importe quelle contrainte de métaschéma de recherche pour filtrer les résultats. Par exemple, pour rechercher toutes les personnes ayant contributed_toeffectué le film"Sauver le privé Ryan", essayez:

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

Comme indiqué dans Options de configuration, lang, scoring, spell et exact sont transmis de manière transparente à l'API Search. Vous pouvez également les écraser. Par exemple, si la suggestion Freebase est initialisée avec lang:"en" et que vous souhaitez également rechercher des noms français, procédez comme suit:

babar lang:fr,en

Pour en savoir plus sur le filtrage et les contraintes de recherche, consultez le Cookbook sur la recherche.