Freebase Suggest

Freebase.com has an open API that can be used to access and update structured data.

Freebase Suggest is a jQuery plugin that can be used to reconcile user input against millions of topics stored in Freebase.

Development	Production
suggest.css 12K	suggest.min.css 8.0K
suggest.js 52K	suggest.min.js 28K


<link type="text/css" rel="stylesheet" href="http://freebaselibs.com/static/suggest/0.9.4/suggest.css" />
<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js"></script>
<script type="text/javascript" src="http://freebaselibs.com/static/suggest/0.9.4/suggest.js"></script>

<input id="myinput"/>

<script type="text/javascript">
  $(function() {
    $("#myinput").suggest().bind("fb-select", function(e,data) { alert(data.name + ", " + data.id);} );
  });
</script>

Try it out here:

suggest( options )

Options

type Array, String (JSON) Default: null

Searches may be made more specific by matching against the type(s) of topics by passing one or more type value(s). Type value may be ids or guids of types. More than one type can be passed in by using the type parameter as an array (i.e., ["/type/id1", "/type/id2"]).

type_strict String Default: "any"

This parameter makes it possible to control how specific the type matches must be. A value of
"should" gives preference to matches by boosting their query score but doesn't require any,
"any" requests that at least one type value matches and
"all" requires that all types match.

mql_filter Object, String (JSON) Default: null

This parameter may be used to specify a topic-rooted MQL query to use against full text index matches. For example: Looking for music albums by a specific artist:


var options = {
  "type_strict": "/music/album",
  "mql_filter": [{"artist":[{"id":"/en/carly_simon"}]}]
}

When using mql_filter, one should be careful to front-load as many as possible of the overall query constraints to the full text queries. For example, it is much faster to constrain a query on type via the type parameter than a type clause in a MQL filter.

Note that the mql_filter query cannot have a constrained id clause since it receives an extra guid|= clause containing the guids of matches to pass through the filter. Having these clauses together is not supported by MQL.

flyout Boolean, "bottom" Default: true

Whether or not to show a flyout description on hover. If "bottom", show flyout at the bottom of the suggest list. If the suggest list is displayed above the input box, the flyout will be displayed on top of the list. If TRUE, suggest will do it's best to show the flyout either on the left or right side of the list.

required Boolean, "always" Default: false

This can be used to help with input validation. Values can be true, false or 'always'. If true, an 'fb-required' event will be triggered if nothing is selected and the input value is NOT empty. If 'always', 'fb-required' will be triggered if no selection is made even if the input value is empty.

suggest_new String Default: null

This can be any text to be shown below the suggestion list. On selection, an 'fb-select-new' will be triggered.

css Object

You can overwrite default css class names used for the various suggest elements

pane	The outer container of the suggest list.	Default: 'fbs-pane'
list	The suggest list.	Default: 'fbs-list'
item	The suggest list items.	Default: 'fbs-item'.
item_name	The element containing the the name of the item.	Default: 'fbs-item-name'
selected	The current highlighted/selected item.	Default: 'fbs-selected'.
flyoutpane	The flyout outer container.	Default: 'fbs-flyoutpane'.

css_prefix String Default: null

You can specify a prefix to be pre-pended to the class names of the the suggest elements. For example if css_prefix is "foo-" the container names will be "foo-fbs-pane" and "foo-fbs-flyoutpane".

soft Boolean Default: false

Carry over from previous freebaseSuggest to enable search box behavior without forcing a selection from the suggest list. If true, DO NOT auto-select first item on ENTER key. Otherwise, select first item.

Events

Freebase Suggest triggers the following events within the context of the input that it is initialized with.

fb-select - When an item is selected from the suggest list. The event is accompanied by a data object where data.name and data.id represent the name and id of the item that was selected.


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

fb-select-new - When the suggest_new option is enabled, this event is triggered when the suggest_new item is selected. The event is accompanied by the input value.


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

fb-required - When required is set to true or 'always', this event will be triggered when an item is NOT selected from the suggest list and the input loses focus.


$("#myinput").suggest({'required': 'always'}).bind("fb-required", function(e) { ... });

Examples

Example 1. Basic usage


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

Try it out here:

Example 2. Suggest new


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

Try it out here:

Example 3. Required


$("#example3")
  .suggest({
    "required": "always"
  })
  .bind("fb-select",
            function(e, data) {
              alert(data.name + ", " + data.id);
            })
  .bind("fb-required",
            function(e) {
              alert("This is required");
            });

Try it out here:

Example 4. Constraining suggestions by type and type_strict

Constrain suggestions by countries or US States.


$("#example4")
  .suggest({
    "type": ["/location/country", "/location/us_state"],
    "type_strict": "any"
  })
  .bind("fb-select",
            function(e, data) {
              alert(data.name + ", " + data.id);
            });

Try it out here:

Example 5. Constraining suggestions by mql_filter

Suggest films directed by Steven Spielberg


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

Try it out here:

Example 6. Search box behavior

Add suggest to your search box.


$("#example6")
  .suggest({
    "type": "/film/film",
    "soft": true
  })
  .bind("fb-select",
            function(e, data) {
              alert(data.name + ", " + data.id);
            });

Try it out here:

Plugins

The Freebase Suggest core library is extensible to create your own custom suggestions. The core library can be thought as a drop down list that appears below a text input and handles keyboard and mouse interactions with the list like up and down arrow keys and selecting. Here are some plugins that are an extension of the core Freebase Suggest library.