angular.js/docs/tutorial.step_9.ngdoc

@workInProgress
@ngdoc overview
@name Tutorial: Step 9
@description
<table id="tutorial_nav">
<tr>
<td id="previous_step">{@link tutorial.step_8 Previous}</td>
<td id="step_result">{@link  http://angular.github.com/angular-phonecat/step-9/app Live Demo
}</td>
<td id="tut_home">{@link tutorial Tutorial Home}</td>
<td id="code_diff">{@link https://github.com/angular/angular-phonecat/compare/step-8...step-9 Code
Diff}</td>
<td id="next_step">{@link tutorial.step_10 Next}</td>
</tr>
</table>

In this step, we have determined that the built-in angular display filters ({@link
angular.filter.number number}, {@link angular.filter.currency currency}, {@link
angular.filter.date date}, etc.) don't handle what we want to do, so we get to create our own
custom {@link angular.filter filter}.  

In the previous step, the details page displayed either "true" or "false" to indicate whether
certain phone features were present or not.  Our custom "checkmark" filter replaces those text
strings with glyphs: ✓ for "true", and ✘ for "false".

Our filter code lives in `app/js/filters.js`:

__`app/index.html`:__ 
<pre>
...
 <script src="lib/angular/angular.js" ng:autobind></script>
 <script src="js/controllers.js"></script>
 <script src="app/js/filters.js"></script>
...
</pre>

In the phone details template, we employ our filter for angular expressions whose values are
"true" or "false"; `{{ [phone_feature] | checkmark }}`:

__`app/partials/phone-detail.html`:__ 
<pre>
<img ng:src="{{phone.images[0].large}}" class="phone"/>
<h1>{{phone.name}}</h1>
<p>{{phone.description}}</p>
...
<ul class="specs">
  ...
  <li>
    <span>Connectivity</span>
    <dl>
      <dt>Network Support</dt>
      <dd>{{phone.connectivity.cell}}</dd>
      <dt>WiFi</dt>
      <dd>{{phone.connectivity.wifi}}</dd>
      <dt>Bluetooth</dt>
      <dd>{{phone.connectivity.bluetooth}}</dd>
      <dt>Infrared</dt>
      <dd>{{phone.connectivity.infrared | checkmark}}</dd>
      <dt>GPS</dt>
      <dd>{{phone.connectivity.gps | checkmark}}</dd>
    </dl>
  </li>
...
</ul>
</pre>

__`app/js/filters.js`:__ (New)
<pre>
angular.filter('checkmark', function(input) {
  return input ? '\u2713' : '\u2718';
});
</pre>

__`test/unit/filtersSpec.js`:__ (New)
<pre>
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>

## Discussion:

* This example shows how easy it is to roll your own filters for displaying data.  As explained in
the "Writing your own Filters" section of the {@link angular.filter angular.filter} page, you
simply register your custom filter function on to the `angular.filter` function. 

* In this example, our filter name is "checkmark"; our input is either "true" or "false", and we
return one of two unicode characters we have chosen to represent true or false (`\u2713` and
`\u2718`).  

* We created a new unit test to verify that our custom filter converts boolean values to unicode
characters.

<table id="tutorial_nav">
<tr>
<td id="previous_step">{@link tutorial.step_8 Previous}</td>
<td id="step_result">{@link  http://angular.github.com/angular-phonecat/step-9/app Live Demo
}</td>
<td id="tut_home">{@link tutorial Tutorial Home}</td>
<td id="code_diff">{@link https://github.com/angular/angular-phonecat/compare/step-8...step-9 Code
Diff}</td>
<td id="next_step">{@link tutorial.step_10 Next}</td>
</tr>
</table>