Widget: Extending the base widget class
+ +
+ This example shows how to extend the base Widget class to create a simple, re-usable spinner control. The Spinner class created in the example is not intended to be a fully featured spinner. It is used here as a concrete example, to convey some of the key concepts to keep in mind when extending the Widget class.
+
Click the buttons, or the arrow up/down and page up/down keys on your keyboard to change the spinner's value
+Extending The Widget Class
+
+Basic Class Structure
+ +Widgets classes follow the general pattern implemented by the Spinner class, shown in the code snippet below. The basic pattern for setting up a new widget class involves:
-
+
- Defining the constructor function for the new widget class, which invokes the superclass constructor to kick of the initialization chain (line 2) +
- Defining the static
NAMEproperty for the class, which is normally the class name in camel case, and is used to prefix events and CSS classes fired/created by the class (line 11)
+ - Defining the static
ATTRSproperty for the class, which defines the set of attribute which the class will introduce, in addition to the superclass attributes (line 18-57)
+ - Extending the
Widgetclass, and adding/over-riding any prototype properties/methods (line 59)
+
Note that these steps are the same for any class which is derived from Base, nothing Widget specific is involved yet.
+Widget adds the concept of a rendered UI to the existing Base lifecycle (viz. init, destroy and attribute state configuration), which we'll see show up in Widget specific areas below.
The HTML_PARSER Property
+ +
+The first Widget specific property Spinner implements is the static HTML_PARSER property. It is used to set the initial widget configuration based on markup, providing basic progressive enhancement support.
+
+The value of the HTML_PARSER property is an object literal, where each property is a widget attribute name, and the value is either a selector string (if the attribute is a node reference) or a function which is executed to provide
+a value for the attribute from the markup on the page. Markup is essentially thought of as an additional data source for the user to set initial attribute values, outside of the configuration object passed to the constructor
+(values passed to the constructor will take precedence over values picked up from markup).
+
For Spinner, HTML_PARSER defines a function for the value attribute, which sets the initial value of the spinner based on an input field if present in the markup.
Lifecycle Methods: initializer, destructor
+ +The initializer and destructor lifecycle methods are carried over from Base, and can be used to setup initial state during construction, and cleanup state during destruction respectively.
For Spinner, there is nothing special we need to do in the initializer (attribute setup is already taken care of), but it's left in the example to round out the lifecycle discussion.
The destructor takes care of detaching any event listeners Spinner adds outside of the bounding box (event listeners on/inside the bounding box are purged by Widget's destructor).
Rendering Lifecycle Methods: renderer, renderUI, bindUI, syncUI
+ +Widget adds a render method to the init and destroy lifecycle methods provided by Base. The init and destroy methods invoke the corresponding initializer and destructor implementations for the widget. Similarly, the render method invokes the renderer implementation for the widget. Note that the renderer method is not chained automatically, unlike the initializer and destructor methods.
The Widget class already provides a default renderer implementation, which invokes the following abstract methods in the order shown (with their respective responsibilities):
-
+
renderUI(): responsible for creating/adding elements to the DOM to render the widget.
+ bindUI(): responsible for binding event listeners (both attribute change and DOM event listeners) to 'activate' the rendered UI.
+ syncUI(): responsible for updating the rendered UI based on the current state of the widget.
+
Since the Spinner class has no need to modify the Widget renderer implementation, it simply implements the above 3 methods to handle the render phase:
A Note On Key Event Listeners
+ +The PR2 release adds basic support for "key" events, which are used by Spinner to setup a listener for arrow up/down and page up/down keys on the spinner's bounding box (line 30).
Event's "key" support allows Spinner to define a single listener, which is only invoked for the key specification provided. The key specification in the above use case is "down:38, 40, 33, 34" for most browsers, indicating that
+the _onDirectionKey method should only be called if the bounding box receives a keydown event with a character code which is either 38, 40, 33 or 34. "key" specifications can also contain more advanced filter criteria, involving modifiers such as CTRL and SHIFT.
For the Spinner widget, we're looking for a key event which fires repeatedly while the key is held down. This differs for Opera, so we need to fork for the key event we're interested in. Future versions of "key" support will aim to provide this type of higher level cross-browser abstraction also.
Attribute Supporting Methods
+ +Since all widgets are attribute driven, they all follow a pretty similar pattern when it comes to how those attributes are used. For a given attribute, widgets will generally have:
+-
+
- A prototype method to listen for changes in the attribute +
- A prototype method to update the state of the rendered UI, to reflect the value of an attribute. +
- A prototype method used to set/get/validate the attribute. +
These methods are kept on the prototype to facilitate customization at any of the levels - event handling, ui updates, set/get/validation logic.
+ +For Spinner, these corresponding methods for the value attribute are: _afterValueChange, _uiSetValue and _validateValue:
Since this example focuses on general patterns for widget development, validator/set/get functions are not defined for attributes such as min/max in the interests of keeping the example simple, but could be, in a production ready spinner.
+ +Rendering Support Methods
+ +Spinner's renderUI method hands off creation of the input field and buttons to the following helpers which use markup templates to generate node instances:
DOM Event Listeners
+ +The DOM event listeners attached during bindUI are straightforward event listeners, which receive the event facade for the DOM event, and update the spinner state accordingly.
A couple of interesting points worth noting: In the "key" listener we set up, we can call e.preventDefault() without having to check the character code, since the "key" event specifier will only invoke the listener
+if one of the specified keys is pressed (arrow/page up/down)
Also, to allow the spinner to update it's value while the mouse button is held down, we setup a timer, which gets cleared out when we receive a mouseup event on the document.
+ + + +ClassName Support Methods
+ +A key part of developing widgets which work with the DOM, is defining class names which it will use to mark the nodes it renders. These class names could be used to mark a node for later retrieval/lookup, for CSS application (both functional as well as cosmetic) or to indicate the current state of the widget.
+ +The widget infrastructure uses the ClassNameManager utility, to generate consistently named classes to apply to the nodes it adds to the page:
+Class names generated by the Widget's getClassName prototype method use the NAME field of the widget, to generate a prefixed classname through ClassNameManager - e.g. for spinner the this.getClassName("increment") above will generate the class name yui-spinner-increment ("yui" being the system level prefix, "spinner" being the widget name).
+When you need to generate standard class names in static code (where you don't have a reference to this.getClassName()), you can use the ClassNameManager directly, as shown in line 1 above, to achieve the same results.
+
CSS Considerations
+ +Since widget uses the getClassName method to generate state related class names and to mark the bounding box/content box of the widget (e.g. "yui-[widgetname]-content", "yui-[widgetname]-hidden", "yui-[widgetname]-disabled"), we need to provide the default CSS handling for states we're interested in handling for the new Spinner widget. The "yui-[widgetname]-hidden" class is probably one state class, which all widgets will provide implementations for.
Using The Spinner Widget
+ +For the example, we have an input field already on the page, which we'd like to enhance to create a Spinner instance:
+ + + +We provide the constructor for the Spinner with the contentBox which contains the input field with our initial value. The HTML_PARSER code we saw earlier, will extract the value from the input field, and use it as the initial value for the Spinner instance: