Freebase Suggest ウィジェット

  1. Freebase Suggest について
  2. サイトに Freebase Suggest を追加する
  3. 構成オプション
  4. CSS を変更する
  5. イベントの仕組み
  6. 詳細とよくある質問
  7. 例とレシピ

Freebase Suggest について

Freebase Suggest は、サイト上の検索ボックスに Freebase トピックのオートコンプリートを追加する jQuery プラグインです。ユーザーはテキストの入力を開始すると、Freebase.com の何百万ものトピック、または人、場所、動物などの種類のサブセットから、関連性のある検索結果が表示されます。トピック フライアウトは、ユーザーがフリーベース ID で一意に識別された正しいアイテムを選択するのに役立ちます。

Freebase Suggest.png

機能

  • クロスブラウザ - jQuery ベース、IE7+、FF2+、Safari 3+、Chrome でテスト（最小 jquery バージョンは 1.4.4）
  • クロスドメインJSONP のおかげでプロキシ サーバーが不要。
  • Google が gstatic.com でホスト
  • 無料（標準の無料利用規約と Google Developer API 利用規約が適用されます）。

試してみる

自由形式の提案

Freebase サジェスチョンを使用することがわかっているサイト:

Freebase Suggest を使用する理由

  • オートコンプリートを使用すると、ユーザーが入力するデータの量が少なくなります。
  • データ入力が楽しく正確です。
  • トピックのフライアウトの画像と説明により、ユーザーの認知負荷を軽減します。
  • テキスト キーワードではなく、強力な識別子を使用する。「Sting」はあいまいですが、Freebase ID の /en/sting や /en/sting_1959 は曖昧ではありません。
  • 同じエンティティに重複する名前を使用しないでください。Puff Daddy、P. ディディ・ショーン・コムスはすべて/en/sean_combsについて言及しています。

Freebase Suggest をウェブサイトに追加する

Freebase Suggest をウェブページに追加するには、ウェブサイトのソースに次のコードを追加します。API キーを取得して使用することで、Freebase Suggest の機能を拡張することもできます。

ウェブサイトに含めるコード

HTML ドキュメントの <head> に次の行を追加します。

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

次に、ドキュメント <body> で次のような入力フィールドを使用します。

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

API キーの取得

API キーを取得することで、アプリケーションで サジェスト リクエストを行うことができます。API キーがない場合、ウィジェットは限定的なテスト目的にのみ動作します。キーを取得するには、スタートガイドの手順に沿ってください。

キーを取得したら、次のようにして Freebase Suggest に渡します。

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

構成オプション

次の表に、Freebase Suggest の構成オプションを示します。

名前 タイプ Default 説明
上級 ブール値 true true の場合、Freebase Suggest は、入力のインライン name:value ペアを解析し、追加のフィルタ制約として処理します。たとえば、'bob type:artist contributed_to:"Love and Theft"' の場合、追加のフィルタ制約 '(all type:artist contributed_to:"Love and Theft")' が検索に渡されます。さらに、アドバンスが true の場合、Freebase Suggest は Freebase ID と MID を認識するため、ID や MID でエンティティを直接検索することができます。
完全一致 ブール値 false true の場合、Search API が（入力に含まれる）完全一致のみを返すように指定します。この値は透過的に Search API に渡されます。
filter String null デフォルトの検索フィルタ制約を指定して、フィルタ パラメータとして Search API に透過的に渡します。たとえば、Freebase Suggest で大学のみを検索する場合は、フィルタとして「(all type:/education/university)」を使用します。利用可能な検索フィルタの包括的なリストについては、Search API またはテキストの制約をご覧ください。
鍵 String null service_url + service_path で指定されたデフォルトの Search API の API キーを指定します。API Console から取得できます。
lang String null lang パラメータは、指定されたすべての言語で検索を実行させる言語コードのカンマ区切りリストを受け入れます。また、結果はエンティティの名前を持つリストの最初の言語でリストされ、最初の言語で表示されます。現在サポートされている言語は、en（英語）、es（スペイン語）、fr（フランス語）、de（ドイツ語）、it（イタリア語）、pt（ポルトガル語）、zh（中国語）、ja（日本語）、ko（韓国語）、ru（ロシア語）、sv（スウェーデン語）、fi（英語）、da（フィンランド）、da（フィンランド）、da（フィンランド）、da（デンマーク語）、da（英語）です。最も広範囲をカバーしているのがデフォルトの言語であり、この値は透過的に Search API に渡されます。
スコアリング String null scoring パラメータを使用すると、最終スコアの計算に使用する関連性スコア コンポーネントを制御できます。この値は透過的に Search API に渡されます。
  • entity: FREEBASE と Google の関連性スコアの両方を使用し、Google スコアがない場合のデフォルトは 1.0 です。グローバル ウィンドウはデフォルト。
  • freebase: Freebase の関連性スコアのみを使用します。
  • schema: タイプ、プロパティ、ドメインなどのスキーマ エンティティを検索する場合に使用します。スキーマ エンティティのリンク数の計算方法は異なります。
