module ERB::Util - activesupport-4.2.4 Documentation

# module ERB::Util

### Constants

HTML_ESCAPE
HTML_ESCAPE_ONCE_REGEXP
HTML_ESCAPE_REGEXP
JSON_ESCAPE
JSON_ESCAPE_REGEXP

### Public Class Methods

h(s)
Alias for: html_escape
html_escape(s) click to toggle source

A utility method for escaping HTML tag characters. This method is also aliased as `h`.

In your ERB templates, use this method to escape any unsafe content. For example:

    <%=h @person.name %>

    puts html_escape('is a > 0 & a < 10?')
    # => is a &gt; 0 &amp; a &lt; 10?

    # File lib/active_support/core_ext/string/output_safety.rb, line 21
    def html_escape(s)
      unwrapped_html_escape(s).html_safe
    end

Also aliased as: h
html_escape_once(s) click to toggle source

A utility method for escaping HTML without affecting existing escaped entities.

    html_escape_once('1 < 2 &amp; 3')
    # => "1 &lt; 2 &amp; 3"

    html_escape_once('&lt;&lt; Accept & Checkout')
    # => "&lt;&lt; Accept &amp; Checkout"

    # File lib/active_support/core_ext/string/output_safety.rb, line 53
    def html_escape_once(s)
      result = s.to_s.gsub(HTML_ESCAPE_ONCE_REGEXP, HTML_ESCAPE)
      s.html_safe? ? result.html_safe : result
    end

json_escape(s) click to toggle source

A utility method for escaping HTML entities in JSON strings. Specifically, the &, > and < characters are replaced with their equivalent unicode escaped form - u0026, u003e, and u003c. The Unicode sequences u2028 and u2029 are also escaped as they are treated as newline characters in some JavaScript engines. These sequences have identical meaning as the original characters inside the context of a JSON string, so assuming the input is a valid and well-formed JSON value, the output will have equivalent meaning when parsed:

    json = JSON.generate({ name: "</script><script>alert('PWNED!!!')</script>"})
    # => "{\"name\":\"</script><script>alert('PWNED!!!')</script>\"}"

    json_escape(json)
    # => "{\"name\":\"\\u003C/script\\u003E\\u003Cscript\\u003Ealert('PWNED!!!')\\u003C/script\\u003E\"}"

    JSON.parse(json) == JSON.parse(json_escape(json))
    # => true

The intended use case for this method is to escape JSON strings before including them inside a script tag to avoid XSS vulnerability:

    <script>
      var currentUser = <%= raw json_escape(current_user.to_json) %>;
    </script>

It is necessary to `raw` the result of `json_escape`, so that quotation marks don't get converted to `&quot;` entities. `json_escape` doesn't automatically flag the result as HTML safe, since the raw value is unsafe to use inside HTML attributes.

If you need to output JSON elsewhere in your HTML, you can just do something like this, as any unsafe characters (including quotation marks) will be automatically escaped for you:

    <div data-user-info="<%= current_user.to_json %>">...</div>

WARNING: this helper only works with valid JSON. Using this on non-JSON values will open up serious XSS vulnerabilities. For example, if you replace the `current_user.to_json` in the example above with user input instead, the browser will happily eval() that string as JavaScript.

The escaping performed in this method is identical to those performed in the Active Support JSON encoder when `ActiveSupport.escape_html_entities_in_json` is set to true. Because this transformation is idempotent, this helper can be applied even if `ActiveSupport.escape_html_entities_in_json` is already true.

