Merge 863cdd1 into 02b0f0d

.travis.yml

@@ -1,3 +1,5 @@
+dist: trusty
+
 language: node_js
 
 sudo: true

src/js/utils/html-utils.js

@@ -93,7 +93,7 @@
          * );
          *~~~
          *
-         * returns:
+         * returns an HtmlSnippet object whose .toString() method returns:
          *
          *~~~ javascript
          * 'You are enrolling in <span class="course-title">Rock &amp; Roll 101</span>'
@@ -110,6 +110,26 @@
          * );
          *~~~
          *
+         * Since escaping is done by default, this is safe to use for rendering untrusted
+         * input within html. For example:
+         *
+         *~~~ javascript
+         * HtmlUtils.interpolateHtml(
+         *     'User said {emStart}{comment}{emEnd}',
+         *     {
+         *         emStart: HtmlUtils.HTML('<em>'),
+         *         comment: '<script>alert("test");</script>',
+         *         emEnd: HtmlUtils.HTML('</em>'),
+         *     }
+         * );
+         *~~~
+         *
+         * returns an HtmlSnippet object whose .toString() method returns:
+         *
+         *~~~ javascript
+         * 'User said <em>&lt;script&gt;alert(&quot;test&quot;);&lt;/script&gt;</em>'
+         *~~~
+         *
          * @param {string} formatString The string to be interpolated.
          * @param {Object} parameters An optional set of parameters for interpolation.
          * @returns {HtmlSnippet} The resulting safely escaped HTML snippet.

src/js/utils/specs/string-utils-spec.js

@@ -26,6 +26,10 @@ define(
                     'does not interpolate additional curly braces': [
                         'Hello, {name}. Here is a { followed by a }', {name: 'Andy'},
                         'Hello, Andy. Here is a { followed by a }'
+                    ],
+                    'does not escape html': [
+                        '<b>Hello</b>, {name}', {name: '<script>alert("boom");</script>'},
+                        '<b>Hello</b>, <script>alert("boom");</script>'
                     ]
                 }, function(template, options, expectedString) {
                     var result = StringUtils.interpolate(template, options);

src/js/utils/string-utils.js

@@ -16,37 +16,35 @@
          * indicated via curly braces, e.g. 'Hello {name}'. These tokens are
          * replaced by the parameter value of the same name.
          *
-         * Parameter values will be rendered using their toString methods and then
-         * HTML-escaped. The only exception is that instances of the class HTML
-         * are rendered without escaping as their contract declares that they are
-         * already valid HTML.
+         * Parameter values will be rendered using their toString methods.
+         * **NO** HTML escaping or sanitizing of any form is performed.
+         * If HTML escaping is required (for example, if user supplied input is
+         * being interpolated), use HtmlUtils.interpolateHtml().
          *
          * Example:
          *
          *~~~ javascript
-         * HtmlUtils.interpolate(
-         *     'You are enrolling in {spanStart}{courseName}{spanEnd}',
+         * StringUtils.interpolate(
+         *     'You are enrolling in {courseName}',
          *     {
          *         courseName: 'Rock & Roll 101',
-         *         spanStart: HtmlUtils.HTML('<span class="course-title">'),
-         *         spanEnd: HtmlUtils.HTML('</span>')
          *     }
          * );
          *~~~
          *
          * returns:
          *
          *~~~ javascript
-         * 'You are enrolling in <span class="course-title">Rock &amp; Roll 101</span>'
+         * 'You are enrolling in Rock & Roll 101'
          *~~~
          *
          * Note: typically the formatString will need to be internationalized, in which
          * case it will be wrapped with a call to an i18n lookup function. In Django,
          * this would look like:
          *
          *~~~ javascript
-         * HtmlUtils.interpolate(
-         *     gettext('You are enrolling in {spanStart}{courseName}{spanEnd}'),
+         * StringUtils.interpolate(
+         *     gettext('You are enrolling in {courseName}'),
          *     ...
          * );
          *~~~