スペル String always 有効な値は、always、no_results、no_spelling です。スペルがリクエストされていて、検索でスペル修正が返された場合、Freebase Suggest は修正を候補リストに表示します。この値は検索サービスに透過的に渡されます。
フライアウト ブール値、bottom true マウスオーバーでフライアウトの説明を表示するかどうかを指定します。bottom の場合、候補リストの一番下にフライアウトを表示します。入力ボックスの上に候補リストが表示されている場合、フライアウトがリストの上に表示されます。true の場合、候補はリストの左側または右側に最善で表示されます。
返信文候補 String null 候補リストの下に表示するテキストです。選択すると、fb-select-new がトリガーされます。
css オブジェクト さまざまな Freebase Suggest 要素に使用されるデフォルトの CSS クラス名を上書きします。詳しくは、CSS を変更するをご覧ください。
css_prefix String null Suggest 要素のクラス名の前に付加する接頭辞を指定できます。たとえば、css_prefix が "foo-" の場合、コンテナ名は "foo-fbs-pane" と "foo-fbs-flyoutpane" になります。
show_id ブール値 true 'notable' 検索によって返された値を表示します。ただし、ID が表示されず、それが true の場合は、アイテムの ID が表示されます。
service_url String 値は https://www.googleapis.com/freebase/v1 です サジェスト サービスのベース URL です。
service_path String /search service_url + service_path = 候補サービスの URL。
flyout_service_url String null フライアウト サービスのベース URL。null の場合、デフォルトは service_url です。
flyout サービスパス String 値は /topic${id}?filter=suggest&limit=3&key=${key} です flyout_service_url + flyout_service_path = フライアウト サービスへの URL。'${id}' と '{key}' はそれぞれ、カーソルを合わせたアイテム ID と API キーに置き換えられます。
flyout_image_service_url String null フライアウトの画像のベース URL。null の場合、デフォルトは service_url です。
flyout_image_service_path String /image${id}?maxwidth=75&key=${key} flyout_image_service_url + flyout_image_service_path = イメージ サービスの URL'${id}' と '{key}' はそれぞれ、カーソルを合わせたアイテム ID と API キーに置き換えられます。
flyout_parent 文字列（jQuery セレクタ） null デフォルトでは、フライアウトのコンテナはドキュメント本文に追加され、絶対位置に配置されます。flyout_parent は別の親を指定しており、フライアウトは絶対位置に配置されません。
整列 String null align が設定されていない場合、候補リストは、ドキュメント内での位置に応じて、入力ボックスの「左」または「右」に合わせて配置されます。この動作をオーバーライドして明示的に配置を設定するには、align を "left" または "right" に設定します。
status 配列 [4]（文字列） ["入力を始めると候補が表示されます...", "検索中⋯⋯", "リストからアイテムを選択:", "エラーが発生しました。しばらくしてからもう一度お試しください] 提案の 4 つの段階に表示されるステータス メッセージ。[0] 入力ボックスが空で、フォーカスを取得したとき。[1] 結果を取得するとき、[2] 結果を表示するとき、[3] サジェスト サービスからエラーがあった場合デフォルトのステータス メッセージをオーバーライドするには、4 つの異なるステージに対応する別の文字列の配列を渡します。
親 文字列（jQuery セレクタ） null デフォルトでは、候補リストはドキュメントの本文に追加され、絶対位置に配置されます。parent を使用して別の親を指定すると、リストは絶対位置にはなりません。
animate ブール値 false true の場合、jQuery SlidesDown 効果を使用して、候補リストの表示がアニメーション化されます。
xhr_遅延 整数（ミリ秒） 200 結果が返されるまでの遅延を指定します。これは、mql_filters が複雑で、Suggest API がハードコードされた遅延よりも応答に時間がかかる、または同様の時間がかかる可能性があり、ユーザー エクスペリエンスが多少低下し、不要な負荷がかかる場合に役立ちます。
Z-index Integer null 最も外側のコンテナ（fbs-pane、fbs-flyoutpane）の Z-Index を設定します。これは、ダイアログ ボックスで [Freebase Suggest] を使用して、Suggest 要素が上部に表示される場合に便利です。

CSS を変更する

Freebase Suggest で使用されるデフォルトの CSS クラスは、css 構成オプションを使用して CSS クラス名の代替値のマップを渡すことでオーバーライドできます。デフォルト CSS のクラスを次の表に示します。

ペイン 候補リストの外部コンテナ。

デフォルト: 'fbs-pane'
list 候補リスト。

デフォルト: 'fbs-list'
アイテム 候補リストのアイテム。

デフォルト: 'fbs-item'.
item_name アイテムの名前を含む要素。

デフォルト: 'fbs-item-name'
選択済み 現在ハイライト表示されている、または選択されている項目。デフォルト: 'fbs-selected'.
status ステータス メッセージを含む要素。デフォルト: 'fbs-status'.
item_type [商品アイテム タイプ] アイテムの注目すべきタイプを含む要素。デフォルト: 'fbs-item-type'.
flyoutpane フライアウトの外部コンテナ。

デフォルト: 'fbs-flyoutpane'

例:

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

イベントの仕組み

Freebase Suggest は、初期化された入力のコンテキスト内で次のイベントをトリガーします。

fb-select - 候補リストから項目を選択した場合。このイベントには、data.name と data.id が、選択されたアイテムの名前と ID を表すデータ オブジェクトが伴います。

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

fb-select-new - suggest_new オプションが有効になっている場合、suggest_new 項目が選択されたときにこのイベントはトリガーされます。イベントには入力値が伴います。

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

よくある質問と詳細情報

質問、バグレポート、フィードバックは、Freebase Developers Google グループまたは問題リスト（[検索 / サジェスト] コンポーネント）からいつでも行っていただけます。

新しいトピックを作成しても、提案に表示されないとどうなりますか。何でしょうか？

Freebase Suggest は、Search API を使用して結果を提供します。この内容はほぼリアルタイムで更新されます。新しいトピックは通常 1 分以内に表示されますが、システムの負荷が高い場合はさらに時間がかかることがあります。

例とレシピ

基本的な使用方法

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

試してみる

新しく提案

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

試してみる

フィルタを使用した候補の制限

スティーヴン スピルバーグ監督による映画の提案を行います。

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

試してみる

テキスト ボックスからのフィルタリング

いずれかのフィルタ制約を [サジェスト] ボックスに直接入力することで、結果をフィルタできます。たとえば、ガーデニングに関する書籍を検索するには、次のようにします。

gardening type:/book/book
gardening type:book

実際には、任意の検索メタスキーマの制約を使用して結果をフィルタできます。たとえば、「contributed_to『Saving Private Ryan』」を引用したすべての人物を検索するには、次のように検索します。

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

設定オプションで説明しているように、lang、scoring、spell、exact は透過的に Search API に渡されます。インラインで上書きすることもできます。たとえば、Freebase Suggest が lang:"en" で初期化され、フランス語の名前も検索する場合は、次のようにします。

babar lang:fr,en

その他のフィルタリングや検索の制約については、検索クックブックをご覧ください。