Freebase Search 小工具

  1. 關於 Freebase 建議
  2. 為網站新增 Freebase 建議
  3. 設定選項
  4. 修改 CSS
  5. 事件的運作方式
  6. 更多資訊與常見問題
  7. 例子和食譜

關於 Freebase Suggestion

Freebase suggests 是 jQuery 外掛程式，可將您網站上的 Basebase 主題自動完成功能新增至網站的搜尋框。使用者開始輸入文字後，小工具就會從 Freebase.com 的數百萬個主題或任何相符類型 (例如「人物」、「地點」或「動物」) 建議內容。主題飛越功能可協助使用者選取由 Freebase ID 明確識別的正確項目。

Freebase Suggested.png

功能與特色

  • 跨瀏覽器：根據 jQuery，在 IE7+、FF2+、Safari 3+ 和 Chrome 上進行測試 (最低 jquery 為 1.4.4 版)
  • 跨網域。JSONP，因此不需要使用 Proxy 伺服器。
  • 由 Google 透過 gstatic.com 代管
  • 免費！(適用標準 Freebase 條款和 Google Developer API 條款)。

馬上試試！

野生自由的建議

已知使用 Freebase 建議的網站：

使用 Freebase Suggestion 的理由

  • 有了自動完成功能，使用者就能輸入更少的資料。
  • 資料輸入功能有趣且準確！
  • 借助主題題材的圖片和說明，減少使用者的認知。
  • 使用明確的 ID，而非文字關鍵字。「Sting」名稱並非模稜兩可，但 Freebase ID /en/sting 和 /en/sting_1959 則不是。
  • 並避免使用同一個實體的名稱。Puff Daddy, P. 迪恩，席恩梳是指「/en/sean_combs」，

在您的網站上新增 Freebase 建議

若要在網頁中加入 Freebase 建議，請在網站原始碼中加入下列程式碼。您也可以取得並使用 API 金鑰來擴充 Freebase Suggestion 的功能。

要加入網站的代碼

請在 HTML 文件的 <head> 中加入以下內容：

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

接著，使用以下文件中的輸入欄位 <body>：

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

取得 API 金鑰

取得 API 金鑰可讓應用程式提出 Suggestion 要求。如果沒有 API 金鑰，小工具將可在有限的測試目的下運作。如要取得金鑰，請按照「入門指南」頁面中的說明操作。

取得金鑰後，請將金鑰傳送給 Freebase 建議，如下所示：

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

設定選項

下表說明 Freebase Suggestion 的設定選項。

名稱 類型 預設 說明
進階 布林值 true 如果為 true，Freebase 建議會剖析並處理輸入內容中的內嵌 name:value 組合，做為其他篩選器限制。例如，如果是 'bob type:artist contributed_to:"Love and Theft"'，系統會將額外的篩選器限制 '(all type:artist contributed_to:"Love and Theft")' 傳遞至搜尋。此外，進階屬性為 true 時，Freebase Suggested 會辨識 Freebase ID 和 MID，以便可以直接透過 ID 或 MID 搜尋實體。
完全比對 布林值 否 如果為 true，則表示 Search API 只會傳回完全比對 (包含輸入的內容)。這個值會以公開透明的方式傳送至 Search API。
過濾器 字串 空值 指定預設的搜尋篩選器限制，以透明化的方式傳遞給 Search API 做為篩選器參數。舉例來說，如要限制 Freebase Recommendations 只搜尋大專院校和/或大學，請使用「(all type:/education/university)」做為篩選器。如需可用搜尋篩選器的完整清單，請參閱 Search API 或文字限制。
金鑰 字串 空值 為 service_url + service_path 指定的預設 Search API 提供 API 金鑰。您可以在 API 控制台取得這個 API。
lang 字串 空值 lang 參數接受以逗號分隔的語言代碼清單，讓搜尋結果以所有指定語言搜尋，且搜尋結果會以第一個語言列出，並以清單中的第一個語言列出實體名稱。目前支援 18 種語言，包括：en (英文)、es (西班牙文)、fr (french)、de (german)、it (italian)、pt (葡萄牙文)、zh (簡體)、ja (japanese)、ko (korean)、ru (russian)、da (荷蘭文)、da (荷蘭文)、da (荷蘭文)、da (荷蘭文)、da (荷蘭文)、da (德文)目前英文涵蓋率最高的國家/地區為預設語言。這個值會以公開透明的方式傳送至 Search API。
計分 字串 空值 scoring 參數可讓您控制使用哪些關聯性分數元件來計算最終分數。這個值會以透明公開的方式傳送至 Search API。
  • entity：使用 FREEBASE 和 Google 的關聯性分數，並將 Google 分數預設為 1.0。此為預設值。
  • freebase：僅使用 Freebase 關聯性分數。
  • schema：用於尋找類型、屬性或網域等結構定義實體。結構定義實體的連結數量會採不同的方式計算。