Therefore, when you are unsure if `ActiveSupport.escape_html_entities_in_json` is enabled, or if you are unsure where your JSON string originated from, it is recommended that you always apply this helper (other libraries, such as the JSON gem, do not provide this kind of protection by default; also some gems might override `to_json` to bypass Active Support's encoder).

    # File lib/active_support/core_ext/string/output_safety.rb, line 110
    def json_escape(s)
      result = s.to_s.gsub(JSON_ESCAPE_REGEXP, JSON_ESCAPE)
      s.html_safe? ? result.html_safe : result
    end

### Private Instance Methods

h(s)
Alias for: html_escape
html_escape(s) click to toggle source

A utility method for escaping HTML tag characters. This method is also aliased as `h`.

In your ERB templates, use this method to escape any unsafe content. For example:

    <%=h @person.name %>

    puts html_escape('is a > 0 & a < 10?')
    # => is a &gt; 0 &amp; a &lt; 10?

    # File lib/active_support/core_ext/string/output_safety.rb, line 21
    def html_escape(s)
      unwrapped_html_escape(s).html_safe
    end

Also aliased as: h
html_escape_once(s) click to toggle source

A utility method for escaping HTML without affecting existing escaped entities.

    html_escape_once('1 < 2 &amp; 3')
    # => "1 &lt; 2 &amp; 3"

    html_escape_once('&lt;&lt; Accept & Checkout')
    # => "&lt;&lt; Accept &amp; Checkout"

    # File lib/active_support/core_ext/string/output_safety.rb, line 53
    def html_escape_once(s)
      result = s.to_s.gsub(HTML_ESCAPE_ONCE_REGEXP, HTML_ESCAPE)
      s.html_safe? ? result.html_safe : result
    end

json_escape(s) click to toggle source

A utility method for escaping HTML entities in JSON strings. Specifically, the &, > and < characters are replaced with their equivalent unicode escaped form - u0026, u003e, and u003c. The Unicode sequences u2028 and u2029 are also escaped as they are treated as newline characters in some JavaScript engines. These sequences have identical meaning as the original characters inside the context of a JSON string, so assuming the input is a valid and well-formed JSON value, the output will have equivalent meaning when parsed:

    json = JSON.generate({ name: "</script><script>alert('PWNED!!!')</script>"})
    # => "{\"name\":\"</script><script>alert('PWNED!!!')</script>\"}"

    json_escape(json)
    # => "{\"name\":\"\\u003C/script\\u003E\\u003Cscript\\u003Ealert('PWNED!!!')\\u003C/script\\u003E\"}"

    JSON.parse(json) == JSON.parse(json_escape(json))
    # => true

The intended use case for this method is to escape JSON strings before including them inside a script tag to avoid XSS vulnerability:

    <script>
      var currentUser = <%= raw json_escape(current_user.to_json) %>;
    </script>

It is necessary to `raw` the result of `json_escape`, so that quotation marks don't get converted to `&quot;` entities. `json_escape` doesn't automatically flag the result as HTML safe, since the raw value is unsafe to use inside HTML attributes.

If you need to output JSON elsewhere in your HTML, you can just do something like this, as any unsafe characters (including quotation marks) will be automatically escaped for you:

    <div data-user-info="<%= current_user.to_json %>">...</div>

WARNING: this helper only works with valid JSON. Using this on non-JSON values will open up serious XSS vulnerabilities. For example, if you replace the `current_user.to_json` in the example above with user input instead, the browser will happily eval() that string as JavaScript.

The escaping performed in this method is identical to those performed in the Active Support JSON encoder when `ActiveSupport.escape_html_entities_in_json` is set to true. Because this transformation is idempotent, this helper can be applied even if `ActiveSupport.escape_html_entities_in_json` is already true.

Therefore, when you are unsure if `ActiveSupport.escape_html_entities_in_json` is enabled, or if you are unsure where your JSON string originated from, it is recommended that you always apply this helper (other libraries, such as the JSON gem, do not provide this kind of protection by default; also some gems might override `to_json` to bypass Active Support's encoder).

    # File lib/active_support/core_ext/string/output_safety.rb, line 110
    def json_escape(s)
      result = s.to_s.gsub(JSON_ESCAPE_REGEXP, JSON_ESCAPE)
      s.html_safe? ? result.html_safe : result
    end