Debian Codegraph @

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

raw
1 // Copyright 2008 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 Base class for container renderers.
17 *
18 * @author [email protected] (Attila Bodis)
19 */
20
21 goog.provide('goog.ui.ContainerRenderer');
22
23 goog.require('goog.a11y.aria');
24 goog.require('goog.array');
25 goog.require('goog.asserts');
26 goog.require('goog.dom.NodeType');
27 goog.require('goog.dom.TagName');
28 goog.require('goog.dom.classlist');
29 goog.require('goog.string');
30 goog.require('goog.style');
31 goog.require('goog.ui.registry');
32 goog.require('goog.userAgent');
33
34
35
36 /**
37 * Default renderer for {@link goog.ui.Container}. Can be used as-is, but
38 * subclasses of Container will probably want to use renderers specifically
39 * tailored for them by extending this class.
40 * @param {string=} opt_ariaRole Optional ARIA role used for the element.
41 * @constructor
42 */
43 goog.ui.ContainerRenderer = function(opt_ariaRole) {
44 // By default, the ARIA role is unspecified.
45 /** @private {string|undefined} */
46 this.ariaRole_ = opt_ariaRole;
47 };
48 goog.addSingletonGetter(goog.ui.ContainerRenderer);
49
50
51 /**
52 * Constructs a new renderer and sets the CSS class that the renderer will use
53 * as the base CSS class to apply to all elements rendered by that renderer.
54 * An example to use this function using a menu is:
55 *
56 * <pre>
57 * var myCustomRenderer = goog.ui.ContainerRenderer.getCustomRenderer(
58 * goog.ui.MenuRenderer, 'my-special-menu');
59 * var newMenu = new goog.ui.Menu(opt_domHelper, myCustomRenderer);
60 * </pre>
61 *
62 * Your styles for the menu can now be:
63 * <pre>
64 * .my-special-menu { }
65 * </pre>
66 *
67 * <em>instead</em> of
68 * <pre>
69 * .CSS_MY_SPECIAL_MENU .goog-menu { }
70 * </pre>
71 *
72 * You would want to use this functionality when you want an instance of a
73 * component to have specific styles different than the other components of the
74 * same type in your application. This avoids using descendant selectors to
75 * apply the specific styles to this component.
76 *
77 * @param {Function} ctor The constructor of the renderer you want to create.
78 * @param {string} cssClassName The name of the CSS class for this renderer.
79 * @return {goog.ui.ContainerRenderer} An instance of the desired renderer with
80 * its getCssClass() method overridden to return the supplied custom CSS
81 * class name.
82 */
83 goog.ui.ContainerRenderer.getCustomRenderer = function(ctor, cssClassName) {
84 var renderer = new ctor();
85
86 /**
87 * Returns the CSS class to be applied to the root element of components
88 * rendered using this renderer.
89 * @return {string} Renderer-specific CSS class.
90 */
91 renderer.getCssClass = function() { return cssClassName; };
92
93 return renderer;
94 };
95
96
97 /**
98 * Default CSS class to be applied to the root element of containers rendered
99 * by this renderer.
100 * @type {string}
101 */
102 goog.ui.ContainerRenderer.CSS_CLASS = goog.getCssName('goog-container');
103
104
105 /**
106 * Returns the ARIA role to be applied to the container.
107 * See http://wiki/Main/ARIA for more info.
108 * @return {undefined|string} ARIA role.
109 */
110 goog.ui.ContainerRenderer.prototype.getAriaRole = function() {
111 return this.ariaRole_;
112 };
113
114
115 /**
116 * Enables or disables the tab index of the element. Only elements with a
117 * valid tab index can receive focus.
118 * @param {Element} element Element whose tab index is to be changed.
119 * @param {boolean} enable Whether to add or remove the element's tab index.
120 */
121 goog.ui.ContainerRenderer.prototype.enableTabIndex = function(element, enable) {
122 if (element) {
123 element.tabIndex = enable ? 0 : -1;
124 }
125 };
126
127
128 /**
129 * Creates and returns the container's root element. The default
130 * simply creates a DIV and applies the renderer's own CSS class name to it.
131 * To be overridden in subclasses.
132 * @param {goog.ui.Container} container Container to render.
133 * @return {Element} Root element for the container.
134 */
135 goog.ui.ContainerRenderer.prototype.createDom = function(container) {
136 return container.getDomHelper().createDom(
137 goog.dom.TagName.DIV, this.getClassNames(container).join(' '));
138 };
139
140
141 /**
142 * Returns the DOM element into which child components are to be rendered,
143 * or null if the container hasn't been rendered yet.
144 * @param {Element} element Root element of the container whose content element
145 * is to be returned.
146 * @return {Element} Element to contain child elements (null if none).
147 */
148 goog.ui.ContainerRenderer.prototype.getContentElement = function(element) {
149 return element;
150 };
151
152
153 /**
154 * Default implementation of {@code canDecorate}; returns true if the element
155 * is a DIV, false otherwise.
156 * @param {Element} element Element to decorate.
157 * @return {boolean} Whether the renderer can decorate the element.
158 */
159 goog.ui.ContainerRenderer.prototype.canDecorate = function(element) {
160 return element.tagName == 'DIV';
161 };
162
163
164 /**
165 * Default implementation of {@code decorate} for {@link goog.ui.Container}s.
166 * Decorates the element with the container, and attempts to decorate its child
167 * elements. Returns the decorated element.
168 * @param {goog.ui.Container} container Container to decorate the element.
169 * @param {Element} element Element to decorate.
170 * @return {!Element} Decorated element.
171 */
172 goog.ui.ContainerRenderer.prototype.decorate = function(container, element) {
173 // Set the container's ID to the decorated element's DOM ID, if any.
174 if (element.id) {
175 container.setId(element.id);
176 }
177
178 // Configure the container's state based on the CSS class names it has.
179 var baseClass = this.getCssClass();
180 var hasBaseClass = false;
181 var classNames = goog.dom.classlist.get(element);
182 if (classNames) {
183 goog.array.forEach(classNames, function(className) {
184 if (className == baseClass) {
185 hasBaseClass = true;
186 } else if (className) {
187 this.setStateFromClassName(container, className, baseClass);
188 }
189 }, this);
190 }
191
192 if (!hasBaseClass) {
193 // Make sure the container's root element has the renderer's own CSS class.
194 goog.dom.classlist.add(element, baseClass);
195 }
196
197 // Decorate the element's children, if applicable. This should happen after
198 // the container's own state has been initialized, since how children are
199 // decorated may depend on the state of the container.
200 this.decorateChildren(container, this.getContentElement(element));
201
202 return element;
203 };
204
205
206 /**
207 * Sets the container's state based on the given CSS class name, encountered
208 * during decoration. CSS class names that don't represent container states
209 * are ignored. Considered protected; subclasses should override this method
210 * to support more states and CSS class names.
211 * @param {goog.ui.Container} container Container to update.
212 * @param {string} className CSS class name.
213 * @param {string} baseClass Base class name used as the root of state-specific
214 * class names (typically the renderer's own class name).
215 * @protected
216 * @suppress {missingRequire} goog.ui.Container
217 */
218 goog.ui.ContainerRenderer.prototype.setStateFromClassName = function(
219 container, className, baseClass) {
220 if (className == goog.getCssName(baseClass, 'disabled')) {
221 container.setEnabled(false);
222 } else if (className == goog.getCssName(baseClass, 'horizontal')) {
223 container.setOrientation(goog.ui.Container.Orientation.HORIZONTAL);
224 } else if (className == goog.getCssName(baseClass, 'vertical')) {
225 container.setOrientation(goog.ui.Container.Orientation.VERTICAL);
226 }
227 };
228
229
230 /**
231 * Takes a container and an element that may contain child elements, decorates
232 * the child elements, and adds the corresponding components to the container
233 * as child components. Any non-element child nodes (e.g. empty text nodes
234 * introduced by line breaks in the HTML source) are removed from the element.
235 * @param {goog.ui.Container} container Container whose children are to be
236 * discovered.
237 * @param {Element} element Element whose children are to be decorated.
238 * @param {Element=} opt_firstChild the first child to be decorated.
239 */
240 goog.ui.ContainerRenderer.prototype.decorateChildren = function(
241 container, element, opt_firstChild) {
242 if (element) {
243 var node = opt_firstChild || element.firstChild, next;
244 // Tag soup HTML may result in a DOM where siblings have different parents.
245 while (node && node.parentNode == element) {
246 // Get the next sibling here, since the node may be replaced or removed.
247 next = node.nextSibling;
248 if (node.nodeType == goog.dom.NodeType.ELEMENT) {
249 // Decorate element node.
250 var child = this.getDecoratorForChild(/** @type {!Element} */ (node));
251 if (child) {
252 // addChild() may need to look at the element.
253 child.setElementInternal(/** @type {!Element} */ (node));
254 // If the container is disabled, mark the child disabled too. See
255 // bug 1263729. Note that this must precede the call to addChild().
256 if (!container.isEnabled()) {
257 child.setEnabled(false);
258 }
259 container.addChild(child);
260 child.decorate(/** @type {!Element} */ (node));
261 }
262 } else if (!node.nodeValue || goog.string.trim(node.nodeValue) == '') {
263 // Remove empty text node, otherwise madness ensues (e.g. controls that
264 // use goog-inline-block will flicker and shift on hover on Gecko).
265 element.removeChild(node);
266 }
267 node = next;
268 }
269 }
270 };
271
272
273 /**
274 * Inspects the element, and creates an instance of {@link goog.ui.Control} or
275 * an appropriate subclass best suited to decorate it. Returns the control (or
276 * null if no suitable class was found). This default implementation uses the
277 * element's CSS class to find the appropriate control class to instantiate.
278 * May be overridden in subclasses.
279 * @param {Element} element Element to decorate.
280 * @return {goog.ui.Control?} A new control suitable to decorate the element
281 * (null if none).
282 */
283 goog.ui.ContainerRenderer.prototype.getDecoratorForChild = function(element) {
284 return /** @type {goog.ui.Control} */ (
285 goog.ui.registry.getDecorator(element));
286 };
287
288
289 /**
290 * Initializes the container's DOM when the container enters the document.
291 * Called from {@link goog.ui.Container#enterDocument}.
292 * @param {goog.ui.Container} container Container whose DOM is to be initialized
293 * as it enters the document.
294 */
295 goog.ui.ContainerRenderer.prototype.initializeDom = function(container) {
296 var elem = container.getElement();
297 goog.asserts.assert(elem, 'The container DOM element cannot be null.');
298 // Make sure the container's element isn't selectable. On Gecko, recursively
299 // marking each child element unselectable is expensive and unnecessary, so
300 // only mark the root element unselectable.
301 goog.style.setUnselectable(elem, true, goog.userAgent.GECKO);
302
303 // IE doesn't support outline:none, so we have to use the hideFocus property.
304 if (goog.userAgent.IE) {
305 elem.hideFocus = true;
306 }
307
308 // Set the ARIA role.
309 var ariaRole = this.getAriaRole();
310 if (ariaRole) {
311 goog.a11y.aria.setRole(elem, ariaRole);
312 }
313 };
314
315
316 /**
317 * Returns the element within the container's DOM that should receive keyboard
318 * focus (null if none). The default implementation returns the container's
319 * root element.
320 * @param {goog.ui.Container} container Container whose key event target is
321 * to be returned.
322 * @return {Element} Key event target (null if none).
323 */
324 goog.ui.ContainerRenderer.prototype.getKeyEventTarget = function(container) {
325 return container.getElement();
326 };
327
328
329 /**
330 * Returns the CSS class to be applied to the root element of containers
331 * rendered using this renderer.
332 * @return {string} Renderer-specific CSS class.
333 */
334 goog.ui.ContainerRenderer.prototype.getCssClass = function() {
335 return goog.ui.ContainerRenderer.CSS_CLASS;
336 };
337
338
339 /**
340 * Returns all CSS class names applicable to the given container, based on its
341 * state. The array of class names returned includes the renderer's own CSS
342 * class, followed by a CSS class indicating the container's orientation,
343 * followed by any state-specific CSS classes.
344 * @param {goog.ui.Container} container Container whose CSS classes are to be
345 * returned.
346 * @return {!Array<string>} Array of CSS class names applicable to the
347 * container.
348 */
349 goog.ui.ContainerRenderer.prototype.getClassNames = function(container) {
350 var baseClass = this.getCssClass();
351 var isHorizontal =
352 container.getOrientation() == goog.ui.Container.Orientation.HORIZONTAL;
353 var classNames = [
354 baseClass, (isHorizontal ? goog.getCssName(baseClass, 'horizontal') :
355 goog.getCssName(baseClass, 'vertical'))
356 ];
357 if (!container.isEnabled()) {
358 classNames.push(goog.getCssName(baseClass, 'disabled'));
359 }
360 return classNames;
361 };
362
363
364 /**
365 * Returns the default orientation of containers rendered or decorated by this
366 * renderer. The base class implementation returns {@code VERTICAL}.
367 * @return {goog.ui.Container.Orientation} Default orientation for containers
368 * created or decorated by this renderer.
369 * @suppress {missingRequire} goog.ui.Container
370 */
371 goog.ui.ContainerRenderer.prototype.getDefaultOrientation = function() {
372 return goog.ui.Container.Orientation.VERTICAL;
373 };