拼字檢查 字串 always 有效值為 always、no_results、no_spelling。如果系統要求拼字，但搜尋字詞傳回拼字修正，Freebase Suggestion 會在 [建議] 清單中顯示更正結果。這個值會以公開透明的方式傳遞給搜尋服務。
飛行 布林值，bottom true 決定是否要在滑鼠遊標懸停時顯示航班說明。如為 bottom，請在「建議」清單底部顯示檔期。如果輸入方塊上方顯示「建議」清單，則飛出清單會顯示在清單頂端。如果為 true，則建議功能會盡可能在清單的左側或右側顯示檔期。
建議新功能 字串 空值 建議清單下方顯示的文字。選取時即會觸發 fb-select-new。
CSS 物件 覆寫各種 Freebase Suggestion 元素的預設 CSS 類別名稱。詳情請參閱修改 CSS。
CSS 前置字元 字串 空值 您可以指定在 Google 建議元素的類別名稱前面加上前置前置字串。舉例來說，如果 css_prefix 是「foo-」，容器名稱就會是「foo-fbs-pane」和「foo-fbs-flyoutpane」。
show_id 布林值 true 顯示搜尋方法傳回 'notable' 的值。然而，如果找不到 ID，則表示該項目為 true，會顯示商品的 ID。
service_url 字串 值為 https://www.googleapis.com/freebase/v1 這是「建議」服務的基本網址。
service_path 字串 /search service_url + service_path = 建議服務的網址。
flyout_service_url 字串 空值 飛行服務的基本網址。如果為空值，則預設為 service_url。
flyout_service_path 字串 值為 /search?filter=(all mid:${id})&output=(notable:/client/summary description type)&key=${key} flyout_service_url + flyout_service_path = 飛出服務的網址。'${id}' & '{key}' 分別被懸停的項目 ID 和 API 金鑰取代。
flyout_image_service_url 字串 空值 飛出圖片的基準網址。如果為空值，則預設為 service_url。
flyout_image_service_path 字串 值為 /image${id}?maxwidth=75&key=${key}&errorid=/freebase/no_image_png flyout_image_service_url + flyout_image_service_path = 圖片服務的網址。'${id}' & '{key}' 分別會變成懸停的項目 ID 和 API 金鑰。
flyout_parent 字串 (jQuery 選取器) 空值 根據預設，飛出式容器會附加至文件內文，並位於絕對位置。flyout_parent 會指定不同的父項，並避免絕對位置。
對齊 字串 空值 如未設定 align，建議清單就會與輸入方塊的「左」或「右」對齊。視盒在文件中的位置而定。如要覆寫此行為並明確設定對齊方式，請將 align 設為「left」或「right」。
狀態 陣列 [4](字串) ["開始輸入即可取得建議...", "Searching...""從清單中選取項目：", "抱歉，發生錯誤。請稍後再試」 建議的 4 個不同階段會顯示狀態訊息；[0] 輸入方塊為空白且聚焦時擷取結果時，[1]；顯示結果時，[2]；如果「建議」服務發生錯誤，[3]。如要傳遞這些預設狀態訊息，您可以傳入與 4 個不同階段相對應的不同字串陣列。
父項 字串 (jQuery 選取器) 空值 根據預設，「建議」清單會附加到文件內文，並絕對位置。使用 parent 指定不同的上層，且清單不會絕對定位。
動畫 布林值 否 如果設為 True，系統便會使用 jQuery slidedown 效果為「建議」清單顯示動畫。
Xhr_delay 整數 (毫秒) 200 指定傳回結果前的延遲時間。如果 mql_filters 較為複雜，且 Suggested API 的回答時間可能會比硬式編碼延遲來得長，甚至需要更多時間或相似時間才能完成回應，因此這可能會破壞使用者體驗，造成非必要的使用者體驗，並造成不必要的負載。
ZIndex 整數 空值 設定最外層容器 (fbs-pane、fbs-flyoutpane) 的 Z-index。在對話方塊中使用 Freebase 建議時，這會有助於讓建議元素顯示在頂端。

修改 CSS

您可以使用 css 設定選項，傳入 CSS 類別名稱的替代值對應來覆寫 Freebase Suggested 使用的預設 CSS 類別。下表說明預設 CSS 中的類別。

窗格 「建議」清單的外部容器。

預設：'fbs-pane'
list 建議清單。

預設：'fbs-list'
商品 建議清單項目。

預設：'fbs-item'。
item_name 包含商品名稱的元素。

預設：'fbs-item-name'
已選取 目前的醒目顯示/選取項目。預設：'fbs-selected'。
狀態 包含狀態訊息的元素。預設：'fbs-status'。
item_type [項目類型] 元素包括項目的著名類型。預設：'fbs-item-type'。
飛輪 飛出式容器。

預設：'fbs-flyoutpane'

例如：

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

事件的運作方式

Freebase Suggested 會在所初始化的輸入情境中觸發下列事件。

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 suggests 使用 Search API 提供結果，且將以近乎即時的速度更新。新主題通常會在一分鐘內顯示完畢，但如果系統處於高負載狀態，則需要較長的時間。

範例與食譜

基本用法

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

事實上，您可以使用任何 Search Metaschema 限制來篩選結果。舉例來說，如要搜尋「contributed_to」這個私人影片，請搜尋「淡水瑞恩」。

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

如「設定選項」中所述，lang、scoring、spell、exact 會明確傳遞至 Search API。如有需要，你也可以以內嵌方式覆寫。舉例來說，如果 Freebase Suggested 已使用 lang:"en" 初始化，但您也想要搜尋法文名稱，請嘗試：

babar lang:fr,en

如需其他篩選和搜尋限制，請參閱搜尋教戰手冊。