• If you are citizen of an European Union member nation, you may not use this service unless you are at least 16 years old.

  • You already know Dokkio is an AI-powered assistant to organize & manage your digital files & messages. Very soon, Dokkio will support Outlook as well as One Drive. Check it out today!

View
 

Widget

Page history last edited by Jörn Zaefferer 11 years, 9 months ago

This page covers designs and APIs that are common among many or all widgets. Patterns that exist throughout jQuery UI should be documented here.

 


Common Options

 

The animate option is used when a property is transitioning from one value to another. For example, if a height is changing or if the position of an element is changing. 

  • animate (mixed, default: {})
    • string: name of easing to use with default duration
    • number: duration in milliseconds with default easing 
    • object with easing and duration options
      • can also contain a down option with any of the above options
      • "down" animations occur when the panel being activated has a lower index than the currently active panel 
    • null/false: disables animation 

 

The disabled option is used for all widgets. Every widget must support the concept of fully enabled and fully disabled states. Some widgets may have partially disabled states as well. In these cases, the widget is free to add whatever additional API makes sense, but should take care to be consistent and future-compatible with other widgets where possible.

  • disabled (boolean, default: false)

 

The show and hide options are used when an element will be dynamically shown and hidden. These options support built-in animations such as fadeIn and slideUp, as well as all custom jQuery UI effects.  

  • hide (mixed, default: null)
    • true: fade with default duration
    • number: fade with specified duration
    • string: use the specified method/effect with default duration; can pass a built-in method, e.g., slideUp, or any effect, e.g., explode.
    • object: object containing an effect (method or effect) property, and optionally duration and easing properties. Custom properties can also be passed for effects that have more complex settings.
  • show (mixed, default: null)
    • true: fade with default duration
    • number: fade with specified duration
    • string: use the specified method/effect with default duration; can pass a built-in method, e.g., slideDown, or any effect, e.g., drop.
    • object: object containing an effect (method or effect) property, and optionally duration and easing properties. Custom properties can also be passed for effects that have more complex settings.

 


Common Methods

 

The enable and disable methods accompany the disabled option. Every widget must support calling these methods with no parameters in order to fully enable or disable the widget. Additional method signatures may be added to support partially disabled widgets.

  • enable()
  • disable()

 

The refresh method is used in cases where it makes sense for users to make changes directly in the DOM because there's no equivalent API exposed by the widget. In these cases, the user can make the appropriate changes and then call the refresh method and the widget should figure out what has changed and react accordingly.

  • refresh()

 

The destroy method reverts creation of the widget, leaving the element in its original state.

  • destroy()

 

The option method handles getting and setting options for the widget. Options are the main mechanism for managing the widget's state, so they must be kept in sync with the actual state of the widget over time. The API is the same as .attr() and .css().

  • option( key )
  • option( key, value )
  • option( values ) 

 

The widget method gives access to elements created by the widget, often wrapping the original element. In a dialog widget, the element is wrapped, and the widget method gives access to that wrapper. If there is no wrapper involved, the element itself is returned. To handle event delegation, the result of widget() is usually a better choice then binding to the element itself.

  • widget() 

 

 


Private Methods

 

The Widget API has a collection of methods intended for internal use, usually for direct use inside the widget, or in some cases, to override them. Though overriding is always and option and easy to implement with the _super() and _superApply() methods. 

 

  • _create()
    • This is the widget's constructor.
  • _init()
    • Widgets have the concept of initialization that is distinct from creation. Any time the plugin is called with no arguments or with only an option hash, the widget is initialized; this includes when the widget is created.
    • Initialization should only be handled if there is a logical action to perform on successive calls to the widget with no arguments. 
  • _destroy()
    • The destroy() method cleans up all common data, events, etc. and then delegates out to _destroy() for custom cleanup. 
  • _setOptions( options )
    • Called with a hash of key/value pairs to set whenever the option() method is called, regardless of the form in which option() was called.
    • Overriding this is useful if you can defer processor-intensive changes for multiple option changes. 
  • _setOption( key, value )
    • Called from _setOptions() for each individual option.
    • Widget state should be updated based on changes. 
  • _on( element, handlers )
    • Binds events to the specified element. If no element is specified then this.element is used.
    • handlers is an object of event names and event handlers. Delegation is supported via selectors inside the event names, e.g., "click .foo".
    • Maintains proper this context inside the handlers.
    • Automatically handles disabled widgets.
      • If the widget is disabled or the event occurs on an element with the ui-state-disabled class, the event handler is not invoked.
    • Event handlers are automatically namespaced and cleaned up on destroy. 
  • _off( element, eventName )
    • Unbinds events from the specified element (required, unlike _on).
    • eventName is a string of one or more space-separated events to remove. The widget's event namespace is appended to each when removing events. 
  • _super()
    • Invoke the method of the same name from the parent widget, with any specified arguments. Essentially .call().
  • _superApply( arguments )
    • Invoke the method of the same name from the parent widget, with the array of arguments. Essentially .apply().
  • _delay( fn, delay )
    • Invoke fn after delay milliseconds. Keeps `this` context correct. Essentially setTimeout().
    • Returns the timeout ID for use with clearTimeout().
  • _hoverable( element )
    • Sets up element to apply the ui-state-hover class on hover.
    • The event handlers are automatically cleaned up on destroy. 
  • _focusable( element )
    • Sets up element to apply the ui-state-focus class on hover.
    • The event handlers are automatically cleaned up on destroy.  
  • _trigger( type [, event [, data ] ] )
    • Triggers an event and its associated callback.
    • The option with the name equal to type is invoked as the callback.
    • The event name is the widget name + type.
      • NOTE: This is currently configurable with widgetEventPrefix, but that is going away.
    • event is the original event that caused this event to occur; useful for providing context to the listener.
    • data is a hash of data associated with the event. 
  • _show( element, option[, callback] )
    • Show element immediately, using built-in animation methods, or using custom effects.
    • See show option for possible values to option.
    • Invoke callback after the element is shown. 
  • _hide( element, option[, callback] )
    • Hide element immediately, using built-in animation methods, or using custom effects.
    • See hide option for possible values to option.
    • Invoke callback after the element is shown. 
    •  

 

Comments (0)

You don't have permission to comment on this page.