jQuery UI 1.8 Upgrade Guide

link Overview

This guide will assist in upgrading from jQuery UI 1.7.x to jQuery UI 1.8.x. All changes are listed below, organized by plugin, along with how to upgrade your code to work with jQuery UI 1.8.

link Accordion

  • Removed alwaysOpen option in favor of collapsible option (#4030)

link Datepicker

  • The yearRange option now allows different formats for each half of the range, e.g. "1950:-18". This means that relative years must always use a "+" or "-" to indicate their status. In particular, to reference the current year you must use "+0", e.g., "-10:+0".
  • To suppress show/hide animations set showAnim to blank or false instead of setting duration to 0.
  • Manually entered dates now update the alternate field.
  • Default tab processing is no longer suppressed.

link Dialog

  • beforeclose option changed to beforeClose - beforeclose is now deprecated and will be removed in the next release.
  • Dialog buttons now use the new Button widget, it has to be included to get properly themed dialog buttons. If it is missing, plain unthemed buttons will be used, which will still work, just not look as nice.

link Draggable

  • Removed ui.absolutePosition in callbacks (#3990)
  • Changed stack option to accept a selector instead of a hash (#4365)

link Droppable

  • Removed ui.absolutePosition in callbacks (#3989)

link Widget

link Widget prototype changes

  • $.widget.prototype to $.Widget.prototype so it can fully use prototypal inheritance ($.Widget is a constructor).
  • Renamed _init() to _create().
  • A new _init() method was added to perform "default functionality".
  • _init() is called every time the plugin is called without passing the name of a method to invoke.
  • Renamed _setData() to _setOption().
  • Removed _getData() since it should never be overridden.
  • Removed bindings for data events, must always use the option() method now.
  • Added widget() to return the main/outermost element of the widget.
  • Getter methods no longer need to be explicitly defined. Any method that returns a value other than undefined or the plugin instance is automatically treated as a getter. This also adds the ability to define a method that can act as a chainable setter and a getter.
  • destroy() now removes all widget-namespaced events bound to this.element and this.widget().
  • option() with no parameters now returns the full options hash.
  • Instantiating a widget directly via the new keyword now fully initializes the widget (no need to call the initialization method after the constructor).

link Properties moved from $.ui.foo to $.ui.foo.prototype

  • $.ui.foo.defaults -> $.ui.foo.prototype.options
  • $.ui.foo.eventPrefix -> $.ui.foo.prototype.widgetEventPrefix

link Other changes

  • $.widget() now accepts a base widget to extend as the second parameter; defaults to $.Widget.
  • Added $.widget.bridge() to allow creation of stateful plugins using a custom constructor.
  • Calling the constructor method multiple times now performs an action. If a hash is passed to the constructor, that hash is passed to the option() method and the _init()` method is called.

link New Widget Method

A new common method has been added, called widget(). This method will return the .ui-{pluginname} element. Depending on the plugin, in many cases this is different than the original element, otherwise it will return the original element.

For example, when you call $( "#myDiv" ).dialog() the #myDiv element gets the .ui-dialog-content class while a generated wrapper element gets the .ui-dialog class. Before the widget method existed it was a bit of a pain to call `$( "#myDiv" ).closest( ".ui-dialog" ) and though that worked in this case, for many plugins that doesn't work, for example, Datepicker, or Autocomplete, where the widget element is not a wrapper.

Now with the widget() method, you can simply call $( "#myDiv" ).dialog( "widget" ) to get the widget element.

link Example code

An example for migrating a custom widget from 1.7 to 1.8.