NOTE: Content from the old Development page has been ported into this page to avoid any confusion. This page is in-progress and we'll be making additions frequently so please check back for updates. Please note any questions or claifications here so they can be answered.
General Guidelines
- Follow the common JS style guide.
- Do not use jQuery.browser or jQuery.support.
- Plugins must work regardless of what options are passed to init. All options are truly optional and may be changed at any time.
- Use jQuery.ui.keyCode for all keyboard events.
- Do not abbreviate variable names; the bytes will be saved when compressed.
- Do not modify options that a user passes in, except when they are used to reflect the state of the plugin.
- All default values must be explicit.
- If the default behavior is to parse the DOM for a value, then null should be used for the default.
- No default value should be undefined.
- Defaults should be specified in alphabetical order, with callbacks grouped at the bottom.
- Don't save any data on the element other than the plugin instance.
- An exception to this rule is if you need to store data on subordinate elements.
- Use HTML, not XHTML .
- Use <!doctype html> to trigger standards mode and <meta charset="utf-8">.
- Use valid HTML, ie <div></div> not <div/>.
.noConflict() compliance
Wrap plugins in a closure that passes jQuery in as a parameter. Inside the closure, only reference jQuery through the parameter variable.
(function( $ ) {
// inside here only reference $, not jQuery
}( jQuery ) );
passing elements as options or parameters
Whenever a user can specify an element, they should be able to provide any of the following:
- DOMElement
- array of DOMElement's
- jQuery object
- function that returns any of the above
- Is there a common set of parameters that would be passed to this function?
- Is there a common context that would be set for this function?
- See #4957
TODO: move everything below here to widget factory docs and link to that doc from here.
getting/setting options after init
add notes about how to listen to options
callbacks
add notes about how to trigger callbacks and what to pass in the ui object
specifying icons
add notes about how to specify which icons to use, e.g., which close icon.
specifying events
add notes about how to specify which events should trigger an action
- click, ctrl+click, mouseover
applying CSS classes
- applying hover states
- applying focus states
z-index and stacking
Widgets that append elements to the page should use the .ui-front stacking technique.
These widgets will have an appendTo option but will not have a zIndex option.
The default for appendTo should be null, which means to walk up the DOM from the associated element looking for an existing element with the ui-front class. For example, the autocomplete widget's menu is appended to the DOM, and walks up from the associated input field.
If an element is found with the ui-front class, the element being appended will be appended to the found element.
If no element is found, the element is appended to the body.
If the user explicitly sets the appendTo option, then no searching is performed and the specified element is used.
The appended element must also have the ui-front class added, which will apply a z-index to the element. The element must also have it's position style set to absolute or fixed by some other class.
Comments (2)
Scott González said
at 7:59 am on Jun 30, 2009
no Hungarian notation
Scott González said
at 11:24 am on Jul 15, 2009
don't use .data() for plugin properties
You don't have permission to comment on this page.