* The top portion of this file contains utilities for Soy users:
* The bottom portion of this file contains utilities that should only be called
* by Soy-generated JS code. Please do not use these functions directly from
* your hand-writen code. Their names all start with '$$'.
*
* @author Mike Samuel
* @author Kai Huang
* @author Aharon Lenin
*/
goog.provide('soy');
goog.provide('soy.StringBuilder');
goog.provide('soy.esc');
goog.require('goog.asserts');
goog.require('goog.dom.DomHelper');
goog.require('goog.format');
goog.require('goog.i18n.BidiFormatter');
goog.require('goog.i18n.bidi');
goog.require('goog.soy');
goog.require('goog.string');
goog.require('goog.string.StringBuffer');
goog.require('soydata');
// -----------------------------------------------------------------------------
// StringBuilder (compatible with the 'stringbuilder' code style).
/**
* Utility class to facilitate much faster string concatenation in IE,
* using Array.join() rather than the '+' operator. For other browsers
* we simply use the '+' operator.
*
* @param {Object} var_args Initial items to append,
* e.g., new soy.StringBuilder('foo', 'bar').
* @constructor
*/
soy.StringBuilder = goog.string.StringBuffer;
// -----------------------------------------------------------------------------
// Public utilities.
/**
* Helper function to render a Soy template and then set the output string as
* the innerHTML of an element. It is recommended to use this helper function
* instead of directly setting innerHTML in your hand-written code, so that it
* will be easier to audit the code for cross-site scripting vulnerabilities.
*
* NOTE: New code should consider using goog.soy.renderElement instead.
*
* @param {Element} element The element whose content we are rendering.
* @param {Function} template The Soy template defining the element's content.
* @param {Object=} opt_templateData The data for the template.
* @param {Object=} opt_injectedData The injected data for the template.
*/
soy.renderElement = goog.soy.renderElement;
/**
* Helper function to render a Soy template into a single node or a document
* fragment. If the rendered HTML string represents a single node, then that
* node is returned (note that this is *not* a fragment, despite them name of
* the method). Otherwise a document fragment is returned containing the
* rendered nodes.
*
* NOTE: New code should consider using goog.soy.renderAsFragment
* instead (note that the arguments are different).
*
* @param {Function} template The Soy template defining the element's content.
* @param {Object=} opt_templateData The data for the template.
* @param {Document=} opt_document The document used to create DOM nodes. If not
* specified, global document object is used.
* @param {Object=} opt_injectedData The injected data for the template.
* @return {!Node} The resulting node or document fragment.
*/
soy.renderAsFragment = function(
template, opt_templateData, opt_document, opt_injectedData) {
return goog.soy.renderAsFragment(
template, opt_templateData, opt_injectedData,
new goog.dom.DomHelper(opt_document));
};
/**
* Helper function to render a Soy template into a single node. If the rendered
* HTML string represents a single node, then that node is returned. Otherwise,
* a DIV element is returned containing the rendered nodes.
*
* NOTE: New code should consider using goog.soy.renderAsElement
* instead (note that the arguments are different).
*
* @param {Function} template The Soy template defining the element's content.
* @param {Object=} opt_templateData The data for the template.
* @param {Document=} opt_document The document used to create DOM nodes. If not
* specified, global document object is used.
* @param {Object=} opt_injectedData The injected data for the template.
* @return {!Element} Rendered template contents, wrapped in a parent DIV
* element if necessary.
*/
soy.renderAsElement = function(
template, opt_templateData, opt_document, opt_injectedData) {
return goog.soy.renderAsElement(
template, opt_templateData, opt_injectedData,
new goog.dom.DomHelper(opt_document));
};
// -----------------------------------------------------------------------------
// Below are private utilities to be used by Soy-generated code only.
/**
* Builds an augmented data object to be passed when a template calls another,
* and needs to pass both original data and additional params. The returned
* object will contain both the original data and the additional params. If the
* same key appears in both, then the value from the additional params will be
* visible, while the value from the original data will be hidden. The original
* data object will be used, but not modified.
*
* @param {!Object} origData The original data to pass.
* @param {Object} additionalParams The additional params to pass.
* @return {Object} An augmented data object containing both the original data
* and the additional params.
*/
soy.$$augmentData = function(origData, additionalParams) {
// Create a new object whose '__proto__' field is set to origData.
/** @constructor */
function TempCtor() {}
TempCtor.prototype = origData;
var newData = new TempCtor();
// Add the additional params to the new object.
for (var key in additionalParams) {
newData[key] = additionalParams[key];
}
return newData;
};
/**
* Gets the keys in a map as an array. There are no guarantees on the order.
* @param {Object} map The map to get the keys of.
* @return {Array. Important: This function must always be called with a string constant.
*
* If Closure Compiler is not being used, then this is just this identity
* function. If Closure Compiler is being used, then each call to this function
* will be replaced with a short string constant, which will be consistent per
* input name.
*
* @param {string} delTemplateName The delegate template name for which to get a
* consistent unique id.
* @return {string} A unique id that is consistent per input name.
*
* @consistentIdGenerator
*/
soy.$$getDelegateId = function(delTemplateName) {
return delTemplateName;
};
/**
* Map from registered delegate template id/name to the priority of the
* implementation.
* @type {Object}
* @private
*/
soy.$$DELEGATE_REGISTRY_PRIORITIES_ = {};
/**
* Map from registered delegate template id/name to the implementation function.
* @type {Object}
* @private
*/
soy.$$DELEGATE_REGISTRY_FUNCTIONS_ = {};
/**
* Registers a delegate implementation. If the same delegate template id/name
* has been registered previously, then priority values are compared and only
* the higher priority implementation is stored (if priorities are equal, an
* error is thrown).
*
* @param {string} delTemplateId The delegate template id/name to register.
* @param {number} delPriority The implementation's priority value.
* @param {Function} delFn The implementation function.
*/
soy.$$registerDelegateFn = function(delTemplateId, delPriority, delFn) {
var mapKey = 'key_' + delTemplateId;
var currPriority = soy.$$DELEGATE_REGISTRY_PRIORITIES_[mapKey];
if (currPriority === undefined || delPriority > currPriority) {
// Registering new or higher-priority function: replace registry entry.
soy.$$DELEGATE_REGISTRY_PRIORITIES_[mapKey] = delPriority;
soy.$$DELEGATE_REGISTRY_FUNCTIONS_[mapKey] = delFn;
} else if (delPriority == currPriority) {
// Registering same-priority function: error.
throw Error(
'Encountered two active delegates with same priority (id/name "' +
delTemplateId + '").');
} else {
// Registering lower-priority function: do nothing.
}
};
/**
* Retrieves the (highest-priority) implementation that has been registered for
* a given delegate template id/name. If no implementation has been registered
* for the id/name, then returns an implementation that is equivalent to an
* empty template (i.e. rendered output would be empty string).
*
* @param {string} delTemplateId The delegate template id/name to get.
* @return {Function} The retrieved implementation function.
*/
soy.$$getDelegateFn = function(delTemplateId) {
var delFn = soy.$$DELEGATE_REGISTRY_FUNCTIONS_['key_' + delTemplateId];
return delFn ? delFn : soy.$$EMPTY_TEMPLATE_FN_;
};
/**
* Private helper soy.$$getDelegateFn(). This is the empty template function
* that is returned whenever there's no delegate implementation found.
*
* @param {Object.
* Escapes HTML special characters so that the value will not prematurely end
* the body of a tag like {@code }.
*
* Will normalize known safe HTML to make sure that sanitized HTML (which could
* contain an innocuous {@code } don't prematurely end an RCDATA
* element.
*
* @param {*} value The string-like value to be escaped. May not be a string,
* but the value will be coerced to a string.
* @return {string} An escaped version of value.
*/
soy.$$escapeHtmlRcdata = function(value) {
if (typeof value === 'object' && value &&
value.contentKind === soydata.SanitizedContentKind.HTML) {
return soy.esc.$$normalizeHtmlHelper(value.content);
}
return soy.esc.$$escapeHtmlHelper(value);
};
/**
* Removes HTML tags from a string of known safe HTML so it can be used as an
* attribute value.
*
* @param {*} value The HTML to be escaped. May not be a string, but the
* value will be coerced to a string.
* @return {string} A representation of value without tags, HTML comments, or
* other content.
*/
soy.$$stripHtmlTags = function(value) {
return String(value).replace(soy.esc.$$HTML_TAG_REGEX_, '');
};
/**
* Escapes HTML special characters in an HTML attribute value.
*
* @param {*} value The HTML to be escaped. May not be a string, but the
* value will be coerced to a string.
* @return {string} An escaped version of value.
*/
soy.$$escapeHtmlAttribute = function(value) {
if (typeof value === 'object' && value &&
value.contentKind === soydata.SanitizedContentKind.HTML) {
return soy.esc.$$normalizeHtmlHelper(soy.$$stripHtmlTags(value.content));
}
return soy.esc.$$escapeHtmlHelper(value);
};
/**
* Escapes HTML special characters in a string including space and other
* characters that can end an unquoted HTML attribute value.
*
* @param {*} value The HTML to be escaped. May not be a string, but the
* value will be coerced to a string.
* @return {string} An escaped version of value.
*/
soy.$$escapeHtmlAttributeNospace = function(value) {
if (typeof value === 'object' && value &&
value.contentKind === soydata.SanitizedContentKind.HTML) {
return soy.esc.$$normalizeHtmlNospaceHelper(
soy.$$stripHtmlTags(value.content));
}
return soy.esc.$$escapeHtmlNospaceHelper(value);
};
/**
* Filters out strings that cannot be a substring of a valid HTML attribute.
*
* @param {*} value The value to escape. May not be a string, but the value
* will be coerced to a string.
* @return {string} A valid HTML attribute name part or name/value pair.
* {@code "zSoyz"} if the input is invalid.
*/
soy.$$filterHtmlAttribute = function(value) {
if (typeof value === 'object' && value &&
value.contentKind === soydata.SanitizedContentKind.HTML_ATTRIBUTE) {
return value.content.replace(/=([^"']*)$/, '="$1"');
}
return soy.esc.$$filterHtmlAttributeHelper(value);
};
/**
* Filters out strings that cannot be a substring of a valid HTML element name.
*
* @param {*} value The value to escape. May not be a string, but the value
* will be coerced to a string.
* @return {string} A valid HTML element name part.
* {@code "zSoyz"} if the input is invalid.
*/
soy.$$filterHtmlElementName = function(value) {
return soy.esc.$$filterHtmlElementNameHelper(value);
};
/**
* Escapes characters in the value to make it valid content for a JS string
* literal.
*
* @param {*} value The value to escape. May not be a string, but the value
* will be coerced to a string.
* @return {string} An escaped version of value.
* @deprecated
*/
soy.$$escapeJs = function(value) {
return soy.$$escapeJsString(value);
};
/**
* Escapes characters in the value to make it valid content for a JS string
* literal.
*
* @param {*} value The value to escape. May not be a string, but the value
* will be coerced to a string.
* @return {string} An escaped version of value.
*/
soy.$$escapeJsString = function(value) {
if (typeof value === 'object' &&
value.contentKind === soydata.SanitizedContentKind.JS_STR_CHARS) {
return value.content;
}
return soy.esc.$$escapeJsStringHelper(value);
};
/**
* Encodes a value as a JavaScript literal.
*
* @param {*} value The value to escape. May not be a string, but the value
* will be coerced to a string.
* @return {string} A JavaScript code representation of the input.
*/
soy.$$escapeJsValue = function(value) {
// We surround values with spaces so that they can't be interpolated into
// identifiers by accident.
// We could use parentheses but those might be interpreted as a function call.
if (value == null) { // Intentionally matches undefined.
// Java returns null from maps where there is no corresponding key while
// JS returns undefined.
// We always output null for compatibility with Java which does not have a
// distinct undefined value.
return ' null ';
}
switch (typeof value) {
case 'boolean': case 'number':
return ' ' + value + ' ';
default:
return "'" + soy.esc.$$escapeJsStringHelper(String(value)) + "'";
}
};
/**
* Escapes characters in the string to make it valid content for a JS regular
* expression literal.
*
* @param {*} value The value to escape. May not be a string, but the value
* will be coerced to a string.
* @return {string} An escaped version of value.
*/
soy.$$escapeJsRegex = function(value) {
return soy.esc.$$escapeJsRegexHelper(value);
};
/**
* Matches all URI mark characters that conflict with HTML attribute delimiters
* or that cannot appear in a CSS uri.
* From G.2: CSS grammar
*
* url ([!#$%&*-~]|{nonascii}|{escape})*
*
*
* @type {RegExp}
* @private
*/
soy.$$problematicUriMarks_ = /['()]/g;
/**
* @param {string} ch A single character in {@link soy.$$problematicUriMarks_}.
* @return {string}
* @private
*/
soy.$$pctEncode_ = function(ch) {
return '%' + ch.charCodeAt(0).toString(16);
};
/**
* Escapes a string so that it can be safely included in a URI.
*
* @param {*} value The value to escape. May not be a string, but the value
* will be coerced to a string.
* @return {string} An escaped version of value.
*/
soy.$$escapeUri = function(value) {
if (typeof value === 'object' &&
value.contentKind === soydata.SanitizedContentKind.URI) {
return soy.$$normalizeUri(value);
}
// Apostophes and parentheses are not matched by encodeURIComponent.
// They are technically special in URIs, but only appear in the obsolete mark
// production in Appendix D.2 of RFC 3986, so can be encoded without changing
// semantics.
var encoded = soy.esc.$$escapeUriHelper(value);
soy.$$problematicUriMarks_.lastIndex = 0;
if (soy.$$problematicUriMarks_.test(encoded)) {
return encoded.replace(soy.$$problematicUriMarks_, soy.$$pctEncode_);
}
return encoded;
};
/**
* Removes rough edges from a URI by escaping any raw HTML/JS string delimiters.
*
* @param {*} value The value to escape. May not be a string, but the value
* will be coerced to a string.
* @return {string} An escaped version of value.
*/
soy.$$normalizeUri = function(value) {
return soy.esc.$$normalizeUriHelper(value);
};
/**
* Vets a URI's protocol and removes rough edges from a URI by escaping
* any raw HTML/JS string delimiters.
*
* @param {*} value The value to escape. May not be a string, but the value
* will be coerced to a string.
* @return {string} An escaped version of value.
*/
soy.$$filterNormalizeUri = function(value) {
return soy.esc.$$filterNormalizeUriHelper(value);
};
/**
* Escapes a string so it can safely be included inside a quoted CSS string.
*
* @param {*} value The value to escape. May not be a string, but the value
* will be coerced to a string.
* @return {string} An escaped version of value.
*/
soy.$$escapeCssString = function(value) {
return soy.esc.$$escapeCssStringHelper(value);
};
/**
* Encodes a value as a CSS identifier part, keyword, or quantity.
*
* @param {*} value The value to escape. May not be a string, but the value
* will be coerced to a string.
* @return {string} A safe CSS identifier part, keyword, or quanitity.
*/
soy.$$filterCssValue = function(value) {
// Uses == to intentionally match null and undefined for Java compatibility.
if (value == null) {
return '';
}
return soy.esc.$$filterCssValueHelper(value);
};
// -----------------------------------------------------------------------------
// Basic directives/functions.
/**
* Converts \r\n, \r, and \n to
s
* @param {*} str The string in which to convert newlines.
* @return {string} A copy of {@code str} with converted newlines.
*/
soy.$$changeNewlineToBr = function(str) {
return goog.string.newLineToBr(String(str), false);
};
/**
* Inserts word breaks ('wbr' tags) into a HTML string at a given interval. The
* counter is reset if a space is encountered. Word breaks aren't inserted into
* HTML tags or entities. Entites count towards the character count; HTML tags
* do not.
*
* @param {*} str The HTML string to insert word breaks into. Can be other
* types, but the value will be coerced to a string.
* @param {number} maxCharsBetweenWordBreaks Maximum number of non-space
* characters to allow before adding a word break.
* @return {string} The string including word breaks.
*/
soy.$$insertWordBreaks = function(str, maxCharsBetweenWordBreaks) {
return goog.format.insertWordBreaks(String(str), maxCharsBetweenWordBreaks);
};
/**
* Truncates a string to a given max length (if it's currently longer),
* optionally adding ellipsis at the end.
*
* @param {*} str The string to truncate. Can be other types, but the value will
* be coerced to a string.
* @param {number} maxLen The maximum length of the string after truncation
* (including ellipsis, if applicable).
* @param {boolean} doAddEllipsis Whether to add ellipsis if the string needs
* truncation.
* @return {string} The string after truncation.
*/
soy.$$truncate = function(str, maxLen, doAddEllipsis) {
str = String(str);
if (str.length <= maxLen) {
return str; // no need to truncate
}
// If doAddEllipsis, either reduce maxLen to compensate, or else if maxLen is
// too small, just turn off doAddEllipsis.
if (doAddEllipsis) {
if (maxLen > 3) {
maxLen -= 3;
} else {
doAddEllipsis = false;
}
}
// Make sure truncating at maxLen doesn't cut up a unicode surrogate pair.
if (soy.$$isHighSurrogate_(str.charAt(maxLen - 1)) &&
soy.$$isLowSurrogate_(str.charAt(maxLen))) {
maxLen -= 1;
}
// Truncate.
str = str.substring(0, maxLen);
// Add ellipsis.
if (doAddEllipsis) {
str += '...';
}
return str;
};
/**
* Private helper for $$truncate() to check whether a char is a high surrogate.
* @param {string} ch The char to check.
* @return {boolean} Whether the given char is a unicode high surrogate.
* @private
*/
soy.$$isHighSurrogate_ = function(ch) {
return 0xD800 <= ch && ch <= 0xDBFF;
};
/**
* Private helper for $$truncate() to check whether a char is a low surrogate.
* @param {string} ch The char to check.
* @return {boolean} Whether the given char is a unicode low surrogate.
* @private
*/
soy.$$isLowSurrogate_ = function(ch) {
return 0xDC00 <= ch && ch <= 0xDFFF;
};
// -----------------------------------------------------------------------------
// Bidi directives/functions.
/**
* Cache of bidi formatter by context directionality, so we don't keep on
* creating new objects.
* @type {!Object.}
* @private
*/
soy.$$bidiFormatterCache_ = {};
/**
* Returns cached bidi formatter for bidiGlobalDir, or creates a new one.
* @param {number} bidiGlobalDir The global directionality context: 1 if ltr, -1
* if rtl, 0 if unknown.
* @return {goog.i18n.BidiFormatter} A formatter for bidiGlobalDir.
* @private
*/
soy.$$getBidiFormatterInstance_ = function(bidiGlobalDir) {
return soy.$$bidiFormatterCache_[bidiGlobalDir] ||
(soy.$$bidiFormatterCache_[bidiGlobalDir] =
new goog.i18n.BidiFormatter(bidiGlobalDir));
};
/**
* Returns the leading horizontal edge, i.e. "left" or "right", depending on
* bidiGlobalDir.
* @param {number} bidiGlobalDir The global directionality context: 1 if ltr, -1
* if rtl, 0 if unknown.
* @return {string} "right" for RTL context and "left" otherwise.
*/
soy.$$bidiStartEdge = function(bidiGlobalDir) {
return soy.$$getBidiFormatterInstance_(bidiGlobalDir).startEdge();
};
/**
* Returns the trailing horizontal edge, i.e. "right" or "left", depending on
* bidiGlobalDir.
* @param {number} bidiGlobalDir The global directionality context: 1 if ltr, -1
* if rtl, 0 if unknown.
* @return {string} "left" for RTL context and "right" otherwise.
*/
soy.$$bidiEndEdge = function(bidiGlobalDir) {
return soy.$$getBidiFormatterInstance_(bidiGlobalDir).endEdge();
};
/**
* Estimate the overall directionality of text. If opt_isHtml, makes sure to
* ignore the LTR nature of the mark-up and escapes in text, making the logic
* suitable for HTML and HTML-escaped text.
* @param {string} text The text whose directionality is to be estimated.
* @param {boolean=} opt_isHtml Whether text is HTML/HTML-escaped.
* Default: false.
* @return {number} 1 if text is LTR, -1 if it is RTL, and 0 if it is neutral.
*/
soy.$$bidiTextDir = function(text, opt_isHtml) {
if (!text) {
return 0;
}
return goog.i18n.bidi.detectRtlDirectionality(text, opt_isHtml) ? -1 : 1;
};
/**
* Returns "dir=ltr" or "dir=rtl", depending on text's estimated
* directionality, if it is not the same as bidiGlobalDir.
* Otherwise, returns the empty string.
* If opt_isHtml, makes sure to ignore the LTR nature of the mark-up and escapes
* in text, making the logic suitable for HTML and HTML-escaped text.
* @param {number} bidiGlobalDir The global directionality context: 1 if ltr, -1
* if rtl, 0 if unknown.
* @param {string} text The text whose directionality is to be estimated.
* @param {boolean=} opt_isHtml Whether text is HTML/HTML-escaped.
* Default: false.
* @return {soydata.SanitizedHtmlAttribute} "dir=rtl" for RTL text in non-RTL
* context; "dir=ltr" for LTR text in non-LTR context;
* else, the empty string.
*/
soy.$$bidiDirAttr = function(bidiGlobalDir, text, opt_isHtml) {
return new soydata.SanitizedHtmlAttribute(
soy.$$getBidiFormatterInstance_(bidiGlobalDir).dirAttr(text, opt_isHtml));
};
/**
* Returns a Unicode BiDi mark matching bidiGlobalDir (LRM or RLM), or an empty
* string if bidiGlobalDir is 0 (unknown).
* @param {number} bidiGlobalDir The global directionality context: 1 if ltr, -1
* if rtl, 0 if unknown.
* @return {string} A Unicode bidi mark matching bidiGlobalDir, or the empty
* string when bidiGlobalDir is 0 (unknown).
*/
soy.$$bidiMark = function(bidiGlobalDir) {
return soy.$$getBidiFormatterInstance_(bidiGlobalDir).mark();
};
/**
* Returns a Unicode BiDi mark matching bidiGlobalDir (LRM or RLM) if the
* directionality or the exit directionality of text are opposite to
* bidiGlobalDir. Otherwise returns the empty string.
* If opt_isHtml, makes sure to ignore the LTR nature of the mark-up and escapes
* in text, making the logic suitable for HTML and HTML-escaped text.
* @param {number} bidiGlobalDir The global directionality context: 1 if ltr, -1
* if rtl, 0 if unknown.
* @param {string} text The text whose directionality is to be estimated.
* @param {boolean=} opt_isHtml Whether text is HTML/HTML-escaped.
* Default: false.
* @return {string} A Unicode bidi mark matching bidiGlobalDir, or the empty
* string when text's overall and exit directionalities both match
* bidiGlobalDir, or bidiGlobalDir is 0 (unknown).
*/
soy.$$bidiMarkAfter = function(bidiGlobalDir, text, opt_isHtml) {
var formatter = soy.$$getBidiFormatterInstance_(bidiGlobalDir);
return formatter.markAfter(text, opt_isHtml);
};
/**
* Returns str wrapped in a according to its directionality -
* but only if that is neither neutral nor the same as the global context.
* Otherwise, returns str unchanged.
* Always treats str as HTML/HTML-escaped, i.e. ignores mark-up and escapes when
* estimating str's directionality.
* @param {number} bidiGlobalDir The global directionality context: 1 if ltr, -1
* if rtl, 0 if unknown.
* @param {*} str The string to be wrapped. Can be other types, but the value
* will be coerced to a string.
* @return {string} The wrapped string.
*/
soy.$$bidiSpanWrap = function(bidiGlobalDir, str) {
var formatter = soy.$$getBidiFormatterInstance_(bidiGlobalDir);
return formatter.spanWrap(str + '', true);
};
/**
* Returns str wrapped in Unicode BiDi formatting characters according to its
* directionality, i.e. either LRE or RLE at the beginning and PDF at the end -
* but only if str's directionality is neither neutral nor the same as the
* global context. Otherwise, returns str unchanged.
* Always treats str as HTML/HTML-escaped, i.e. ignores mark-up and escapes when
* estimating str's directionality.
* @param {number} bidiGlobalDir The global directionality context: 1 if ltr, -1
* if rtl, 0 if unknown.
* @param {*} str The string to be wrapped. Can be other types, but the value
* will be coerced to a string.
* @return {string} The wrapped string.
*/
soy.$$bidiUnicodeWrap = function(bidiGlobalDir, str) {
var formatter = soy.$$getBidiFormatterInstance_(bidiGlobalDir);
return formatter.unicodeWrap(str + '', true);
};
// -----------------------------------------------------------------------------
// Generated code.
// START GENERATED CODE FOR ESCAPERS.
/**
* @type {function (*) : string}
*/
soy.esc.$$escapeUriHelper = function(v) {
return goog.string.urlEncode(String(v));
};
/**
* Maps charcters to the escaped versions for the named escape directives.
* @type {Object.