Debian Codegraph @

closure-library/closure/goog/ui/media/mp3.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 a reusable mp3 UI component given a mp3 URL.
17 *
18 * goog.ui.media.Mp3 is actually a {@link goog.ui.ControlRenderer}, a stateless
19 * class - that could/should be used as a Singleton with the static method
20 * {@code goog.ui.media.Mp3.getInstance} -, that knows how to render Mp3s. It is
21 * designed to be used with a {@link goog.ui.Control}, which will actually
22 * control the media renderer and provide the {@link goog.ui.Component} base.
23 * This design guarantees that all different types of medias will behave alike
24 * but will look different.
25 *
26 * goog.ui.media.Mp3 expects mp3 urls on {@code goog.ui.Control.getModel} as
27 * data models, and render a flash object that will play that URL.
28 *
29 * Example of usage:
30 *
31 * <pre>
32 * goog.ui.media.Mp3.newControl('http://hostname/file.mp3').render();
33 * </pre>
34 *
35 * Mp3 medias currently support the following states:
36 *
37 * <ul>
38 * <li> {@link goog.ui.Component.State.DISABLED}: shows 'flash not available'
39 * <li> {@link goog.ui.Component.State.HOVER}: mouse cursor is over the mp3
40 * <li> {@link goog.ui.Component.State.SELECTED}: mp3 is playing
41 * </ul>
42 *
43 * Which can be accessed by
44 *
45 * <pre>
46 * mp3.setEnabled(true);
47 * mp3.setHighlighted(true);
48 * mp3.setSelected(true);
49 * </pre>
50 *
51 * Requires flash to actually work.
52 *
53 */
54
55 goog.provide('goog.ui.media.Mp3');
56
57 goog.require('goog.string');
58 goog.require('goog.ui.media.FlashObject');
59 goog.require('goog.ui.media.Media');
60 goog.require('goog.ui.media.MediaRenderer');
61
62
63
64 /**
65 * Subclasses a goog.ui.media.MediaRenderer to provide a Mp3 specific media
66 * renderer.
67 *
68 * This class knows how to parse mp3 URLs, and render the DOM structure
69 * of mp3 flash players. This class is meant to be used as a singleton static
70 * stateless class, that takes {@code goog.ui.media.Media} instances and renders
71 * it. It expects {@code goog.ui.media.Media.getModel} to return a well formed,
72 * previously checked, mp3 URL {@see goog.ui.media.PicasaAlbum.parseUrl},
73 * which is the data model this renderer will use to construct the DOM
74 * structure. {@see goog.ui.media.PicasaAlbum.newControl} for an example of
75 * constructing a control with this renderer.
76 *
77 * This design is patterned after http://go/closure_control_subclassing
78 *
79 * It uses {@link goog.ui.media.FlashObject} to embed the flash object.
80 *
81 * @constructor
82 * @extends {goog.ui.media.MediaRenderer}
83 * @final
84 */
85 goog.ui.media.Mp3 = function() {
86 goog.ui.media.MediaRenderer.call(this);
87 };
88 goog.inherits(goog.ui.media.Mp3, goog.ui.media.MediaRenderer);
89 goog.addSingletonGetter(goog.ui.media.Mp3);
90
91
92 /**
93 * Flash player arguments. We expect that {@code flashUrl_} will contain a flash
94 * movie that takes an audioUrl parameter on its URL, containing the URL of the
95 * mp3 to be played.
96 *
97 * @type {string}
98 * @private
99 */
100 goog.ui.media.Mp3.PLAYER_ARGUMENTS_ = 'audioUrl=%s';
101
102
103 /**
104 * Default CSS class to be applied to the root element of components rendered
105 * by this renderer.
106 *
107 * @type {string}
108 */
109 goog.ui.media.Mp3.CSS_CLASS = goog.getCssName('goog-ui-media-mp3');
110
111
112 /**
113 * Flash player URL. Uses Google Reader's mp3 flash player by default.
114 *
115 * @type {string}
116 * @private
117 */
118 goog.ui.media.Mp3.flashUrl_ =
119 'http://www.google.com/reader/ui/3523697345-audio-player.swf';
120
121
122 /**
123 * Regular expression to check if a given URL is a valid mp3 URL.
124 *
125 * Copied from http://go/markdownlite.js.
126
127 *
128 * NOTE(user): although it would be easier to use goog.string.endsWith('.mp3'),
129 * in the future, we want to provide media inlining, which is basically getting
130 * a text and replacing all mp3 references with an mp3 player, so it makes sense
131 * to share the same regular expression to match everything.
132 *
133 * @type {RegExp}
134 */
135 goog.ui.media.Mp3.MATCHER =
136 /(https?:\/\/[\w-%&\/.=:#\+~\(\)]+\.(mp3)+(\?[\w-%&\/.=:#\+~\(\)]+)?)/i;
137
138
139 /**
140 * A static convenient method to construct a goog.ui.media.Media control out of
141 * a mp3 URL. It checks the mp3 URL, sets it as the data model
142 * goog.ui.media.Mp3 renderer uses, sets the states supported by the renderer,
143 * and returns a Control that binds everything together. This is what you
144 * should be using for constructing Mp3 videos, except if you need more fine
145 * control over the configuration.
146 *
147 * @param {goog.ui.media.MediaModel} dataModel A media model that must contain
148 * an mp3 url on {@code dataModel.getUrl}.
149 * @param {goog.dom.DomHelper=} opt_domHelper Optional DOM helper, used for
150 * document interaction.
151 * @return {!goog.ui.media.Media} A goog.ui.Control subclass with the mp3
152 * renderer.
153 */
154 goog.ui.media.Mp3.newControl = function(dataModel, opt_domHelper) {
155 var control = new goog.ui.media.Media(
156 dataModel, goog.ui.media.Mp3.getInstance(), opt_domHelper);
157 // mp3 ui doesn't have a non selected view: it shows the mp3 player by
158 // default.
159 control.setSelected(true);
160 return control;
161 };
162
163
164 /**
165 * A static method that sets which flash URL this class should use. Use this if
166 * you want to host your own flash mp3 player.
167 *
168 * @param {string} flashUrl The URL of the flash mp3 player.
169 */
170 goog.ui.media.Mp3.setFlashUrl = function(flashUrl) {
171 goog.ui.media.Mp3.flashUrl_ = flashUrl;
172 };
173
174
175 /**
176 * A static method that builds a URL that will contain the flash player that
177 * will play the {@code mp3Url}.
178 *
179 * @param {string} mp3Url The URL of the mp3 music.
180 * @return {string} An URL of a flash player that will know how to play the
181 * given {@code mp3Url}.
182 */
183 goog.ui.media.Mp3.buildFlashUrl = function(mp3Url) {
184 var flashUrl = goog.ui.media.Mp3.flashUrl_ + '?' +
185 goog.string.subs(
186 goog.ui.media.Mp3.PLAYER_ARGUMENTS_, goog.string.urlEncode(mp3Url));
187 return flashUrl;
188 };
189
190
191 /**
192 * Creates the initial DOM structure of a mp3 video, which is basically a
193 * the flash object pointing to a flash mp3 player.
194 *
195 * @param {goog.ui.Control} c The media control.
196 * @return {!Element} A DOM structure that represents the control.
197 * @override
198 */
199 goog.ui.media.Mp3.prototype.createDom = function(c) {
200 var control = /** @type {goog.ui.media.Media} */ (c);
201 var div = goog.ui.media.Mp3.superClass_.createDom.call(this, control);
202
203 var dataModel =
204 /** @type {goog.ui.media.MediaModel} */ (control.getDataModel());
205 var flash = new goog.ui.media.FlashObject(
206 dataModel.getPlayer().getTrustedResourceUrl(), control.getDomHelper());
207 flash.setFlashVar('playerMode', 'embedded');
208 flash.render(div);
209
210 return div;
211 };
212
213
214 /**
215 * Returns the CSS class to be applied to the root element of components
216 * rendered using this renderer.
217 * @return {string} Renderer-specific CSS class.
218 * @override
219 */
220 goog.ui.media.Mp3.prototype.getCssClass = function() {
221 return goog.ui.media.Mp3.CSS_CLASS;
222 };