Userguide

Learning how to use the widgets.

The Simplicity Widgets are designed to be extensible, and to get out of the way when you need them to.

They follow simple architectural patterns for communicating with a search server, coordinating widget state on the page, and displaying results.

jQuery and jQuery UI are required to use the widgets.

There are three high-level steps to use the widgets on a page:

  1. install the widgets on the page with link and script tags
  2. add HTML elements for the search and result areas
  3. add a few lines of JavaScript to configure the widgets

You need to add link and script tags for the JavaScript and CSS resources for the widgets.

Add the CSS references to the head of the page.

<link href="http://ajax.googleapis.com/ajax/libs/jqueryui/1.10.0/themes/base/jquery-ui.css" rel="stylesheet">
<link href="http://cdn.transparensee.com/simplicity/4.0/simplicity.min.css" rel="stylesheet">

Note: You can use any of the available jQuery UI themes.

Add these external JavaScript references to the end of the body of the page.

<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js"></script>
<script src="http://ajax.googleapis.com/ajax/libs/jqueryui/1.10.0/jquery-ui.min.js"></script>
<script src="http://cdn.transparensee.com/simplicity/4.0/simplicity.min.js"></script>

Some widgets have extra dependencies, you’ll need to add script tags for them.

jQuery BBQ plugin
Used by $.simplicityDiscoverySearch('mergeQueryParams') and $.simplicityHistory.
<script src="http://cdn.transparensee.com/lib/jquery-plugin/bbq/1.2.1/jquery.ba-bbq.min.js"></script>

Some browsers need extra JavaScript support to function well, you’ll need to add script tags for the following libraries for most compatibility.

JSON2
Gracefully adds support for JSON.parse and JSON.stringify to browsers that do not have native JSON support.
<!--[if lt IE 9]>
  <script src="http://cdn.transparensee.com/lib/json2/2010-11-17/json2.min.js"></script>
<![endif]-->
jQuery bgiframe plugin
Recommended for IE6 compatibility when using $.simplicityFlyout.
<!--[if IE]>
  <script src="http://cdn.transparensee.com/lib/jquery-plugin/bgiframe/2.1.2/jquery.bgiframe.min.js"></script>
<![endif]-->
html5shim
Adds HTML5 element support to IE. This script tag must go in the head section of your page.
<!--[if lt IE 9]>
  <script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
xdr.js
Adds support for CORS requests to older versions of IE.
<!--[if IE]>
  <script src="http://cdn.transparensee.com/lib/xdr/984c41/xdr.min.js"></script>
<![endif]-->
jQuery Touch Punch plugin
Adds tablet/phone touch event support to jQuery UI.
<script src="http://cdn.transparensee.com/lib/jquery-plugin/touchpunch/0.2.2/jquery.ui.touch-punch.min.js"></script>

You will add javascript code after the above tags to instantiate and configure the widgets that you want to use. We’ll get to that in a bit.

Add the search navigation form to the left side of the page.

<form id="searchForm" onsubmit="return false;">
  <fieldset>
    <div class="input-append">
      <input id="q" name="q" type="text" class="span2" placeholder="Keyword search">
      <button class="btn" type="button">Go!</button>
    </div>
    <label>Genre
      <select id="genre" name="genre" multiple="multiple">
        <option value="">Select</option>
      </select>
    </label>
    <div id="genreFancy"></div>
    <hr />
    <button id="resetSearch" type="button" name="resetSearch" class="btn">Reset Search</button>
  </fieldset>
</form>

Add the results and pagination divs to the content area of the page.

<div id="paginationTop"></div>
<div id="searchResults"></div>
<div id="paginationBottom"></div>

We configure the widgets in a script tag below the script tags that loaded simplicity.js and its dependencies.

Only one widget group is needed, so we create a simplicityState widget on the body element.

$('body').simplicityState();

Then we configure request widgets on the inputs in the search navigation form.

$('#q,#genre').simplicityInputs();

$('#genre').simplicityFacetedSelect().hide();
$('#genreFancy').simplicityFancySelect({
    select: '#genre'
});

$('#resetSearch').click(function () {
  $('body').simplicityState('reset');
});

The response widgets are created for the divs in the content area to display the search results and pagination links.

$('#searchResults').simplicitySearchResults({
  resultsCallback: window.searchResults
});

$('#paginationTop,#paginationBottom').simplicityPagination();

Finally, we perform the page level setup of the simplicityDiscoverySearch widget.

$('body')
  .simplicityPageSnapBack()
  .simplicityDiscoverySearch({
    url: 'http://freebase-movies.discoverysearchengine.com:8090/ws/query',
    backend: 'engine',
    controllerCallback: window.searchController
  })
  .simplicityDiscoverySearch('search');

For the best user experience, we recommend placing any slow-loading scripts such map vendor scripts below all the Simplicity Widget JavaScript so that the widgets can be fully functional and displayed before the slow loading scripts are executed.

Note the example snippets above refer to two external JavaScript functions window.searchController and window.searchResults which aren’t included above.

We’ve demonstrated how to build a basic search page that uses JavaScript based search controller and results rendering and connects directly to the Discovery Search Engine using Ajax requests with CORS.

You can try out the completed page or view/download the source files from the github repository.