Debian Codegraph @

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

raw
1 // Copyright 2009 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 Provides the base goog.ui.Control and goog.ui.ControlRenderer
17 * for media types, as well as a media model consistent with the Yahoo Media RSS
18 * specification {@link http://search.yahoo.com/mrss/}.
19 *
20 * The goog.ui.media.* package is basically a set of goog.ui.ControlRenderers
21 * subclasses (such as goog.ui.media.Youtube, goog.ui.media.Picasa, etc) that
22 * should all work with the same goog.ui.Control (goog.ui.media.Media) logic.
23 *
24 * This design guarantees that all different types of medias will behave alike
25 * (in a base level) but will look different.
26 *
27 * In MVC terms, {@link goog.ui.media.Media} is the Controller,
28 * {@link goog.ui.media.MediaRenderer} + CSS definitions are the View and
29 * {@code goog.ui.media.MediaModel} is the data Model. Typically,
30 * MediaRenderer will be subclassed to provide media specific renderers.
31 * MediaRenderer subclasses are also responsible for defining the data model.
32 *
33 * This design is strongly patterned after:
34 * http://go/closure_control_subclassing
35 *
36 * goog.ui.media.MediaRenderer handles the basic common ways to display media,
37 * such as displaying tooltips, frames, minimize/maximize buttons, play buttons,
38 * etc. Its subclasses are responsible for rendering media specific DOM
39 * structures, like youtube flash players, picasa albums, etc.
40 *
41 * goog.ui.media.Media handles the Control of Medias, by listening to events
42 * and firing the appropriate actions. It knows about the existence of captions,
43 * minimize/maximize buttons, and takes all the actions needed to change states,
44 * including delegating the UI actions to MediaRenderers.
45 *
46 * Although MediaRenderer is a base class designed to be subclassed, it can
47 * be used by itself:
48 *
49 * <pre>
50 * var renderer = new goog.ui.media.MediaRenderer();
51 * var control = new goog.ui.media.Media('hello world', renderer);
52 * var control.render(goog.dom.getElement('mediaHolder'));
53 * </pre>
54 *
55 * It requires a few CSS rules to be defined, which you should use to control
56 * how the component is displayed. {@link goog.ui.ControlRenderer}s is very CSS
57 * intensive, which separates the UI structure (the HTML DOM elements, which is
58 * created by the {@code goog.ui.media.MediaRenderer}) from the UI view (which
59 * nodes are visible, which aren't, where they are positioned. These are defined
60 * on the CSS rules for each state). A few examples of CSS selectors that needs
61 * to be defined are:
62 *
63 * <ul>
64 * <li>.goog-ui-media
65 * <li>.goog-ui-media-hover
66 * <li>.goog-ui-media-selected
67 * </ul>
68 *
69 * If you want to have different custom renderers CSS namespaces (eg. you may
70 * want to show a small thumbnail, or you may want to hide the caption, etc),
71 * you can do so by using:
72 *
73 * <pre>
74 * var renderer = goog.ui.ControlRenderer.getCustomRenderer(
75 * goog.ui.media.MediaRenderer, 'my-custom-namespace');
76 * var media = new goog.ui.media.Media('', renderer);
77 * media.render(goog.dom.getElement('parent'));
78 * </pre>
79 *
80 * Which will allow you to set your own .my-custom-namespace-hover,
81 * .my-custom-namespace-selected CSS selectors.
82 *
83 * NOTE(user): it seems like an overkill to subclass goog.ui.Control instead of
84 * using a factory, but we wanted to make sure we had more control over the
85 * events for future media implementations. Since we intent to use it in many
86 * different places, it makes sense to have a more flexible design that lets us
87 * control the inner workings of goog.ui.Control.
88 *
89 * TODO(user): implement, as needed, the Media specific state changes UI, such
90 * as minimize/maximize buttons, expand/close buttons, etc.
91 *
92 */
93
94 goog.provide('goog.ui.media.Media');
95 goog.provide('goog.ui.media.MediaRenderer');
96
97 goog.require('goog.asserts');
98 goog.require('goog.dom.TagName');
99 goog.require('goog.style');
100 goog.require('goog.ui.Component');
101 goog.require('goog.ui.Control');
102 goog.require('goog.ui.ControlRenderer');
103
104
105
106 /**
107 * Provides the control mechanism of media types.
108 *
109 * @param {goog.ui.media.MediaModel} dataModel The data model to be used by the
110 * renderer.
111 * @param {goog.ui.ControlRenderer=} opt_renderer Renderer used to render or
112 * decorate the component; defaults to {@link goog.ui.ControlRenderer}.
113 * @param {goog.dom.DomHelper=} opt_domHelper Optional DOM helper, used for
114 * document interaction.
115 * @constructor
116 * @extends {goog.ui.Control}
117 * @final
118 */
119 goog.ui.media.Media = function(dataModel, opt_renderer, opt_domHelper) {
120 goog.ui.Control.call(this, null, opt_renderer, opt_domHelper);
121
122 // Sets up the data model.
123 this.setDataModel(dataModel);
124 this.setSupportedState(goog.ui.Component.State.OPENED, true);
125 this.setSupportedState(goog.ui.Component.State.SELECTED, true);
126 // TODO(user): had to do this to for mouseDownHandler not to
127 // e.preventDefault(), because it was not allowing the event to reach the
128 // flash player. figure out a better way to not e.preventDefault().
129 this.setAllowTextSelection(true);
130
131 // Media items don't use RTL styles, so avoid accessing computed styles to
132 // figure out if the control is RTL.
133 this.setRightToLeft(false);
134 };
135 goog.inherits(goog.ui.media.Media, goog.ui.Control);
136
137
138 /**
139 * The media data model used on the renderer.
140 *
141 * @type {goog.ui.media.MediaModel}
142 * @private
143 */
144 goog.ui.media.Media.prototype.dataModel_;
145
146
147 /**
148 * Sets the media model to be used on the renderer.
149 * @param {goog.ui.media.MediaModel} dataModel The media model the renderer
150 * should use.
151 */
152 goog.ui.media.Media.prototype.setDataModel = function(dataModel) {
153 this.dataModel_ = dataModel;
154 };
155
156
157 /**
158 * Gets the media model renderer is using.
159 * @return {goog.ui.media.MediaModel} The media model being used.
160 */
161 goog.ui.media.Media.prototype.getDataModel = function() {
162 return this.dataModel_;
163 };
164
165
166
167 /**
168 * Base class of all media renderers. Provides the common renderer functionality
169 * of medias.
170 *
171 * The current common functionality shared by Medias is to have an outer frame
172 * that gets highlighted on mouse hover.
173 *
174 * TODO(user): implement more common UI behavior, as needed.
175 *
176 * NOTE(user): I am not enjoying how the subclasses are changing their state
177 * through setState() ... maybe provide abstract methods like
178 * goog.ui.media.MediaRenderer.prototype.preview = goog.abstractMethod;
179 * goog.ui.media.MediaRenderer.prototype.play = goog.abstractMethod;
180 * goog.ui.media.MediaRenderer.prototype.minimize = goog.abstractMethod;
181 * goog.ui.media.MediaRenderer.prototype.maximize = goog.abstractMethod;
182 * and call them on this parent class setState ?
183 *
184 * @constructor
185 * @extends {goog.ui.ControlRenderer}
186 */
187 goog.ui.media.MediaRenderer = function() {
188 goog.ui.ControlRenderer.call(this);
189 };
190 goog.inherits(goog.ui.media.MediaRenderer, goog.ui.ControlRenderer);
191
192
193 /**
194 * Builds the common DOM structure of medias. Builds an outer div, and appends
195 * a child div with the {@code goog.ui.Control.getContent} content. Marks the
196 * caption with a {@code this.getClassClass()} + '-caption' css flag, so that
197 * specific renderers can hide/show the caption as desired.
198 *
199 * @param {goog.ui.Control} control The control instance.
200 * @return {!Element} The DOM structure that represents control.
201 * @override
202 */
203 goog.ui.media.MediaRenderer.prototype.createDom = function(control) {
204 goog.asserts.assertInstanceof(control, goog.ui.media.Media);
205 var domHelper = control.getDomHelper();
206 var div = domHelper.createElement(goog.dom.TagName.DIV);
207 div.className = this.getClassNames(control).join(' ');
208
209 var dataModel = control.getDataModel();
210
211 // Only creates DOMs if the data is available.
212 if (dataModel.getCaption()) {
213 var caption = domHelper.createElement(goog.dom.TagName.DIV);
214 caption.className = goog.getCssName(this.getCssClass(), 'caption');
215 caption.appendChild(
216 domHelper.createDom(
217 goog.dom.TagName.P,
218 goog.getCssName(this.getCssClass(), 'caption-text'),
219 dataModel.getCaption()));
220 domHelper.appendChild(div, caption);
221 }
222
223 if (dataModel.getDescription()) {
224 var description = domHelper.createElement(goog.dom.TagName.DIV);
225 description.className = goog.getCssName(this.getCssClass(), 'description');
226 description.appendChild(
227 domHelper.createDom(
228 goog.dom.TagName.P,
229 goog.getCssName(this.getCssClass(), 'description-text'),
230 dataModel.getDescription()));
231 domHelper.appendChild(div, description);
232 }
233
234 // Creates thumbnails of the media.
235 var thumbnails = dataModel.getThumbnails() || [];
236 for (var index = 0; index < thumbnails.length; index++) {
237 var thumbnail = thumbnails[index];
238 var thumbnailElement = domHelper.createElement(goog.dom.TagName.IMG);
239 thumbnailElement.src = thumbnail.getUrl();
240 thumbnailElement.className = this.getThumbnailCssName(index);
241
242 // Check that the size is defined and that the size's height and width
243 // are defined. Undefined height and width is deprecated but still
244 // seems to exist in some cases.
245 var size = thumbnail.getSize();
246
247 if (size && goog.isDefAndNotNull(size.height) &&
248 goog.isDefAndNotNull(size.width)) {
249 goog.style.setSize(thumbnailElement, size);
250 }
251 domHelper.appendChild(div, thumbnailElement);
252 }
253
254 if (dataModel.getPlayer()) {
255 // if medias have players, allow UI for a play button.
256 var playButton = domHelper.createElement(goog.dom.TagName.DIV);
257 playButton.className = goog.getCssName(this.getCssClass(), 'playbutton');
258 domHelper.appendChild(div, playButton);
259 }
260
261 control.setElementInternal(div);
262
263 this.setState(
264 control,
265 /** @type {goog.ui.Component.State} */ (control.getState()), true);
266
267 return div;
268 };
269
270
271 /**
272 * Returns a renamable CSS class name for a numbered thumbnail. The default
273 * implementation generates the class names goog-ui-media-thumbnail0,
274 * goog-ui-media-thumbnail1, and the generic goog-ui-media-thumbnailn.
275 * Subclasses can override this method when their media requires additional
276 * specific class names (Applications are supposed to know how many thumbnails
277 * media will have).
278 *
279 * @param {number} index The thumbnail index.
280 * @return {string} CSS class name.
281 * @protected
282 */
283 goog.ui.media.MediaRenderer.prototype.getThumbnailCssName = function(index) {
284 switch (index) {
285 case 0:
286 return goog.getCssName(this.getCssClass(), 'thumbnail0');
287 case 1:
288 return goog.getCssName(this.getCssClass(), 'thumbnail1');
289 case 2:
290 return goog.getCssName(this.getCssClass(), 'thumbnail2');
291 case 3:
292 return goog.getCssName(this.getCssClass(), 'thumbnail3');
293 case 4:
294 return goog.getCssName(this.getCssClass(), 'thumbnail4');
295 default:
296 return goog.getCssName(this.getCssClass(), 'thumbnailn');
297 }
298 };