Improve this doc

In this step you will learn how to create your own custom display filter.

Navigate to one of the detail pages.

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.

The most important changes are listed below. You can see the full diff on GitHub:

Custom Filter

In order to create a new filter, you are going to create a phonecatFilters module and register your custom filter with this module:

app/js/filters.js: 

  1. angular.module('phonecatFilters', []).filter('checkmark', function() {
  2.   return function(input) {
  3.     return input ? '\u2713' : '\u2718';
  4.   };
  5. });

The name of our filter is "checkmark". The input evaluates to either true or false, and we return one of the two unicode characters we have chosen to represent true (\u2713 -> ✓) or false (\u2718 -> ✘).

Now that our filter is ready, we need to register the phonecatFilters module as a dependency for our main phonecat module.

app/js/app.js: 

  1. ...
  2. angular.module('phonecatApp', ['phonecatFilters']).
  3. ...

Template

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

app/index.html: 

  1. ...
  2.  <script src="js/controllers.js"></script>
  3.  <script src="js/filters.js"></script>
  4. ...

The syntax for using filters in Angular templates is as follows:

  1. {{ expression | filter }}

Let's employ the filter in the phone details template:

app/partials/phone-detail.html: 

  1. ...
  2.     <dl>
  3.       <dt>Infrared</dt>
  4.       <dd>{{phone.connectivity.infrared | checkmark}}</dd>
  5.       <dt>GPS</dt>
  6.       <dd>{{phone.connectivity.gps | checkmark}}</dd>
  7.     </dl>
  8. ...

Test

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

test/unit/filtersSpec.js: 

  1. describe('filter', function() {
  2.  
  3.   beforeEach(module('phonecatFilters'));
  4.  
  5.   describe('checkmark', function() {
  6.  
  7.     it('should convert boolean values to unicode checkmark or cross',
  8.         inject(function(checkmarkFilter) {
  9.       expect(checkmarkFilter(true)).toBe('\u2713');
  10.       expect(checkmarkFilter(false)).toBe('\u2718');
  11.     }));
  12.   });
  13. });

We must call beforeEach(module('phonecatFilters')) before any of our filter tests execute. This call loads our phonecatFilters module into the injector for this test run.

Note that we call the helper function, inject(function(checkmarkFilter) { … }), to get access to the filter that we want to test. See angular.mock.inject().

You should now see the following output in the Karma tab:

  1.     Chrome 22.0: Executed 4 of 4 SUCCESS (0.034 secs / 0.012 secs)

Experiments

  • Let's experiment with some of the built-in Angular filters and add the following bindings to index.html:

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

Summary

Now that you have learned how to write and test a custom filter, go to step 10 to learn how we can use Angular to enhance the phone details page further.