Debian Codegraph @

closure-library/closure/goog/soy/renderer.js

raw
1 // Copyright 2010 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 soy renderer that allows registration of
17 * injected data ("globals") that will be passed into the rendered
18 * templates.
19 *
20 * There is also an interface {@link goog.soy.InjectedDataSupplier} that
21 * user should implement to provide the injected data for a specific
22 * application. The injected data format is a JavaScript object:
23 * <pre>
24 * {'dataKey': 'value', 'otherDataKey': 'otherValue'}
25 * </pre>
26 *
27 * The injected data can then be referred to in any soy templates as
28 * part of a magic "ij" parameter. For example, {@code $ij.dataKey}
29 * will evaluate to 'value' with the above injected data.
30 *
31 * @author [email protected] (Henry Wong)
32 * @author [email protected] (Chris Henry)
33 */
34
35 goog.provide('goog.soy.InjectedDataSupplier');
36 goog.provide('goog.soy.Renderer');
37
38 goog.require('goog.asserts');
39 goog.require('goog.dom');
40 goog.require('goog.soy');
41 goog.require('goog.soy.data.SanitizedContent');
42 goog.require('goog.soy.data.SanitizedContentKind');
43
44
45
46 /**
47 * Creates a new soy renderer. Note that the renderer will only be
48 * guaranteed to work correctly within the document scope provided in
49 * the DOM helper.
50 *
51 * @param {goog.soy.InjectedDataSupplier=} opt_injectedDataSupplier A supplier
52 * that provides an injected data.
53 * @param {goog.dom.DomHelper=} opt_domHelper Optional DOM helper;
54 * defaults to that provided by {@code goog.dom.getDomHelper()}.
55 * @constructor
56 */
57 goog.soy.Renderer = function(opt_injectedDataSupplier, opt_domHelper) {
58 /**
59 * @const {!goog.dom.DomHelper}
60 * @private
61 */
62 this.dom_ = opt_domHelper || goog.dom.getDomHelper();
63
64 /**
65 * @const {?goog.soy.InjectedDataSupplier}
66 * @private
67 */
68 this.supplier_ = opt_injectedDataSupplier || null;
69 };
70
71
72 /**
73 * Renders a Soy template into a single node or a document fragment.
74 * Delegates to {@code goog.soy.renderAsFragment}.
75 *
76 * @param {?function(ARG_TYPES, Object<string, *>=):*|
77 * ?function(ARG_TYPES, null=, Object<string, *>=):*} template
78 * The Soy template defining the element's content.
79 * @param {ARG_TYPES=} opt_templateData The data for the template.
80 * @return {!Node} The resulting node or document fragment.
81 * @template ARG_TYPES
82 */
83 goog.soy.Renderer.prototype.renderAsFragment = function(
84 template, opt_templateData) {
85 var node = goog.soy.renderAsFragment(
86 template, opt_templateData, this.getInjectedData_(), this.dom_);
87 this.handleRender(node);
88 return node;
89 };
90
91
92 /**
93 * Renders a Soy template into a single node. If the rendered HTML
94 * string represents a single node, then that node is returned.
95 * Otherwise, a DIV element is returned containing the rendered nodes.
96 * Delegates to {@code goog.soy.renderAsElement}.
97 *
98 * @param {?function(ARG_TYPES, Object<string, *>=):*|
99 * ?function(ARG_TYPES, null=, Object<string, *>=):*} template
100 * The Soy template defining the element's content.
101 * @param {ARG_TYPES=} opt_templateData The data for the template.
102 * @return {!Element} Rendered template contents, wrapped in a parent DIV
103 * element if necessary.
104 * @template ARG_TYPES
105 */
106 goog.soy.Renderer.prototype.renderAsElement = function(
107 template, opt_templateData) {
108 var element = goog.soy.renderAsElement(
109 template, opt_templateData, this.getInjectedData_(), this.dom_);
110 this.handleRender(element);
111 return element;
112 };
113
114
115 /**
116 * Renders a Soy template and then set the output string as the
117 * innerHTML of the given element. Delegates to {@code goog.soy.renderElement}.
118 *
119 * @param {Element} element The element whose content we are rendering.
120 * @param {?function(ARG_TYPES, Object<string, *>=):*|
121 * ?function(ARG_TYPES, null=, Object<string, *>=):*} template
122 * The Soy template defining the element's content.
123 * @param {ARG_TYPES=} opt_templateData The data for the template.
124 * @template ARG_TYPES
125 */
126 goog.soy.Renderer.prototype.renderElement = function(
127 element, template, opt_templateData) {
128 goog.soy.renderElement(
129 element, template, opt_templateData, this.getInjectedData_());
130 this.handleRender(element);
131 };
132
133
134 /**
135 * Renders a Soy template and returns the output string.
136 * If the template is strict, it must be of kind HTML. To render strict
137 * templates of other kinds, use {@code renderText} (for {@code kind="text"}) or
138 * {@code renderStrictOfKind}.
139 *
140 * @param {?function(ARG_TYPES, Object<string, *>=):*|
141 * ?function(ARG_TYPES, null=, Object<string, *>=):*} template
142 * The Soy template to render.
143 * @param {ARG_TYPES=} opt_templateData The data for the template.
144 * @return {string} The return value of rendering the template directly.
145 * @template ARG_TYPES
146 */
147 goog.soy.Renderer.prototype.render = function(template, opt_templateData) {
148 var result =
149 template(opt_templateData || {}, undefined, this.getInjectedData_());
150 goog.asserts.assert(
151 !(result instanceof goog.soy.data.SanitizedContent) ||
152 result.contentKind === goog.soy.data.SanitizedContentKind.HTML,
153 'render was called with a strict template of kind other than "html"' +
154 ' (consider using renderText or renderStrict)');
155 this.handleRender();
156 return String(result);
157 };
158
159
160 /**
161 * Renders a strict Soy template of kind="text" and returns the output string.
162 * It is an error to use renderText on non-strict templates, or strict templates
163 * of kinds other than "text".
164 *
165 * @param {?function(ARG_TYPES, Object<string, *>=):?goog.soy.data.UnsanitizedText|
166 * ?function(ARG_TYPES, null=, Object<string, *>=):
167 * ?goog.soy.data.UnsanitizedText} template The Soy template to render.
168 * @param {ARG_TYPES=} opt_templateData The data for the template.
169 * @return {string} The return value of rendering the template directly.
170 * @template ARG_TYPES
171 */
172 goog.soy.Renderer.prototype.renderText = function(template, opt_templateData) {
173 var result =
174 template(opt_templateData || {}, undefined, this.getInjectedData_());
175 goog.asserts.assertInstanceof(
176 result, goog.soy.data.SanitizedContent,
177 'renderText cannot be called on a non-strict soy template');
178 goog.asserts.assert(
179 result.contentKind === goog.soy.data.SanitizedContentKind.TEXT,
180 'renderText was called with a template of kind other than "text"');
181 this.handleRender();
182 return String(result);
183 };
184
185
186 /**
187 * Renders a strict Soy HTML template and returns the output SanitizedHtml
188 * object.
189 * @param {?function(ARG_TYPES, Object<string, *>=):!goog.soy.data.SanitizedHtml|
190 * ?function(ARG_TYPES, null=, Object<string, *>=):
191 * !goog.soy.data.SanitizedHtml} template The Soy template to render.
192 * @param {ARG_TYPES=} opt_templateData The data for the template.
193 * @return {!goog.soy.data.SanitizedHtml}
194 * @template ARG_TYPES
195 */
196 goog.soy.Renderer.prototype.renderStrict = function(
197 template, opt_templateData) {
198 return this.renderStrictOfKind(
199 template, opt_templateData, goog.soy.data.SanitizedContentKind.HTML);
200 };
201
202
203 /**
204 * Renders a strict Soy template and returns the output SanitizedUri object.
205 *
206 * @param {!function(ARG_TYPES, ?Object<string, *>=):!goog.soy.data.SanitizedUri|
207 * !function(ARG_TYPES, null=, ?Object<string, *>=):
208 * !goog.soy.data.SanitizedUri} template The Soy template to render.
209 * @param {ARG_TYPES=} opt_templateData The data for the template.
210 * @return {!goog.soy.data.SanitizedUri}
211 * @template ARG_TYPES
212 */
213 goog.soy.Renderer.prototype.renderStrictUri = function(
214 template, opt_templateData) {
215 return this.renderStrictOfKind(
216 template, opt_templateData, goog.soy.data.SanitizedContentKind.URI);
217 };
218
219
220 /**
221 * Renders a strict Soy template and returns the output SanitizedContent object.
222 *
223 * @param {?function(ARG_TYPES, ?Object<string, *>=): RETURN_TYPE|
224 * ?function(ARG_TYPES, null=, ?Object<string, *>=): RETURN_TYPE}
225 * template The Soy template to render.
226 * @param {ARG_TYPES=} opt_templateData The data for the template.
227 * @param {goog.soy.data.SanitizedContentKind=} opt_kind The output kind to
228 * assert. If null, the template must be of kind="html" (i.e., opt_kind
229 * defaults to goog.soy.data.SanitizedContentKind.HTML).
230 * @return {RETURN_TYPE} The SanitizedContent object. This return type is
231 * generic based on the return type of the template, such as
232 * goog.soy.data.SanitizedHtml.
233 * @template ARG_TYPES, RETURN_TYPE
234 */
235 goog.soy.Renderer.prototype.renderStrictOfKind = function(
236 template, opt_templateData, opt_kind) {
237 var result =
238 template(opt_templateData || {}, undefined, this.getInjectedData_());
239 goog.asserts.assertInstanceof(
240 result, goog.soy.data.SanitizedContent,
241 'renderStrict cannot be called on a non-strict soy template');
242 goog.asserts.assert(
243 result.contentKind ===
244 (opt_kind || goog.soy.data.SanitizedContentKind.HTML),
245 'renderStrict was called with the wrong kind of template');
246 this.handleRender();
247 return result;
248 };
249
250
251 /**
252 * Renders a strict Soy template of kind="html" and returns the result as
253 * a goog.html.SafeHtml object.
254 *
255 * Rendering a template that is not a strict template of kind="html" results in
256 * a runtime error.
257 *
258 * @param {?function(ARG_TYPES, Object<string, *>=): !goog.soy.data.SanitizedHtml|
259 * ?function(ARG_TYPES, null=, Object<string, *>=):
260 * !goog.soy.data.SanitizedHtml} template The Soy template to render.
261 * @param {ARG_TYPES=} opt_templateData The data for the template.
262 * @return {!goog.html.SafeHtml}
263 * @template ARG_TYPES
264 */
265 goog.soy.Renderer.prototype.renderSafeHtml = function(
266 template, opt_templateData) {
267 var result = this.renderStrict(template, opt_templateData);
268 // Convert from SanitizedHtml to SafeHtml.
269 return result.toSafeHtml();
270 };
271
272
273 /**
274 * Renders a strict Soy template of kind="css" and returns the result as
275 * a goog.html.SafeStyleSheet object.
276 *
277 * Rendering a template that is not a strict template of kind="css" results in
278 * a runtime and compile-time error.
279 *
280 * @param {?function(ARG_TYPES, Object<string, *>=): !goog.soy.data.SanitizedCss|
281 * ?function(ARG_TYPES, null=, Object<string, *>=):
282 * !goog.soy.data.SanitizedCss} template The Soy template to render.
283 * @param {ARG_TYPES=} opt_templateData The data for the template.
284 * @return {!goog.html.SafeStyleSheet}
285 * @template ARG_TYPES
286 */
287 goog.soy.Renderer.prototype.renderSafeStyleSheet = function(
288 template, opt_templateData) {
289 var result = this.renderStrictOfKind(
290 template, opt_templateData, goog.soy.data.SanitizedContentKind.CSS);
291 return result.toSafeStyleSheet();
292 };
293
294
295 /**
296 * @return {!goog.dom.DomHelper}
297 * @protected
298 */
299 goog.soy.Renderer.prototype.getDom = function() {
300 return this.dom_;
301 };
302
303
304 /**
305 * Observes rendering of templates by this renderer.
306 * @param {Node=} opt_node Relevant node, if available. The node may or may
307 * not be in the document, depending on whether Soy is creating an element
308 * or writing into an existing one.
309 * @protected
310 */
311 goog.soy.Renderer.prototype.handleRender = goog.nullFunction;
312
313
314 /**
315 * Creates the injectedParams map if necessary and calls the configuration
316 * service to prepopulate it.
317 * @return {Object} The injected params.
318 * @private
319 */
320 goog.soy.Renderer.prototype.getInjectedData_ = function() {
321 return this.supplier_ ? this.supplier_.getData() : {};
322 };
323
324
325
326 /**
327 * An interface for a supplier that provides Soy injected data.
328 * @interface
329 */
330 goog.soy.InjectedDataSupplier = function() {};
331
332
333 /**
334 * Gets the injected data. Implementation may assume that
335 * {@code goog.soy.Renderer} will treat the returned data as
336 * immutable. The renderer will call this every time one of its
337 * {@code render*} methods is called.
338 * @return {Object} A key-value pair representing the injected data.
339 */
340 goog.soy.InjectedDataSupplier.prototype.getData = function() {};