# angular.filter.html

Work in Progress This page is currently being revised. It might be incomplete or contain inaccuracies.

## Description

Prevents the input from getting escaped by angular. By default the input is sanitized and inserted into the DOM as is.

The input is sanitized by parsing the html into tokens. All safe tokens (from a whitelist) are then serialized back to properly escaped html string. This means that no unsafe input can make it into the returned string, however since our parser is more strict than a typical browser parser, it's possible that some obscure input, which would be recognized as valid HTML by a browser, won't make it through the sanitizer.

If you hate your users, you may call the filter with optional 'unsafe' argument, which bypasses the html sanitizer, but makes your application vulnerable to XSS and other attacks. Using this option is strongly discouraged and should be used only if you absolutely trust the input being filtered and you can't get the content through the sanitizer.

## Usage

### In HTML Template Binding

`{{ html_expression | html[:option] }}`

### In JavaScript

`angular.filter.html(html[, option])`

### Parameters

- `html – {string} –`

  Html input.

- `option(optional) – {string} –`

  If 'unsafe' then do not sanitize the HTML input.

### Returns

`{string}` –

Sanitized or raw html.

## Example

     Snippet: <textarea name="snippet" cols="60" rows="3">
    &lt;p style="color:blue"&gt;an html
    &lt;em onmouseover="this.textContent='PWN3D!'"&gt;click here&lt;/em&gt;
    snippet&lt;/p&gt;</textarea>
      <table>
        <tr>
          <td>Filter</td>
          <td>Source</td>
          <td>Rendered</td>
        </tr>
        <tr id="html-filter">
          <td>html filter</td>
          <td>
            <pre>&lt;div ng:bind="snippet | html"&gt;<br/>&lt;/div&gt;</pre>
          </td>
          <td>
            <div ng:bind="snippet | html"></div>
          </td>
        </tr>
        <tr id="escaped-html">
          <td>no filter</td>
          <td><pre>&lt;div ng:bind="snippet"&gt;<br/>&lt;/div&gt;</pre></td>
          <td><div ng:bind="snippet"></div></td>
        </tr>
        <tr id="html-unsafe-filter">
          <td>unsafe html filter</td>
          <td><pre>&lt;div ng:bind="snippet | html:'unsafe'"&gt;<br/>&lt;/div&gt;</pre></td>
          <td><div ng:bind="snippet | html:'unsafe'"></div></td>
        </tr>
      </table>

      it('should sanitize the html snippet ', function(){
        expect(using('#html-filter').binding('snippet | html')).
          toBe('<p>an html\n<em>click here</em>\nsnippet</p>');
      });

      it('should escape snippet without any filter', function() {
        expect(using('#escaped-html').binding('snippet')).
          toBe("&lt;p style=\"color:blue\"&gt;an html\n" +
               "&lt;em onmouseover=\"this.textContent='PWN3D!'\"&gt;click here&lt;/em&gt;\n" +
               "snippet&lt;/p&gt;");
      });

      it('should inline raw snippet if filtered as unsafe', function() {
        expect(using('#html-unsafe-filter').binding("snippet | html:'unsafe'")).
          toBe("<p style=\"color:blue\">an html\n" +
               "<em onmouseover=\"this.textContent='PWN3D!'\">click here</em>\n" +
               "snippet</p>");
      });

      it('should update', function(){
        input('snippet').enter('new <b>text</b>');
        expect(using('#html-filter').binding('snippet | html')).toBe('new <b>text</b>');
        expect(using('#escaped-html').binding('snippet')).toBe("new &lt;b&gt;text&lt;/b&gt;");
        expect(using('#html-unsafe-filter').binding("snippet | html:'unsafe'")).toBe('new <b>text</b>');
      });