step_09.html

<h1>Tutorial: 9 - Filters</h1>
<div class="tutorial-9-filters"><ul doc:tutorial-nav="9"></ul>

<p>In this step you will learn how to create your own custom display filter.</p><doc:tutorial-instructions step="9"></doc:tutorial-instructions><p>Navigate to one of the detail pages.</p>

<p>In the previous step, the details page displayed either "true" or "false" to indicate whether
certain phone features were present or not. We have used a custom filter to convert those text
strings into glyphs: ✓ for "true", and ✘ for "false". Let's see, what the filter code looks like.</p>

<p>The most important changes are listed below. You can see the full diff on <a href="https://github.com/angular/angular-phonecat/compare/step-8...step-9">GitHub</a>:</p>

<h3>Custom Filter</h3>

<p>In order to create a new filter, simply register your custom filter function with the <a href="#!/api/angular.filter"><code><code>angular.filter</code></code></a> API.</p>

<p><strong><code>app/js/filters.js</code>:</strong></p><div ng:non-bindable><pre class="brush: js;">
angular.filter('checkmark', function(input) {
  return input ? '\u2713' : '\u2718';
});
</pre></div><p>The name of our filter is "checkmark". The <code>input</code> evaluates to either <code>true</code> or <code>false</code>, and we
return one of two unicode characters we have chosen to represent true or false (<code>\u2713</code> and
<code>\u2718</code>).</p>

<h3>Template</h3>

<p>Since the filter code lives in the <code>app/js/filters.js</code> file, we need to include this file in our
layout template.</p>

<p><strong><code>app/index.html</code>:</strong></p><div ng:non-bindable><pre class="brush: js; html-script: true;">
...
 &lt;script src="js/controllers.js"&gt;&lt;/script&gt;
 &lt;script src="js/filters.js"&gt;&lt;/script&gt;
...
</pre></div><p>The syntax for using filters in angular templates is as follows:</p>

<pre><code>{{ expression | filter }}
</code></pre>

<p>Let's employ the filter in the phone details template:</p>

<p><strong><code>app/partials/phone-detail.html</code>:</strong></p><div ng:non-bindable><pre class="brush: js; html-script: true;">
...
    &lt;dl&gt;
      &lt;dt&gt;Infrared&lt;/dt&gt;
      &lt;dd&gt;{{phone.connectivity.infrared | checkmark}}&lt;/dd&gt;
      &lt;dt&gt;GPS&lt;/dt&gt;
      &lt;dd&gt;{{phone.connectivity.gps | checkmark}}&lt;/dd&gt;
    &lt;/dl&gt;
...
</pre></div><h3>Test</h3>

<p>Filters, like any other component, should be tested and these tests are very easy to write.</p>

<p><strong><code>test/unit/filtersSpec.js</code>:</strong></p><div ng:non-bindable><pre class="brush: js;">
describe('checkmark filter', function() {

  it('should convert boolean values to unicode checkmark or cross', function() {
    expect(angular.filter.checkmark(true)).toBe('\u2713');
    expect(angular.filter.checkmark(false)).toBe('\u2718');
  });
})
</pre></div><p>To run the unit tests, execute the <code>./scripts/test.sh</code> script and you should see the following
output.</p>

<pre><code>    Chrome: Runner reset.
    ....
    Total 4 tests (Passed: 4; Fails: 0; Errors: 0) (3.00 ms)
      Chrome 11.0.696.57 Mac OS: Run 4 tests (Passed: 4; Fails: 0; Errors 0) (3.00 ms)
</code></pre>

<h2>Experiments</h2>

<ul>
<li><p>Let's experiment with some of the <a href="#!/api/angular.filter"><code>built-in angular filters</code></a> and add the
following bindings to <code>index.html</code>:</p>

<ul><li><code>{{ "lower cap string" | uppercase }}</code></li>
<li><code>{{ {foo: "bar", baz: 23} | json }}</code></li>
<li><code>{{ 1304375948024 | date }}</code></li>
<li><code>{{ 1304375948024 | date:"MM/dd/yyyy @ h:mma" }}</code></li></ul></li>
<li><p>We can also create a model with an input element, and combine it with a filtered binding. Add
the following to index.html:</p>

<pre><code>&lt;input name="userInput"&gt; Uppercased: {{ userInput | uppercase }}
</code></pre></li>
</ul>

<h2>Summary</h2>

<p>Now that you have learned how to write and test a custom filter, go to <a href="#!/tutorial/step_10">step 10</a> to
learn how we can use angular to enhance the phone details page further.</p>

<ul doc:tutorial-nav="9"></ul></div>