Primer

Standing on the shoulders of $.giants.

Here we’ll show you the common idiums of the upstream projects that the widgets depend upon.

External documentation:

Selectors

Several Simplicity Widgets take a selector as an option. They always wrap the passed in object with $(selector) meaning that you can pass in a DOM element, jQuery object or CSS selector.

In this example, all of the options refer to the same target element.

$('#example').selectorExample({
   domElement: document.getElementById('target'),
   jQueryObject: $('#target'),
   cssSelector: '#target' 
});

Deferred execution

We recommend setting up any JavaScript on the page to execute when the DOM is ready using $(callback). This prevents strange JavaScript errors, allows you to better optimize for page load and gives you a functional closure that prevents leaking local variables into the global scope.

$(function () {
    // My code goes in here
    $('#example').text('hello, world');
});

External documentation:

The Simplicity Widgets all follow the standard jQuery UI Widget model.

Creating widgets

You can construct them with their default options:

$('#example').exampleWidget();

Or override just the options you care about:

$('#example').exampleWidget({
    name: 'example',
    rating: 0.9
});

And you can create more than one at a time:

$('.example').exampleWidget()

Widget options and methods

Once created, you get get the value of any option:

$('#example').exampleWidget('option', 'name');

Or set it:

$('#example').exampleWidget('option', 'name', 'my new name');

You can even call methods on a widget:

$('#example').exampleWidget('bounce');

Widget events

Let’s presume that our widget is documented to fire a bouncing event.

We can bind an event handler at widget creation time:

$('#example').exampleWidget({
    bouncing: function (evt, ui) {
        console.log('widget is bouncing', evt, ui);
    }
});

Or we can explicity bind an event handler for the fully qualified event name:

$('#example').bind('examplewidgetbouncing', function (evt, ui) {
    console.log('widget is bouncing', evt, ui);
});

This highlights a subtle but important feature of jQuery UI. When binding to a widget event using an option, you use the short version of the event name. When binding to a widget event using $.bind() you use the long version of the event name. To generate the long version of the event name, you lowercase the name of the widget and then append the short event name. In our example above, the short event name is bouncing while the long event name is examplewidgetbouncing.

Technically, this is handled by the widget factory’s use of the widgetEventPrefix option. The jQuery UI slider is a great example of customizing this as it sets widgetEventPrefix to slide instead of the default slider causing the events to be named slidestart, slideslide, slidechange and slidestop instead of sliderstart, sliderslide, sliderchange and sliderstop.

Simplicity Widget events

With the exception of simplicityState and simplicityDiscoverySearch, all the Simplicity Widgets fire regular jQuery widget events that follow the prefixing rules described above. These are regular DOM events that bubble up the document.

The simplicityState and simplicityDiscoverySearch widgets use $.triggerHandler() instead to create non-prefixed non-bubbling events.

This allows us to take advantage of widget groups without having to prevent events from bubbling into the wrong group.

HTML

<body>
    <div id="searchNav">...</div>
    <div id="secondarySearch">...</div>
</body>

JavaScript

$('body')
    .simplicityState()
    .simplicityDiscoverySearch({
        url: '/my_search_controller.php'
    });

$('#secondarySearch')
    .simplicityState()
    .simplicityDiscoverySearch({
        stateElement: '#secondarySearch',
        url: '/my_search_controller.php'
    });

$('body').bind('simplicitySearchResponse', function (evt, searchResponse) {
    console.log('body search response', searchResponse);
});
$('#secondarySearch').bind('simplicitySearchResponse', function (evt, searchResponse) {
    console.log('secondary search response', searchResponse);
});

The use of $.triggerHandler means that the simplicitySearchResponse event triggered from #secondarySearch will not be picked up by the event handler that is bound to body.

CSS

jQuery UI widgets all set standard CSS classes on their attached elements, at a minimum every widget’s element has the class ui-widget.

The Simplicity Widgets additionally add a class to their element based on the name of the widget. As a rule of thumb, the widget name is lower cased and hyphens are inserted wherever a case change took place. There are a few exceptions, so check the API documentation when in doubt.

For example:

widget css class
simplicityState ui-simplicity-state
simplicityFancySelect ui-simplicity-fancy-select
simplicityMapQuestMapBoundsCoordinator ui-simplicity-mapquest-map-bounds-coordinator

Themes

jQuery UI has great support for theming and the Simplicity Widgets make use of the standard jQuery UI CSS classes to take advantage of the current theme.

You can use ThemeRoller to download one of the standard themes or create your own.

At development time, it is often useful to drop the Theme Switcher Widget onto a page so you can change the theme on the fly.