widget-base.js revision 787ab2d836a2419cedf3cc46b72c0522fbfd5e93
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas SoomeYUI.add('widget-base', function(Y) {
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome/**
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * Provides the base Widget class, with HTML Parser support
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome *
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @module widget
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome */
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome/**
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * Provides the base Widget class
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome *
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @module widget
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @submodule widget-base
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome */
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soomevar L = Y.Lang,
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome Node = Y.Node,
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome ClassNameManager = Y.ClassNameManager,
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome _getClassName = ClassNameManager.getClassName,
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome _getWidgetClassName,
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome _toInitialCap = Y.cached(function(str) {
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome return str.substring(0, 1).toUpperCase() + str.substring(1);
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome }),
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome // K-Weight, IE GC optimizations
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome CONTENT = "content",
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome VISIBLE = "visible",
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome HIDDEN = "hidden",
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome DISABLED = "disabled",
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome FOCUSED = "focused",
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome WIDTH = "width",
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome HEIGHT = "height",
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome BOUNDING_BOX = "boundingBox",
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome CONTENT_BOX = "contentBox",
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome PARENT_NODE = "parentNode",
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome OWNER_DOCUMENT = "ownerDocument",
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome AUTO = "auto",
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome SRC_NODE = "srcNode",
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome BODY = "body",
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome TAB_INDEX = "tabIndex",
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome ID = "id",
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome RENDER = "render",
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome RENDERED = "rendered",
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome DESTROYED = "destroyed",
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome STRINGS = "strings",
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome DIV = "<div></div>",
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome CHANGE = "Change",
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome LOADING = "loading",
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome _UISET = "_uiSet",
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome EMPTY_STR = "",
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome EMPTY_FN = function() {},
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome TRUE = true,
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome FALSE = false,
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome UI,
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome ATTRS = {},
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome UI_ATTRS = [VISIBLE, DISABLED, HEIGHT, WIDTH, FOCUSED],
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome WEBKIT = Y.UA.webkit,
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome // Widget nodeguid-to-instance map.
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome _instances = {};
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome/**
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * A base class for widgets, providing:
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * <ul>
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * <li>The render lifecycle method, in addition to the init and destroy
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * lifecycle methods provide by Base</li>
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * <li>Abstract methods to support consistent MVC structure across
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * widgets: renderer, renderUI, bindUI, syncUI</li>
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * <li>Support for common widget attributes, such as boundingBox, contentBox, visible,
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * disabled, focused, strings</li>
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * </ul>
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome *
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @param config {Object} Object literal specifying widget configuration properties.
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome *
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @class Widget
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @constructor
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @extends Base
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome */
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soomefunction Widget(config) {
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome // kweight
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome var widget = this,
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome parentNode,
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome render,
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome constructor = widget.constructor;
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome widget._strs = {};
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome widget._cssPrefix = constructor.CSS_PREFIX || _getClassName(constructor.NAME.toLowerCase());
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome Widget.superclass.constructor.apply(widget, arguments);
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome render = widget.get(RENDER);
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome if (render) {
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome // Render could be a node or boolean
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome if (render !== TRUE) {
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome parentNode = render;
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome }
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome widget.render(parentNode);
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome }
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome}
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome/**
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * Static property provides a string to identify the class.
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * <p>
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * Currently used to apply class identifiers to the bounding box
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * and to classify events fired by the widget.
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * </p>
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome *
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @property Widget.NAME
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @type String
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @static
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome */
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas SoomeWidget.NAME = "widget";
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome/**
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * Constant used to identify state changes originating from
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * the DOM (as opposed to the JavaScript model).
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome *
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @property Widget.UI_SRC
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @type String
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @static
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @final
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome */
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas SoomeUI = Widget.UI_SRC = "ui";
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome/**
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * Static property used to define the default attribute
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * configuration for the Widget.
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome *
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @property Widget.ATTRS
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @type Object
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @static
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome */
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas SoomeWidget.ATTRS = ATTRS;
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome// Trying to optimize kweight by setting up attrs this way saves about 0.4K min'd
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome/**
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @attribute id
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @writeOnce
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @default Generated using guid()
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @type String
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome */
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas SoomeATTRS[ID] = {
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome valueFn: "_guid",
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome writeOnce: TRUE
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome};
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome/**
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * Flag indicating whether or not this Widget
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * has been through the render lifecycle phase.
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome *
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @attribute rendered
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @readOnly
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @default false
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @type boolean
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome */
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas SoomeATTRS[RENDERED] = {
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome value:FALSE,
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome readOnly: TRUE
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome};
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome/**
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @attribute boundingBox
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @description The outermost DOM node for the Widget, used for sizing and positioning
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * of a Widget as well as a containing element for any decorator elements used
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * for skinning.
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @type String | Node
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @writeOnce
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome */
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas SoomeATTRS[BOUNDING_BOX] = {
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome value:null,
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome setter: "_setBB",
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome writeOnce: TRUE
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome};
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome/**
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @attribute contentBox
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @description A DOM node that is a direct descendant of a Widget's bounding box that
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * houses its content.
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @type String | Node
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @writeOnce
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome */
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas SoomeATTRS[CONTENT_BOX] = {
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome valueFn:"_defaultCB",
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome setter: "_setCB",
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome writeOnce: TRUE
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome};
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome/**
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @attribute tabIndex
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @description Number (between -32767 to 32767) indicating the widget's
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * position in the default tab flow. The value is used to set the
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * "tabIndex" attribute on the widget's bounding box. Negative values allow
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * the widget to receive DOM focus programmatically (by calling the focus
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * method), while being removed from the default tab flow. A value of
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * null removes the "tabIndex" attribute from the widget's bounding box.
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @type Number
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @default null
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome */
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas SoomeATTRS[TAB_INDEX] = {
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome value: null,
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome validator: "_validTabIndex"
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome};
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome/**
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @attribute focused
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @description Boolean indicating if the Widget, or one of its descendants,
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * has focus.
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @readOnly
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @default false
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @type boolean
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome */
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas SoomeATTRS[FOCUSED] = {
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome value: FALSE,
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome readOnly:TRUE
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome};
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome/**
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @attribute disabled
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @description Boolean indicating if the Widget should be disabled. The disabled implementation
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * is left to the specific classes extending widget.
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @default false
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @type boolean
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome */
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas SoomeATTRS[DISABLED] = {
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome value: FALSE
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome};
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome/**
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @attribute visible
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @description Boolean indicating weather or not the Widget is visible.
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @default TRUE
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @type boolean
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome */
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas SoomeATTRS[VISIBLE] = {
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome value: TRUE
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome};
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome/**
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @attribute height
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @description String with units, or number, representing the height of the Widget. If a number is provided,
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * the default unit, defined by the Widgets DEF_UNIT, property is used.
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @default EMPTY_STR
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @type {String | Number}
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome */
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas SoomeATTRS[HEIGHT] = {
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome value: EMPTY_STR
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome};
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome/**
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @attribute width
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @description String with units, or number, representing the width of the Widget. If a number is provided,
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * the default unit, defined by the Widgets DEF_UNIT, property is used.
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @default EMPTY_STR
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @type {String | Number}
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome */
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas SoomeATTRS[WIDTH] = {
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome value: EMPTY_STR
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome};
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome/**
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @attribute strings
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @description Collection of strings used to label elements of the Widget's UI.
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @default null
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @type Object
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome */
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas SoomeATTRS[STRINGS] = {
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome value: {},
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome setter: "_strSetter",
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome getter: "_strGetter"
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome};
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome/**
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * Whether or not to render the widget automatically after init, and optionally, to which parent node.
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome *
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @attribute render
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @type boolean | Node
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @writeOnce
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome */
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas SoomeATTRS[RENDER] = {
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome value:FALSE,
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome writeOnce:TRUE
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome};
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome/**
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * The css prefix which the static Widget.getClassName method should use when constructing class names
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome *
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @property Widget.CSS_PREFIX
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @type String
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @default Widget.NAME.toLowerCase()
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @private
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @static
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome */
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas SoomeWidget.CSS_PREFIX = _getClassName(Widget.NAME.toLowerCase());
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome/**
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * Generate a standard prefixed classname for the Widget, prefixed by the default prefix defined
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * by the <code>Y.config.classNamePrefix</code> attribute used by <code>ClassNameManager</code> and
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * <code>Widget.NAME.toLowerCase()</code> (e.g. "yui-widget-xxxxx-yyyyy", based on default values for
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * the prefix and widget class name).
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * <p>
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * The instance based version of this method can be used to generate standard prefixed classnames,
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * based on the instances NAME, as opposed to Widget.NAME. This method should be used when you
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * need to use a constant class name across different types instances.
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * </p>
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @method getClassName
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @param {String*} args* 0..n strings which should be concatenated, using the default separator defined by ClassNameManager, to create the class name
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome */
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas SoomeWidget.getClassName = function() {
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome // arguments needs to be array'fied to concat
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome return _getClassName.apply(ClassNameManager, [Widget.CSS_PREFIX].concat(Y.Array(arguments), true));
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome};
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome_getWidgetClassName = Widget.getClassName;
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome/**
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * Returns the widget instance whose bounding box contains, or is, the given node.
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * <p>
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * In the case of nested widgets, the nearest bounding box ancestor is used to
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * return the widget instance.
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * </p>
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @method Widget.getByNode
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @static
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @param node {Node | String} The node for which to return a Widget instance. If a selector
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * string is passed in, which selects more than one node, the first node found is used.
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @return {Widget} Widget instance, or null if not found.
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome */
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas SoomeWidget.getByNode = function(node) {
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome var widget,
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome widgetMarker = _getWidgetClassName();
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome node = Node.one(node);
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome if (node) {
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome node = node.ancestor("." + widgetMarker, true);
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome if (node) {
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome widget = _instances[Y.stamp(node, TRUE)];
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome }
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome }
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome return widget || null;
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome};
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas SoomeY.extend(Widget, Y.Base, {
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome /**
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * Returns a class name prefixed with the the value of the
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * <code>YUI.config.classNamePrefix</code> attribute + the instances <code>NAME</code> property.
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * Uses <code>YUI.config.classNameDelimiter</code> attribute to delimit the provided strings.
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * e.g.
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * <code>
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * <pre>
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * // returns "yui-slider-foo-bar", for a slider instance
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * var scn = slider.getClassName('foo','bar');
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome *
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * // returns "yui-overlay-foo-bar", for an overlay instance
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * var ocn = overlay.getClassName('foo','bar');
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * </pre>
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * </code>
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome *
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @method getClassName
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @param {String}+ One or more classname bits to be joined and prefixed
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome */
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome getClassName: function () {
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome return _getClassName.apply(ClassNameManager, [this._cssPrefix].concat(Y.Array(arguments), true));
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome },
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome /**
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * Initializer lifecycle implementation for the Widget class. Registers the
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * widget instance, and runs through the Widget's HTML_PARSER definition.
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome *
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @method initializer
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @protected
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @param config {Object} Configuration object literal for the widget
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome */
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome initializer: function(config) {
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome _instances[Y.stamp(this.get(BOUNDING_BOX))] = this;
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome /**
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * Notification event, which widget implementations can fire, when
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * they change the content of the widget. This event has no default
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * behavior and cannot be prevented, so the "on" or "after"
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * moments are effectively equivalent (with on listeners being invoked before
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * after listeners).
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome *
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @event widget:contentUpdate
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @preventable false
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @param {EventFacade} e The Event Facade
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome */
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome if (this._applyParser) {
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome this._applyParser(config);
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome }
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome },
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome /**
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * Destructor lifecycle implementation for the Widget class. Purges events attached
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * to the bounding box (and all child nodes) and removes the Widget from the
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * list of registered widgets.
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome *
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @method destructor
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @protected
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome */
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome destructor: function() {
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome var boundingBox = this.get(BOUNDING_BOX),
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome bbGuid = Y.stamp(boundingBox, TRUE);
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome if (bbGuid in _instances) {
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome delete _instances[bbGuid];
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome }
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome this._destroyBox();
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome },
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome /**
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * Removes and destroys the widgets rendered boundingBox, contentBox,
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * and detaches bound UI events.
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome *
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @method _destroyBox
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @protected
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome */
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome _destroyBox : function() {
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome var boundingBox = this.get(BOUNDING_BOX),
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome contentBox = this.get(CONTENT_BOX),
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome same = boundingBox && boundingBox.compareTo(contentBox);
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome if (this.UI_EVENTS) {
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome this._destroyUIEvents();
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome }
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome this._unbindUI(boundingBox);
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome if (contentBox) {
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome contentBox.remove(TRUE);
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome }
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome if (!same) {
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome boundingBox.remove(TRUE);
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome }
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome },
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome /**
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * Establishes the initial DOM for the widget. Invoking this
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * method will lead to the creating of all DOM elements for
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * the widget (or the manipulation of existing DOM elements
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * for the progressive enhancement use case).
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * <p>
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * This method should only be invoked once for an initialized
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * widget.
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * </p>
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * <p>
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * It delegates to the widget specific renderer method to do
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * the actual work.
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * </p>
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome *
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @method render
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @chainable
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @final
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * @param parentNode {Object | String} Optional. The Node under which the
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * Widget is to be rendered. This can be a Node instance or a CSS selector string.
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * <p>
afc2ba1deb75b323afde536f2dd18bcafdaa308dToomas Soome * If the selector string returns more than one Node, the first node will be used
* as the parentNode. NOTE: This argument is required if both the boundingBox and contentBox
* are not currently in the document. If it's not provided, the Widget will be rendered
* to the body of the current document in this case.
* </p>
*/
render: function(parentNode) {
if (!this.get(DESTROYED) && !this.get(RENDERED)) {
/**
* Lifecycle event for the render phase, fired prior to rendering the UI
* for the widget (prior to invoking the widget's renderer method).
* <p>
* Subscribers to the "on" moment of this event, will be notified
* before the widget is rendered.
* </p>
* <p>
* Subscribers to the "after" moment of this event, will be notified
* after rendering is complete.
* </p>
*
* @event widget:render
* @preventable _defRenderFn
* @param {EventFacade} e The Event Facade
*/
this.publish(RENDER, {
queuable:FALSE,
fireOnce:TRUE,
defaultTargetOnly:TRUE,
defaultFn: this._defRenderFn
});
this.fire(RENDER, {parentNode: (parentNode) ? Node.one(parentNode) : null});
}
return this;
},
/**
* Default render handler
*
* @method _defRenderFn
* @protected
* @param {EventFacade} e The Event object
* @param {Node} parentNode The parent node to render to, if passed in to the <code>render</code> method
*/
_defRenderFn : function(e) {
this._parentNode = e.parentNode;
this.renderer();
this._set(RENDERED, TRUE);
this._removeLoadingClassNames();
},
/**
* Creates DOM (or manipulates DOM for progressive enhancement)
* This method is invoked by render() and is not chained
* automatically for the class hierarchy (unlike initializer, destructor)
* so it should be chained manually for subclasses if required.
*
* @method renderer
* @protected
*/
renderer: function() {
// kweight
var widget = this;
widget._renderUI();
widget.renderUI();
widget._bindUI();
widget.bindUI();
widget._syncUI();
widget.syncUI();
},
/**
* Configures/Sets up listeners to bind Widget State to UI/DOM
*
* This method is not called by framework and is not chained
* automatically for the class hierarchy.
*
* @method bindUI
* @protected
*/
bindUI: EMPTY_FN,
/**å
* Adds nodes to the DOM
*
* This method is not called by framework and is not chained
* automatically for the class hierarchy.
*
* @method renderUI
* @protected
*/
renderUI: EMPTY_FN,
/**
* Refreshes the rendered UI, based on Widget State
*
* This method is not called by framework and is not chained
* automatically for the class hierarchy.
*
* @method syncUI
* @protected
*
*/
syncUI: EMPTY_FN,
/**
* @method hide
* @description Hides the Widget by setting the "visible" attribute to "false".
* @chainable
*/
hide: function() {
return this.set(VISIBLE, FALSE);
},
/**
* @method show
* @description Shows the Widget by setting the "visible" attribute to "true".
* @chainable
*/
show: function() {
return this.set(VISIBLE, TRUE);
},
/**
* @method focus
* @description Causes the Widget to receive the focus by setting the "focused"
* attribute to "true".
* @chainable
*/
focus: function () {
return this._set(FOCUSED, TRUE);
},
/**
* @method blur
* @description Causes the Widget to lose focus by setting the "focused" attribute
* to "false"
* @chainable
*/
blur: function () {
return this._set(FOCUSED, FALSE);
},
/**
* @method enable
* @description Set the Widget's "disabled" attribute to "false".
* @chainable
*/
enable: function() {
return this.set(DISABLED, FALSE);
},
/**
* @method disable
* @description Set the Widget's "disabled" attribute to "true".
* @chainable
*/
disable: function() {
return this.set(DISABLED, TRUE);
},
/**
* @method _uiSizeCB
* @protected
* @param {boolean} expand
*/
_uiSizeCB : function(expand) {
this.get(CONTENT_BOX).toggleClass(_getWidgetClassName(CONTENT, "expanded"), expand);
},
/**
* Helper method to collect the boundingBox and contentBox, set styles and append to the provided parentNode, if not
* already a child. The owner document of the boundingBox, or the owner document of the contentBox will be used
* as the document into which the Widget is rendered if a parentNode is node is not provided. If both the boundingBox and
* the contentBox are not currently in the document, and no parentNode is provided, the widget will be rendered
* to the current document's body.
*
* @method _renderBox
* @private
* @param {Node} parentNode The parentNode to render the widget to. If not provided, and both the boundingBox and
* the contentBox are not currently in the document, the widget will be rendered to the current document's body.
*/
_renderBox: function(parentNode) {
// TODO: Performance Optimization [ More effective algo to reduce Node refs, compares, replaces? ]
var widget = this, // kweight
contentBox = widget.get(CONTENT_BOX),
boundingBox = widget.get(BOUNDING_BOX),
srcNode = widget.get(SRC_NODE),
defParentNode = widget.DEF_PARENT_NODE,
doc = (srcNode && srcNode.get(OWNER_DOCUMENT)) || boundingBox.get(OWNER_DOCUMENT) || contentBox.get(OWNER_DOCUMENT);
// If srcNode (assume it's always in doc), have contentBox take its place (widget render responsible for re-use of srcNode contents)
if (srcNode && !srcNode.compareTo(contentBox) && !contentBox.inDoc(doc)) {
srcNode.replace(contentBox);
}
if (!boundingBox.compareTo(contentBox.get(PARENT_NODE)) && !boundingBox.compareTo(contentBox)) {
// If contentBox box is already in the document, have boundingBox box take it's place
if (contentBox.inDoc(doc)) {
contentBox.replace(boundingBox);
}
boundingBox.appendChild(contentBox);
}
parentNode = parentNode || (defParentNode && Node.one(defParentNode));
if (parentNode) {
parentNode.appendChild(boundingBox);
} else if (!boundingBox.inDoc(doc)) {
Node.one(BODY).insert(boundingBox, 0);
}
},
/**
* Setter for the boundingBox attribute
*
* @method _setBB
* @private
* @param Node/String
* @return Node
*/
_setBB: function(node) {
return this._setBox(this.get(ID), node, this.BOUNDING_TEMPLATE);
},
/**
* Setter for the contentBox attribute
*
* @method _setCB
* @private
* @param {Node|String} node
* @return Node
*/
_setCB: function(node) {
return (this.CONTENT_TEMPLATE === null) ? this.get(BOUNDING_BOX) : this._setBox(null, node, this.CONTENT_TEMPLATE);
},
/**
* Returns the default value for the contentBox attribute.
*
* For the Widget class, this will be the srcNode if provided, otherwise null (resulting in
* a new contentBox node instance being created)
*
* @method _defaultCB
* @protected
*/
_defaultCB : function(node) {
return this.get(SRC_NODE) || null;
},
/**
* Helper method to set the bounding/content box, or create it from
* the provided template if not found.
*
* @method _setBox
* @private
*
* @param {String} id The node's id attribute
* @param {Node|String} node The node reference
* @param {String} template HTML string template for the node
* @return {Node} The node
*/
_setBox : function(id, node, template) {
node = Node.one(node) || Node.create(template);
if (!node.get(ID)) {
node.set(ID, id || Y.guid());
}
return node;
},
/**
* Initializes the UI state for the Widget's bounding/content boxes.
*
* @method _renderUI
* @protected
*/
_renderUI: function() {
this._renderBoxClassNames();
this._renderBox(this._parentNode);
},
/**
* Applies standard class names to the boundingBox and contentBox
*
* @method _renderBoxClassNames
* @protected
*/
_renderBoxClassNames : function() {
var classes = this._getClasses(),
cl,
boundingBox = this.get(BOUNDING_BOX),
i;
boundingBox.addClass(_getWidgetClassName());
// Start from Widget Sub Class
for (i = classes.length-3; i >= 0; i--) {
cl = classes[i];
boundingBox.addClass(cl.CSS_PREFIX || _getClassName(cl.NAME.toLowerCase()));
}
// Use instance based name for content box
this.get(CONTENT_BOX).addClass(this.getClassName(CONTENT));
},
/**
* Removes class names representative of the widget's loading state from
* the boundingBox.
*
* @method _removeLoadingClassNames
* @protected
*/
_removeLoadingClassNames: function () {
var boundingBox = this.get(BOUNDING_BOX),
contentBox = this.get(CONTENT_BOX),
instClass = this.getClassName(LOADING),
widgetClass = _getWidgetClassName(LOADING);
boundingBox.removeClass(widgetClass)
.removeClass(instClass);
contentBox.removeClass(widgetClass)
.removeClass(instClass);
},
/**
* Sets up DOM and CustomEvent listeners for the widget.
*
* @method _bindUI
* @protected
*/
_bindUI: function() {
this._bindAttrUI(this._UI_ATTRS.BIND);
this._bindDOM();
},
/**
* @method _unbindUI
* @protected
*/
_unbindUI : function(boundingBox) {
this._unbindDOM(boundingBox);
},
/**
* Sets up DOM listeners, on elements rendered by the widget.
*
* @method _bindDOM
* @protected
*/
_bindDOM : function() {
var oDocument = this.get(BOUNDING_BOX).get(OWNER_DOCUMENT);
// TODO: Perf Optimization: Use Widget.getByNode delegation, to get by
// with just one _onDocFocus subscription per sandbox, instead of one per widget
this._hDocFocus = oDocument.on("focus", this._onDocFocus, this);
// Fix for Webkit:
// Document doesn't receive focus in Webkit when the user mouses
// down on it, so the "focused" attribute won't get set to the
// correct value.
if (WEBKIT) {
this._hDocMouseDown = oDocument.on("mousedown", this._onDocMouseDown, this);
}
},
/**
* @method _unbindDOM
* @protected
*/
_unbindDOM : function(boundingBox) {
if (this._hDocFocus) {
this._hDocFocus.detach();
}
if (WEBKIT && this._hDocMouseDown) {
this._hDocMouseDown.detach();
}
},
/**
* Updates the widget UI to reflect the attribute state.
*
* @method _syncUI
* @protected
*/
_syncUI: function() {
this._syncAttrUI(this._UI_ATTRS.SYNC);
},
/**
* Sets the height on the widget's bounding box element
*
* @method _uiSetHeight
* @protected
* @param {String | Number} val
*/
_uiSetHeight: function(val) {
this._uiSetDim(HEIGHT, val);
this._uiSizeCB((val !== EMPTY_STR && val !== AUTO));
},
/**
* Sets the width on the widget's bounding box element
*
* @method _uiSetWidth
* @protected
* @param {String | Number} val
*/
_uiSetWidth: function(val) {
this._uiSetDim(WIDTH, val);
},
/**
* @method _uiSetDim
* @private
* @param {String} dim The dimension - "width" or "height"
* @param {Number | String} val The value to set
*/
_uiSetDim: function(dimension, val) {
this.get(BOUNDING_BOX).setStyle(dimension, L.isNumber(val) ? val + this.DEF_UNIT : val);
},
/**
* Sets the visible state for the UI
*
* @method _uiSetVisible
* @protected
* @param {boolean} val
*/
_uiSetVisible: function(val) {
this.get(BOUNDING_BOX).toggleClass(this.getClassName(HIDDEN), !val);
},
/**
* Sets the disabled state for the UI
*
* @protected
* @param {boolean} val
*/
_uiSetDisabled: function(val) {
this.get(BOUNDING_BOX).toggleClass(this.getClassName(DISABLED), val);
},
/**
* Sets the focused state for the UI
*
* @protected
* @param {boolean} val
* @param {string} src String representing the source that triggered an update to
* the UI.
*/
_uiSetFocused: function(val, src) {
var boundingBox = this.get(BOUNDING_BOX);
boundingBox.toggleClass(this.getClassName(FOCUSED), val);
if (src !== UI) {
if (val) {
boundingBox.focus();
} else {
boundingBox.blur();
}
}
},
/**
* Set the tabIndex on the widget's rendered UI
*
* @method _uiSetTabIndex
* @protected
* @param Number
*/
_uiSetTabIndex: function(index) {
var boundingBox = this.get(BOUNDING_BOX);
if (L.isNumber(index)) {
boundingBox.set(TAB_INDEX, index);
} else {
boundingBox.removeAttribute(TAB_INDEX);
}
},
/**
* @method _onDocMouseDown
* @description "mousedown" event handler for the owner document of the
* widget's bounding box.
* @protected
* @param {EventFacade} evt The event facade for the DOM focus event
*/
_onDocMouseDown: function (evt) {
if (this._domFocus) {
this._onDocFocus(evt);
}
},
/**
* DOM focus event handler, used to sync the state of the Widget with the DOM
*
* @method _onDocFocus
* @protected
* @param {EventFacade} evt The event facade for the DOM focus event
*/
_onDocFocus: function (evt) {
this._domFocus = this.get(BOUNDING_BOX).contains(evt.target); // contains() checks invoking node also
this._set(FOCUSED, this._domFocus, { src: UI });
},
/**
* Generic toString implementation for all widgets.
*
* @method toString
* @return {String} The default string value for the widget [ displays the NAME of the instance, and the unique id ]
*/
toString: function() {
// Using deprecated name prop for kweight squeeze.
return this.name + "[" + this.get(ID) + "]";
},
/**
* Default unit to use for dimension values
*
* @property DEF_UNIT
* @type String
*/
DEF_UNIT : "px",
/**
* Default node to render the bounding box to. If not set,
* will default to the current document body.
*
* @property DEF_PARENT_NODE
* @type String | Node
*/
DEF_PARENT_NODE : null,
/**
* Property defining the markup template for content box. If your Widget doesn't
* need the dual boundingBox/contentBox structure, set CONTENT_TEMPLATE to null,
* and contentBox and boundingBox will both point to the same Node.
*
* @property CONTENT_TEMPLATE
* @type String
*/
CONTENT_TEMPLATE : DIV,
/**
* Property defining the markup template for bounding box.
*
* @property BOUNDING_TEMPLATE
* @type String
*/
BOUNDING_TEMPLATE : DIV,
/**
* @method _guid
* @protected
*/
_guid : function() {
return Y.guid();
},
/**
* @method _validTabIndex
* @protected
* @param {Number} tabIndex
*/
_validTabIndex : function (tabIndex) {
return (L.isNumber(tabIndex) || L.isNull(tabIndex));
},
/**
* Binds after listeners for the list of attributes provided
*
* @method _bindAttrUI
* @private
* @param {Array} attrs
*/
_bindAttrUI : function(attrs) {
var i,
l = attrs.length;
for (i = 0; i < l; i++) {
this.after(attrs[i] + CHANGE, this._setAttrUI);
}
},
/**
* Invokes the _uiSet&#61;ATTR NAME&#62; method for the list of attributes provided
*
* @method _syncAttrUI
* @private
* @param {Array} attrs
*/
_syncAttrUI : function(attrs) {
var i, l = attrs.length, attr;
for (i = 0; i < l; i++) {
attr = attrs[i];
this[_UISET + _toInitialCap(attr)](this.get(attr));
}
},
/**
* @method _setAttrUI
* @private
* @param {EventFacade} e
*/
_setAttrUI : function(e) {
this[_UISET + _toInitialCap(e.attrName)](e.newVal, e.src);
},
/**
* The default setter for the strings attribute. Merges partial sets
* into the full string set, to allow users to partial sets of strings
*
* @method _strSetter
* @protected
* @param {Object} strings
* @return {String} The full set of strings to set
*/
_strSetter : function(strings) {
return Y.merge(this.get(STRINGS), strings);
},
/**
* Helper method to get a specific string value
*
* @deprecated Used by deprecated WidgetLocale implementations.
* @method getString
* @param {String} key
* @return {String} The string
*/
getString : function(key) {
return this.get(STRINGS)[key];
},
/**
* Helper method to get the complete set of strings for the widget
*
* @deprecated Used by deprecated WidgetLocale implementations.
* @method getString
* @param {String} key
* @return {String} The string
*/
getStrings : function() {
return this.get(STRINGS);
},
/**
* The lists of UI attributes to bind and sync for widget's _bindUI and _syncUI implementations
*
* @property _UI_ATTRS
* @type Object
* @private
*/
_UI_ATTRS : {
BIND: UI_ATTRS,
SYNC: UI_ATTRS.concat(TAB_INDEX)
}
});
Y.Widget = Widget;
}, '@VERSION@' ,{requires:['attribute', 'event-focus', 'base-base', 'base-pluginhost', 'node-base', 'node-style', 'classnamemanager']});