← Back to branch summary

~landscape/lazr-js/trunk

« back to all changes in this revision

Viewing changes to src-js/lazrjs/yui/3.0.0/build/widget/widget-stack.js

  • Committer: Sidnei da Silva
  • Date: 2009-10-21 21:43:07 UTC
  • mfrom: (120.2.15 yui-3.0.0)
  • mto: (124.5.1 trunk)
  • mto: This revision was merged to the branch mainline in revision 126.
  • Revision ID: sidnei.da.silva@canonical.com-20091021214307-mpul9404n317puk5
- Merge from yui-3.0.0, resolving conflicts

Show diffs side-by-side

added added

removed removed

Lines of Context:
src-js/lazrjs/yui/3.0.0/build/widget/widget-stack.js
 
1
/*
 
2
Copyright (c) 2009, Yahoo! Inc. All rights reserved.
 
3
Code licensed under the BSD License:
 
4
http://developer.yahoo.net/yui/license.txt
 
5
version: 3.0.0
 
6
build: 1549
 
7
*/
 
8
YUI.add('widget-stack', function(Y) {
 
9
 
 
10
/**
 
11
 * Provides stackable (z-index) support for Widgets through an extension.
 
12
 *
 
13
 * @module widget-stack
 
14
 */
 
15
    var L = Y.Lang,
 
16
        UA = Y.UA,
 
17
        Node = Y.Node,
 
18
        Widget = Y.Widget,
 
19
 
 
20
        ZINDEX = "zIndex",
 
21
        SHIM = "shim",
 
22
        VISIBLE = "visible",
 
23
 
 
24
        BOUNDING_BOX = "boundingBox",
 
25
 
 
26
        RENDER_UI = "renderUI",
 
27
        BIND_UI = "bindUI",
 
28
        SYNC_UI = "syncUI",
 
29
 
 
30
        OFFSET_WIDTH = "offsetWidth",
 
31
        OFFSET_HEIGHT = "offsetHeight",
 
32
        PARENT_NODE = "parentNode",
 
33
        FIRST_CHILD = "firstChild",
 
34
        OWNER_DOCUMENT = "ownerDocument",
 
35
 
 
36
        WIDTH = "width",
 
37
        HEIGHT = "height",
 
38
        PX = "px",
 
39
 
 
40
        // HANDLE KEYS
 
41
        SHIM_DEFERRED = "shimdeferred",
 
42
        SHIM_RESIZE = "shimresize",
 
43
 
 
44
        // Events
 
45
        VisibleChange = "visibleChange",
 
46
        WidthChange = "widthChange",
 
47
        HeightChange = "heightChange",
 
48
        ShimChange = "shimChange",
 
49
        ZIndexChange = "zIndexChange",
 
50
        ContentUpdate = "contentUpdate",
 
51
 
 
52
        // CSS
 
53
        STACKED = "stacked";
 
54
 
 
55
    /**
 
56
     * Widget extension, which can be used to add stackable (z-index) support to the 
 
57
     * base Widget class along with a shimming solution, through the 
 
58
     * <a href="Base.html#method_build">Base.build</a> method.
 
59
     *
 
60
     * @class WidgetStack
 
61
     * @param {Object} User configuration object
 
62
     */
 
63
    function Stack(config) {
 
64
        this._stackNode = this.get(BOUNDING_BOX);
 
65
        this._stackHandles = {};
 
66
 
 
67
        // WIDGET METHOD OVERLAP
 
68
        Y.after(this._renderUIStack, this, RENDER_UI);
 
69
        Y.after(this._syncUIStack, this, SYNC_UI);
 
70
        Y.after(this._bindUIStack, this, BIND_UI);
 
71
    }
 
72
 
 
73
    // Static Properties
 
74
    /**
 
75
     * Static property used to define the default attribute 
 
76
     * configuration introduced by WidgetStack.
 
77
     * 
 
78
     * @property WidgetStack.ATTRS
 
79
     * @type Object
 
80
     * @static
 
81
     */
 
82
    Stack.ATTRS = {
 
83
        /**
 
84
         * @attribute shim
 
85
         * @type boolean
 
86
         * @default false, for all browsers other than IE6, for which a shim is enabled by default.
 
87
         * 
 
88
         * @description Boolean flag to indicate whether or not a shim should be added to the Widgets
 
89
         * boundingBox, to protect it from select box bleedthrough.
 
90
         */
 
91
        shim: {
 
92
            value: (UA.ie == 6)
 
93
        },
 
94
 
 
95
        /**
 
96
         * @attribute zIndex
 
97
         * @type number
 
98
         * @default 0
 
99
         * @description The z-index to apply to the Widgets boundingBox. Non-numerical values for 
 
100
         * zIndex will be converted to 0
 
101
         */
 
102
        zIndex: {
 
103
            value:0,
 
104
            setter: function(val) {
 
105
                return this._setZIndex(val);
 
106
            }
 
107
        }
 
108
    };
 
109
 
 
110
    /**
 
111
     * The HTML parsing rules for the WidgetStack class.
 
112
     * 
 
113
     * @property WidgetStack.HTML_PARSER
 
114
     * @static
 
115
     * @type Object
 
116
     */
 
117
    Stack.HTML_PARSER = {
 
118
        zIndex: function(contentBox) {
 
119
            return contentBox.getStyle(ZINDEX);
 
120
        }
 
121
    };
 
122
 
 
123
    /**
 
124
     * Default class used to mark the shim element
 
125
     *
 
126
     * @property WidgetStack.SHIM_CLASS_NAME
 
127
     * @type String
 
128
     * @static
 
129
     * @default "yui-widget-shim"
 
130
     */
 
131
    Stack.SHIM_CLASS_NAME = Widget.getClassName(SHIM);
 
132
 
 
133
    /**
 
134
     * Default class used to mark the boundingBox of a stacked widget.
 
135
     * 
 
136
     * @property WidgetStack.STACKED_CLASS_NAME
 
137
     * @type String
 
138
     * @static
 
139
     * @default "yui-widget-stacked"
 
140
     */
 
141
    Stack.STACKED_CLASS_NAME = Widget.getClassName(STACKED);
 
142
 
 
143
    /**
 
144
     * Default markup template used to generate the shim element.
 
145
     * 
 
146
     * @property WidgetStack.SHIM_TEMPLATE
 
147
     * @type String
 
148
     * @static
 
149
     */
 
150
    Stack.SHIM_TEMPLATE = '<iframe class="' + Stack.SHIM_CLASS_NAME + '" frameborder="0" title="Widget Stacking Shim" src="javascript:false" tabindex="-1" role="presentation"></iframe>';
 
151
 
 
152
    Stack.prototype = {
 
153
 
 
154
        /**
 
155
         * Synchronizes the UI to match the Widgets stack state. This method in 
 
156
         * invoked after syncUI is invoked for the Widget class using YUI's aop infrastructure.
 
157
         *
 
158
         * @method _syncUIStack
 
159
         * @protected
 
160
         */
 
161
        _syncUIStack: function() {
 
162
            this._uiSetShim(this.get(SHIM));
 
163
            this._uiSetZIndex(this.get(ZINDEX));
 
164
        },
 
165
 
 
166
        /**
 
167
         * Binds event listeners responsible for updating the UI state in response to 
 
168
         * Widget stack related state changes.
 
169
         * <p>
 
170
         * This method is invoked after bindUI is invoked for the Widget class
 
171
         * using YUI's aop infrastructure.
 
172
         * </p>
 
173
         * @method _bindUIStack
 
174
         * @protected
 
175
         */
 
176
        _bindUIStack: function() {
 
177
            this.after(ShimChange, this._afterShimChange);
 
178
            this.after(ZIndexChange, this._afterZIndexChange);
 
179
        },
 
180
 
 
181
        /**
 
182
         * Creates/Initializes the DOM to support stackability.
 
183
         * <p>
 
184
         * This method in invoked after renderUI is invoked for the Widget class
 
185
         * using YUI's aop infrastructure.
 
186
         * </p>
 
187
         * @method _renderUIStack
 
188
         * @protected
 
189
         */
 
190
        _renderUIStack: function() {
 
191
            this._stackNode.addClass(Stack.STACKED_CLASS_NAME);
 
192
        },
 
193
 
 
194
        /**
 
195
         * Default setter for zIndex attribute changes. Normalizes zIndex values to 
 
196
         * numbers, converting non-numerical values to 0.
 
197
         *
 
198
         * @method _setZIndex
 
199
         * @protected
 
200
         * @param {String | Number} zIndex
 
201
         * @return {Number} Normalized zIndex
 
202
         */
 
203
        _setZIndex: function(zIndex) {
 
204
            if (L.isString(zIndex)) {
 
205
                zIndex = parseInt(zIndex, 10);
 
206
            }
 
207
            if (!L.isNumber(zIndex)) {
 
208
                zIndex = 0;
 
209
            }
 
210
            return zIndex;
 
211
        },
 
212
 
 
213
        /**
 
214
         * Default attribute change listener for the shim attribute, responsible
 
215
         * for updating the UI, in response to attribute changes.
 
216
         *
 
217
         * @method _afterShimChange
 
218
         * @protected
 
219
         * @param {EventFacade} e The event facade for the attribute change
 
220
         */
 
221
        _afterShimChange : function(e) {
 
222
            this._uiSetShim(e.newVal);
 
223
        },
 
224
 
 
225
        /**
 
226
         * Default attribute change listener for the zIndex attribute, responsible
 
227
         * for updating the UI, in response to attribute changes.
 
228
         * 
 
229
         * @method _afterZIndexChange
 
230
         * @protected
 
231
         * @param {EventFacade} e The event facade for the attribute change
 
232
         */
 
233
        _afterZIndexChange : function(e) {
 
234
            this._uiSetZIndex(e.newVal);
 
235
        },
 
236
 
 
237
        /**
 
238
         * Updates the UI to reflect the zIndex value passed in.
 
239
         *
 
240
         * @method _uiSetZIndex
 
241
         * @protected
 
242
         * @param {number} zIndex The zindex to be reflected in the UI
 
243
         */
 
244
        _uiSetZIndex: function (zIndex) {
 
245
            this._stackNode.setStyle(ZINDEX, zIndex);
 
246
        },
 
247
 
 
248
        /**
 
249
         * Updates the UI to enable/disable the shim. If the widget is not currently visible,
 
250
         * creation of the shim is deferred until it is made visible, for performance reasons.
 
251
         *
 
252
         * @method _uiSetShim
 
253
         * @protected
 
254
         * @param {boolean} enable If true, creates/renders the shim, if false, removes it.
 
255
         */
 
256
        _uiSetShim: function (enable) {
 
257
            if (enable) {
 
258
                // Lazy creation
 
259
                if (this.get(VISIBLE)) {
 
260
                    this._renderShim();
 
261
                } else {
 
262
                    this._renderShimDeferred();
 
263
                }
 
264
            } else {
 
265
                this._destroyShim();
 
266
            }
 
267
        },
 
268
 
 
269
        /**
 
270
         * Sets up change handlers for the visible attribute, to defer shim creation/rendering 
 
271
         * until the Widget is made visible.
 
272
         * 
 
273
         * @method _renderShimDeferred
 
274
         * @private
 
275
         */
 
276
        _renderShimDeferred : function() {
 
277
 
 
278
            this._stackHandles[SHIM_DEFERRED] = this._stackHandles[SHIM_DEFERRED] || [];
 
279
 
 
280
            var handles = this._stackHandles[SHIM_DEFERRED],
 
281
                createBeforeVisible = function(e) {
 
282
                    if (e.newVal) {
 
283
                        this._renderShim();
 
284
                    }
 
285
                };
 
286
 
 
287
            handles.push(this.on(VisibleChange, createBeforeVisible));
 
288
        },
 
289
 
 
290
        /**
 
291
         * Sets up event listeners to resize the shim when the size of the Widget changes.
 
292
         * <p>
 
293
         * NOTE: This method is only used for IE6 currently, since IE6 doesn't support a way to
 
294
         * resize the shim purely through CSS, when the Widget does not have an explicit width/height 
 
295
         * set.
 
296
         * </p>
 
297
         * @method _addShimResizeHandlers
 
298
         * @private
 
299
         */
 
300
        _addShimResizeHandlers : function() {
 
301
 
 
302
            this._stackHandles[SHIM_RESIZE] = this._stackHandles[SHIM_RESIZE] || [];
 
303
 
 
304
            var sizeShim = this.sizeShim,
 
305
                handles = this._stackHandles[SHIM_RESIZE];
 
306
 
 
307
            this.sizeShim();
 
308
 
 
309
            handles.push(this.after(VisibleChange, sizeShim));
 
310
            handles.push(this.after(WidthChange, sizeShim));
 
311
            handles.push(this.after(HeightChange, sizeShim));
 
312
            handles.push(this.after(ContentUpdate, sizeShim));
 
313
        },
 
314
 
 
315
        /**
 
316
         * Detaches any handles stored for the provided key
 
317
         *
 
318
         * @method _detachStackHandles
 
319
         * @param String handleKey The key defining the group of handles which should be detached
 
320
         * @private
 
321
         */
 
322
        _detachStackHandles : function(handleKey) {
 
323
            var handles = this._stackHandles[handleKey],
 
324
                handle;
 
325
 
 
326
            if (handles && handles.length > 0) {
 
327
                while((handle = handles.pop())) {
 
328
                    handle.detach();
 
329
                }
 
330
            }
 
331
        },
 
332
 
 
333
        /**
 
334
         * Creates the shim element and adds it to the DOM
 
335
         *
 
336
         * @method _renderShim
 
337
         * @private
 
338
         */
 
339
        _renderShim : function() {
 
340
            var shimEl = this._shimNode,
 
341
                stackEl = this._stackNode;
 
342
 
 
343
            if (!shimEl) {
 
344
                shimEl = this._shimNode = this._getShimTemplate();
 
345
                stackEl.insertBefore(shimEl, stackEl.get(FIRST_CHILD));
 
346
 
 
347
                if (UA.ie == 6) {
 
348
                    this._addShimResizeHandlers();
 
349
                }
 
350
                this._detachStackHandles(SHIM_DEFERRED);
 
351
            }
 
352
        },
 
353
 
 
354
        /**
 
355
         * Removes the shim from the DOM, and detaches any related event
 
356
         * listeners.
 
357
         *
 
358
         * @method _destroyShim
 
359
         * @private
 
360
         */
 
361
        _destroyShim : function() {
 
362
            if (this._shimNode) {
 
363
                this._shimNode.get(PARENT_NODE).removeChild(this._shimNode);
 
364
                this._shimNode = null;
 
365
 
 
366
                this._detachStackHandles(SHIM_DEFERRED);
 
367
                this._detachStackHandles(SHIM_RESIZE);
 
368
            }
 
369
        },
 
370
 
 
371
        /**
 
372
         * For IE6, synchronizes the size and position of iframe shim to that of 
 
373
         * Widget bounding box which it is protecting. For all other browsers,
 
374
         * this method does not do anything.
 
375
         *
 
376
         * @method sizeShim
 
377
         */
 
378
        sizeShim: function () {
 
379
            var shim = this._shimNode,
 
380
                node = this._stackNode;
 
381
 
 
382
            if (shim && UA.ie === 6 && this.get(VISIBLE)) {
 
383
                shim.setStyle(WIDTH, node.get(OFFSET_WIDTH) + PX);
 
384
                shim.setStyle(HEIGHT, node.get(OFFSET_HEIGHT) + PX);
 
385
            }
 
386
        },
 
387
 
 
388
        /**
 
389
         * Creates a cloned shim node, using the SHIM_TEMPLATE html template, for use on a new instance.
 
390
         *
 
391
         * @method _getShimTemplate
 
392
         * @private
 
393
         * @return {Node} node A new shim Node instance.
 
394
         */
 
395
        _getShimTemplate : function() {
 
396
            return Node.create(Stack.SHIM_TEMPLATE, this._stackNode.get(OWNER_DOCUMENT));
 
397
        }
 
398
    };
 
399
 
 
400
    Y.WidgetStack = Stack;
 
401
 
 
402
 
 
403
}, '3.0.0' ,{requires:['widget']});