ドキュメント

UI/Developer Guide

From jQuery JavaScript Library

Jump to: navigation, search

Contents

jQuery UI API Developer Guide

The widget factory

jquery.ui.widget.js provides a factory method to create widget classes. The signature is $.widget(String name, Options prototype).

Calling the factory creates a widget method used to create and interact with an instance of that widget class.

The following default methods are available for each instance, in addition to those provided by the prototype argument:

  • destroy(): Removes the instance from the encapsulated DOM element, which was stored on instance creation
  • option(String key[, String value]): Gets or sets an option for this instance
  • enable(): Set disabled option to false, it's up to the instance to respect the option
  • disable(): Set disabled option to true, it's up to the instance to respect the option

Available properties for each instance:

  • options: The options for this widget instance, a mix of defaults with settings provided by the user
  • element: A jQuery object always containing a single DOMElement, which can be accessed with this.element[0].

You can override these methods in your own widget code. If you want to "inherit" the default methods, and add functionality, doing this:

$.Widget.prototype.methodToOverride.apply(this, arguments);
will execute the default method. Then you can add your custom code.

Usage:

 $.widget("ui.mywidget", {
   // default options
   options: {
     option1: "defaultValue",
     hidden: true
   },
   _create: function() {
     // creation code for mywidget
     // can use this.options
     if (this.options.hidden) {
       // and this.element
       this.element.hide(); 
     }
   },
   _doSomething: function() {
      // internal functions should be named with a leading underscore
      // manipulate the widget
   },
   value: function() {
     // calculate some value and return it
     return this._calculate();
   },
   length: function() {
     return this._someOtherValue();
   },
   destroy: function() {
       $.Widget.prototype.destroy.apply(this, arguments); // default destroy
        // now do other stuff particular to this widget
   }
 });

Every jQuery UI widget uses the widget factory, so for a more complete example, check out any plugin's full source, eg. jquery.ui.progressbar.js.


A more extensive tutorial for writing UI widgets.

Setters and Getters

The initial instantiation of the widget on an element can pass in starting options where the coder wants to overwrite the defaults.

  $("div").draggable({ helper: "clone", axis: "x" });

In this case, it will make all divs a draggable object with the defaults, except for the helper and axis options. Once the element is created, all other calls to the widget name where the first parameter is not a string will call the _init() method; if options are passed, the .option() method will be called before the _init() method.

At that point, all sets (and gets) are done through the option method of the widget. For example, to change the draggable axis to 'y' it would be set with:

  $("div").draggable("option", "axis", "y");

and to get its value use:

  var saveAxis = $("div").draggable("option", "axis");

This functionality is handled by the base widget, you will need to define what to do after each option is set. To do this, you must overwrite the _setOption function in your widget's prototype, like so

  _setOption: function(key, value) {
    // handle new settings and update options hash
  }

Internal functions & scopes explained

jQuery.data / jQuery.fn.data

Widget developers often have the need to create a so-called expando on a DOM node, which means to store additional data on the DOM node itself. However, this often produces memory leaks.

jQuery has its own way to deal with them -- the data function. It will create a unique string for each node and store data using that string in an internal object, so it won't produce circular references.

The widget instance of your widget is automatically stored through the widget factory with the key 'widget' (replace widget with your widget name):

this.element.data("draggable") === this;

or alternatively:

jQuery.data(this.element[0], "draggable") === this

The instance is also used by the UI framework to keep track of whether a widget was instantiated on a particular node.

Please see Internals/jQuery.data for more information on its usage.

jQuery.fn

jQuery.fn is the general plugin space of jQuery. A UI widget should expose exactly one function in that scope -- a single accessor function overloaded with different usages (this is done automatically when using the widget factory).

Take the function jQuery.fn.draggable() as an example:

  • jQuery(..).draggable() - Creates a new instance of jQuery.ui.draggable
  • jQuery(..).draggable({..}) - Creates a new instance of jQuery.ui.draggable with an optional options hash
  • jQuery(..).draggable("foo", [args]) - Calls the method foo() method on the draggable instance stored on the element with optional arguments

jQuery.ui

This is the scope where the widget constructor function is stored. Every widget should store only one function in that scope, so it's advisable to work with prototypes and instances (this is done automatically by using the widget factory).

Coding Style

Indenting Code

Indent code using tabs. It makes work much easier, because you can change your own tab size in your own editor if the indenting is too large for your view. But it's not so easy to change whitespace indents. Also, don't indent empty lines.

Conformance

Callbacks

Please think about possible callbacks wherever possible. They should be named closer to jQuery-style, instead of DOM like. Draggable, for instance, has the following callbacks:

  • start
  • drag
  • stop

and would be bound to like so:

 {
   start: function(event, ui){},
   drag: function(event, ui){},
   stop: function(event, ui){}
 }

Rather than using your own functions to call these callbacks, the widget factory provides a method:

this._trigger(type, event, uiHash)

where type is the event name, event is the browser event, and uiHash should be an object holding your own key/value pairs that you want to pass to the callback.

Please look at one of the existing widget implementations (Dialog for example) to get a direct view how to implement this stuff.

Derivations from other classes

All widgets related to mouse interaction make use of another class, the mouse interaction class. It basically handles all events (mousedown, mouseup, mousemove) and bindings, and you can use private callbacks to then do something with the new mouse position (move the element for example).

Look at the implementation of draggables/resizables for a self-explanatory view.

Encoding

Please make sure all your files are UTF-8 encoded. It can be very painful to correct encoding errors if three people commit work on the same file with three different encodings.

Documentation

Javadoc blocks

Please do not generate javadoc blocks for your functions and classes. Documentation should be written on the plugin's planning page on the Dev & Planning wiki. Only when finally released are plugins documented on docs.jquery.com/UI.

Inline commenting

Put inline comments before the line they comment and a space between the doubleslash and the comment text.

Comment the "why" things are done, not "how". The "how" is provided by the code. Document things that aren't obvious from the code.

// only left click starts dragging
if (e.which != 1)
  return true;

In this example, it's hard to guess what this prevention is for (until you know how the e.which property works), so an explanation doesn't hurt here.

Keyboard Shortcuts

"The DHTML Style Guide Working Group (DSGWG) has come together to create a recommendation for keyboard shortcuts to be used in website widgets" DHTML Style Guide