Debian Codegraph @

closure-library/closure/goog/ui/drilldownrow.js

raw
1 // Copyright 2007 The Closure Library Authors. All Rights Reserved.
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS-IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14
15 /**
16 * @fileoverview Tree-like drilldown components for HTML tables.
17 *
18 * This component supports expanding and collapsing groups of rows in
19 * HTML tables. The behavior is like typical Tree widgets, but tables
20 * need special support to enable the tree behaviors.
21 *
22 * Any row or rows in an HTML table can be DrilldownRows. The root
23 * DrilldownRow nodes are always visible in the table, but the rest show
24 * or hide as input events expand and collapse their ancestors.
25 *
26 * Programming them: Top-level DrilldownRows are made by decorating
27 * a TR element. Children are made with addChild or addChildAt, and
28 * are entered into the document by the render() method.
29 *
30 * A DrilldownRow can have any number of children. If it has no children
31 * it can be loaded, not loaded, or with a load in progress.
32 * Top-level DrilldownRows are always displayed (though setting
33 * style.display on a containing DOM node could make one be not
34 * visible to the user). A DrilldownRow can be expanded, or not. A
35 * DrilldownRow displays if all of its ancestors are expanded.
36 *
37 * Set up event handlers and style each row for the application in an
38 * enterDocument method.
39 *
40 * Children normally render into the document lazily, at the first
41 * moment when all ancestors are expanded.
42 *
43 * @see ../demos/drilldownrow.html
44 */
45
46 // TODO(user): Build support for dynamically loading DrilldownRows,
47 // probably using automplete as an example to follow.
48
49 // TODO(user): Make DrilldownRows accessible through the keyboard.
50
51 // The render method is redefined in this class because when addChildAt renders
52 // the new child it assumes that the child's DOM node will be a child
53 // of the parent component's DOM node, but all DOM nodes of DrilldownRows
54 // in the same tree of DrilldownRows are siblings to each other.
55 //
56 // Arguments (or lack of arguments) to the render methods in Component
57 // all determine the place of the new DOM node in the DOM tree, but
58 // the place of a new DrilldownRow in the DOM needs to be determined by
59 // its position in the tree of DrilldownRows.
60
61 goog.provide('goog.ui.DrilldownRow');
62
63 goog.require('goog.asserts');
64 goog.require('goog.dom');
65 goog.require('goog.dom.TagName');
66 goog.require('goog.dom.classlist');
67 goog.require('goog.dom.safe');
68 goog.require('goog.html.SafeHtml');
69 goog.require('goog.string.Unicode');
70 goog.require('goog.ui.Component');
71
72
73
74 /**
75 * Builds a DrilldownRow component, which can overlay a tree
76 * structure onto sections of an HTML table.
77 *
78 * @param {!goog.ui.DrilldownRow.DrilldownRowProperties=} opt_properties
79 * Optional properties.
80 * @param {goog.dom.DomHelper=} opt_domHelper Optional DOM helper.
81 * @constructor
82 * @extends {goog.ui.Component}
83 * @final
84 */
85 goog.ui.DrilldownRow = function(opt_properties, opt_domHelper) {
86 goog.ui.Component.call(this, opt_domHelper);
87 var properties = opt_properties || {};
88
89 // Initialize instance variables.
90
91 var html;
92 if (!goog.isDefAndNotNull(properties.html)) {
93 html = goog.html.SafeHtml.EMPTY;
94 } else {
95 goog.asserts.assert(properties.html instanceof goog.html.SafeHtml);
96 html = properties.html;
97 }
98 /**
99 * String of HTML to initialize the DOM structure for the table row.
100 * Should have the form '<tr attr="etc">Row contents here</tr>'.
101 * @type {!goog.html.SafeHtml}
102 * @private
103 */
104 this.html_ = html;
105
106 /**
107 * Controls whether this component's children will show when it shows.
108 * @type {boolean}
109 * @private
110 */
111 this.expanded_ =
112 typeof properties.expanded != 'undefined' ? properties.expanded : true;
113
114 /**
115 * If this component's DOM element is created from a string of
116 * HTML, this is the function to call when it is entered into the DOM tree.
117 * @type {Function} args are DrilldownRow and goog.events.EventHandler
118 * of the DrilldownRow.
119 * @private
120 */
121 this.decoratorFn_ = properties.decorator || goog.ui.DrilldownRow.decorate;
122
123 /**
124 * Is the DrilldownRow to be displayed? If it is rendered, this mirrors
125 * the style.display of the DrilldownRow's row.
126 * @type {boolean}
127 * @private
128 */
129 this.displayed_ = true;
130 };
131 goog.inherits(goog.ui.DrilldownRow, goog.ui.Component);
132
133
134 /**
135 * Used to define properties for a new DrilldownRow. Properties can contain:
136 * loaded: initializes the isLoaded property, defaults to true.
137 * expanded: DrilldownRow expanded or not, default is true.
138 * html: Relevant and required for DrilldownRows to be added as
139 * children. Ignored when decorating an existing table row.
140 * decorator: Function that accepts one DrilldownRow argument, and
141 * should customize and style the row. The default is to call
142 * goog.ui.DrilldownRow.decorator.
143 * @typedef {{
144 * loaded: (boolean|undefined),
145 * expanded: (boolean|undefined),
146 * html: (!goog.html.SafeHtml|undefined),
147 * decorator: (Function|undefined)
148 * }}
149 */
150 goog.ui.DrilldownRow.DrilldownRowProperties;
151
152
153 /**
154 * Example object with properties of the form accepted by the class
155 * constructor. These are educational and show the compiler that
156 * these properties can be set so it doesn't emit warnings.
157 */
158 goog.ui.DrilldownRow.sampleProperties = {
159 html: goog.html.SafeHtml.create(
160 goog.dom.TagName.TR, {},
161 goog.html.SafeHtml.concat(
162 goog.html.SafeHtml.create(goog.dom.TagName.TD, {}, 'Sample'),
163 goog.html.SafeHtml.create(goog.dom.TagName.TD, {}, 'Sample'))),
164 loaded: true,
165 decorator: function(selfObj, handler) {
166 // When the mouse is hovering, add CSS class goog-drilldown-hover.
167 goog.ui.DrilldownRow.decorate(selfObj);
168 var row = selfObj.getElement();
169 handler.listen(row, 'mouseover', function() {
170 goog.dom.classlist.add(row, goog.getCssName('goog-drilldown-hover'));
171 });
172 handler.listen(row, 'mouseout', function() {
173 goog.dom.classlist.remove(row, goog.getCssName('goog-drilldown-hover'));
174 });
175 }
176 };
177
178
179 //
180 // Implementations of Component methods.
181 //
182
183
184 /**
185 * The base class method calls its superclass method and this
186 * drilldown's 'decorator' method as defined in the constructor.
187 * @override
188 */
189 goog.ui.DrilldownRow.prototype.enterDocument = function() {
190 goog.ui.DrilldownRow.superClass_.enterDocument.call(this);
191 this.decoratorFn_(this, this.getHandler());
192 };
193
194
195 /** @override */
196 goog.ui.DrilldownRow.prototype.createDom = function() {
197 this.setElementInternal(
198 goog.ui.DrilldownRow.createRowNode_(this.html_, this.getDomHelper()));
199 };
200
201
202 /**
203 * A top-level DrilldownRow decorates a TR element.
204 *
205 * @param {Element} node The element to test for decorability.
206 * @return {boolean} true iff the node is a TR.
207 * @override
208 */
209 goog.ui.DrilldownRow.prototype.canDecorate = function(node) {
210 return node.tagName == goog.dom.TagName.TR;
211 };
212
213
214 /**
215 * Child drilldowns are rendered when needed.
216 *
217 * @param {goog.ui.Component} child New DrilldownRow child to be added.
218 * @param {number} index position to be occupied by the child.
219 * @param {boolean=} opt_render true to force immediate rendering.
220 * @override
221 */
222 goog.ui.DrilldownRow.prototype.addChildAt = function(child, index, opt_render) {
223 goog.asserts.assertInstanceof(child, goog.ui.DrilldownRow);
224 goog.ui.DrilldownRow.superClass_.addChildAt.call(this, child, index, false);
225 child.setDisplayable_(this.isVisible_() && this.isExpanded());
226 if (opt_render && !child.isInDocument()) {
227 child.render();
228 }
229 };
230
231
232 /** @override */
233 goog.ui.DrilldownRow.prototype.removeChild = function(child) {
234 goog.dom.removeNode(child.getElement());
235 return goog.ui.DrilldownRow.superClass_.removeChild.call(this, child);
236 };
237
238
239 /**
240 * Rendering of DrilldownRow's is on need, do not call this directly
241 * from application code.
242 *
243 * Rendering a DrilldownRow places it according to its position in its
244 * tree of DrilldownRows. DrilldownRows cannot be placed any other
245 * way so this method does not use any arguments. This does not call
246 * the base class method and does not modify any of this
247 * DrilldownRow's children.
248 * @override
249 */
250 goog.ui.DrilldownRow.prototype.render = function() {
251 if (arguments.length) {
252 throw new Error('A DrilldownRow cannot be placed under a specific parent.');
253 } else {
254 var parent = this.getParent();
255 if (!parent.isInDocument()) {
256 throw new Error('Cannot render child of un-rendered parent');
257 }
258 // The new child's TR node needs to go just after the last TR
259 // of the part of the parent's subtree that is to the left
260 // of this. The subtree includes the parent.
261 goog.asserts.assertInstanceof(parent, goog.ui.DrilldownRow);
262 var previous = parent.previousRenderedChild_(this);
263 var row;
264 if (previous) {
265 goog.asserts.assertInstanceof(previous, goog.ui.DrilldownRow);
266 row = previous.lastRenderedLeaf_().getElement();
267 } else {
268 row = parent.getElement();
269 }
270 row = /** @type {Element} */ (row.nextSibling);
271 // Render the child row component into the document.
272 if (row) {
273 this.renderBefore(row);
274 } else {
275 // Render at the end of the parent of this DrilldownRow's
276 // DOM element.
277 var tbody = /** @type {Element} */ (parent.getElement().parentNode);
278 goog.ui.DrilldownRow.superClass_.render.call(this, tbody);
279 }
280 }
281 };
282
283
284 /**
285 * Finds the numeric index of this child within its parent Component.
286 * Throws an exception if it has no parent.
287 *
288 * @return {number} index of this within the children of the parent Component.
289 */
290 goog.ui.DrilldownRow.prototype.findIndex = function() {
291 var parent = this.getParent();
292 if (!parent) {
293 throw new Error('Component has no parent');
294 }
295 return parent.indexOfChild(this);
296 };
297
298
299 //
300 // Type-specific operations
301 //
302
303
304 /**
305 * Returns the expanded state of the DrilldownRow.
306 *
307 * @return {boolean} true iff this is expanded.
308 */
309 goog.ui.DrilldownRow.prototype.isExpanded = function() {
310 return this.expanded_;
311 };
312
313
314 /**
315 * Sets the expanded state of this DrilldownRow: makes all children
316 * displayable or not displayable corresponding to the expanded state.
317 *
318 * @param {boolean} expanded whether this should be expanded or not.
319 */
320 goog.ui.DrilldownRow.prototype.setExpanded = function(expanded) {
321 if (expanded != this.expanded_) {
322 this.expanded_ = expanded;
323 var elem = this.getElement();
324 goog.asserts.assert(elem);
325 goog.dom.classlist.toggle(elem, goog.getCssName('goog-drilldown-expanded'));
326 goog.dom.classlist.toggle(
327 elem, goog.getCssName('goog-drilldown-collapsed'));
328 if (this.isVisible_()) {
329 this.forEachChild(function(child) { child.setDisplayable_(expanded); });
330 }
331 }
332 };
333
334
335 /**
336 * Returns this DrilldownRow's level in the tree. Top level is 1.
337 *
338 * @return {number} depth of this DrilldownRow in its tree of drilldowns.
339 */
340 goog.ui.DrilldownRow.prototype.getDepth = function() {
341 for (var component = this, depth = 0;
342 component instanceof goog.ui.DrilldownRow;
343 component = component.getParent(), depth++) {
344 }
345 return depth;
346 };
347
348
349 /**
350 * This static function is a default decorator that adds HTML at the
351 * beginning of the first cell to display indentation and an expander
352 * image; sets up a click handler on the toggler; initializes a class
353 * for the row: either goog-drilldown-expanded or
354 * goog-drilldown-collapsed, depending on the initial state of the
355 * DrilldownRow; and sets up a click event handler on the toggler
356 * element.
357 *
358 * This creates a DIV with class=toggle. Your application can set up
359 * CSS style rules something like this:
360 *
361 * tr.goog-drilldown-expanded .toggle {
362 * background-image: url('minus.png');
363 * }
364 *
365 * tr.goog-drilldown-collapsed .toggle {
366 * background-image: url('plus.png');
367 * }
368 *
369 * These background images show whether the DrilldownRow is expanded.
370 *
371 * @param {goog.ui.DrilldownRow} selfObj DrilldownRow to be decorated.
372 */
373 goog.ui.DrilldownRow.decorate = function(selfObj) {
374 var depth = selfObj.getDepth();
375 var row = selfObj.getElement();
376 goog.asserts.assert(row);
377 if (!row.cells) {
378 throw new Error('No cells');
379 }
380 var cell = row.cells[0];
381 var dom = selfObj.getDomHelper();
382 var fragment = dom.createDom(
383 goog.dom.TagName.DIV, {'style': 'float: left; width: ' + depth + 'em;'},
384 dom.createDom(
385 goog.dom.TagName.DIV,
386 {'class': 'toggle', 'style': 'width: 1em; float: right;'},
387 // NOTE: NBSP is probably only needed by IE6. This div can probably be
388 // made contentless.
389 goog.string.Unicode.NBSP));
390 cell.insertBefore(fragment, cell.firstChild);
391 goog.dom.classlist.add(
392 row, selfObj.isExpanded() ? goog.getCssName('goog-drilldown-expanded') :
393 goog.getCssName('goog-drilldown-collapsed'));
394 // Default mouse event handling:
395 var toggler =
396 goog.dom.getElementsByTagName(goog.dom.TagName.DIV, fragment)[0];
397 selfObj.getHandler().listen(toggler, 'click', function(event) {
398 selfObj.setExpanded(!selfObj.isExpanded());
399 });
400 };
401
402
403 //
404 // Private methods
405 //
406
407
408 /**
409 * Turn display of a DrilldownRow on or off. If the DrilldownRow has not
410 * yet been rendered, this renders it. This propagates the effect
411 * of the change recursively as needed -- children displaying iff the
412 * parent is displayed and expanded.
413 *
414 * @param {boolean} display state, true iff display is desired.
415 * @private
416 */
417 goog.ui.DrilldownRow.prototype.setDisplayable_ = function(display) {
418 if (display && !this.isInDocument()) {
419 this.render();
420 }
421 if (this.displayed_ == display) {
422 return;
423 }
424 this.displayed_ = display;
425 if (this.isInDocument()) {
426 this.getElement().style.display = display ? '' : 'none';
427 }
428 var selfObj = this;
429 this.forEachChild(function(child) {
430 child.setDisplayable_(display && selfObj.expanded_);
431 });
432 };
433
434
435 /**
436 * True iff this and all its DrilldownRow parents are displayable. The
437 * value is an approximation to actual visibility, since it does not
438 * look at whether DOM nodes containing the top-level component have
439 * display: none, visibility: hidden or are otherwise not displayable.
440 * So this visibility is relative to the top-level component.
441 *
442 * @return {boolean} visibility of this relative to its top-level drilldown.
443 * @private
444 */
445 goog.ui.DrilldownRow.prototype.isVisible_ = function() {
446 for (var component = this; component instanceof goog.ui.DrilldownRow;
447 component = component.getParent()) {
448 if (!component.displayed_) return false;
449 }
450 return true;
451 };
452
453
454 /**
455 * Create and return a TR element from HTML that looks like
456 * "<tr> ... </tr>".
457 *
458 * @param {!goog.html.SafeHtml} html for one row.
459 * @param {!goog.dom.DomHelper} dom DOM to hold the Element.
460 * @return {Element} table row node created from the HTML.
461 * @private
462 */
463 goog.ui.DrilldownRow.createRowNode_ = function(html, dom) {
464 // Note: this may be slow.
465 var tableHtml = goog.html.SafeHtml.create(goog.dom.TagName.TABLE, {}, html);
466 var div = dom.createElement(goog.dom.TagName.DIV);
467 goog.dom.safe.setInnerHtml(div, tableHtml);
468 return div.firstChild.rows[0];
469 };
470
471
472 /**
473 * Get the recursively rightmost child that is in the document.
474 *
475 * @return {goog.ui.DrilldownRow} rightmost child currently entered in
476 * the document, potentially this DrilldownRow. If this is in the
477 * document, result is non-null.
478 * @private
479 */
480 goog.ui.DrilldownRow.prototype.lastRenderedLeaf_ = function() {
481 var leaf = null;
482 for (var node = this; node && node.isInDocument();
483 // Node will become undefined if parent has no children.
484 node = node.getChildAt(node.getChildCount() - 1)) {
485 leaf = node;
486 }
487 return /** @type {goog.ui.DrilldownRow} */ (leaf);
488 };
489
490
491 /**
492 * Search this node's direct children for the last one that is in the
493 * document and is before the given child.
494 * @param {goog.ui.DrilldownRow} child The child to stop the search at.
495 * @return {goog.ui.Component?} The last child component before the given child
496 * that is in the document.
497 * @private
498 */
499 goog.ui.DrilldownRow.prototype.previousRenderedChild_ = function(child) {
500 for (var i = this.getChildCount() - 1; i >= 0; i--) {
501 if (this.getChildAt(i) == child) {
502 for (var j = i - 1; j >= 0; j--) {
503 var prev = this.getChildAt(j);
504 if (prev.isInDocument()) {
505 return prev;
506 }
507 }
508 }
509 }
510 return null;
511 };