PhoneCat Tutorial App


A great way to get introduced to AngularJS is to work through this tutorial, which walks you through the construction of an Angular web app. The app you will build is a catalog that displays a list of Android devices, lets you filter the list to see only devices that interest you, and then view details for any device.

demo application running in the browser

Follow the tutorial to see how Angular makes browsers smarter — without the use of native extensions or plug-ins:

  • See examples of how to use client-side data binding to build dynamic views of data that change immediately in response to user actions.
  • See how Angular keeps your views in sync with your data without the need for DOM manipulation.
  • Learn a better, easier way to test your web apps, with Karma and Protractor.
  • Learn how to use dependency injection and services to make common web tasks, such as getting data into your app, easier.

When you finish the tutorial you will be able to:

  • Create a dynamic application that works in all modern browsers.
  • Use data binding to wire up your data model to your views.
  • Create and run unit tests, with Karma.
  • Create and run end-to-end tests, with Protractor.
  • Move application logic out of the template and into components and controllers.
  • Get data from a server using Angular services.
  • Apply animations to your application, using the ngAnimate module.
  • Structure your Angular applications in a modular way that scales well for larger projects.
  • Identify resources for learning more about AngularJS.

The tutorial guides you through the entire process of building a simple application, including writing and running unit and end-to-end tests. Experiments at the end of each step provide suggestions for you to learn more about AngularJS and the application you are building.

You can go through the whole tutorial in a couple of hours or you may want to spend a pleasant day really digging into it. If you're looking for a shorter introduction to AngularJS, check out the Getting Started document.

Environment Setup

The rest of this page explains how you can set up your local machine for development. If you just want to read the tutorial, you can go straight to the first step: Step 0 – Bootstrapping.

Working with the Code

You can follow along with this tutorial and hack on the code in the comfort of your own computer. This way, you can get hands-on practice of really writing Angular code and also on using the recommended testing tools.

The tutorial relies on the use of the Git versioning system for source code management. You don't need to know anything about Git to follow the tutorial other than how to install and run a few git commands.

Install Git

You can download and install Git from Once installed, you should have access to the git command line tool. The main commands that you will need to use are:

  • git clone ...: Clone a remote repository onto your local machine.
  • git checkout ...: Check out a particular branch or a tagged version of the code to hack on.

Download angular-phonecat

Clone the angular-phonecat repository located at GitHub by running the following command:

git clone --depth=16

This command creates an angular-phonecat sub-directory in your current directory.

The --depth=16 option tells Git to pull down only the last 16 commits. This makes the download much smaller and faster.

Change your current directory to angular-phonecat.

cd angular-phonecat

The tutorial instructions, from now on, assume you are running all commands from within the angular-phonecat directory.

Install Node.js

If you want to run the preconfigured local web server and the test tools then you will also need Node.js v4+.

You can download a Node.js installer for your operating system from

Check the version of Node.js that you have installed by running the following command:

node --version

In Debian based distributions, there might be a name clash with another utility called node. The suggested solution is to also install thenodejs-legacy apt package, which renames node to nodejs.

apt-get install nodejs-legacy npm
nodejs --version
npm --version
If you need to run different versions of Node.js in your local environment, consider installing Node Version Manager (nvm) or Node Version Manager (nvm) for Windows.

Once you have Node.js installed on your machine, you can download the tool dependencies by running:

npm install

This command reads angular-phonecat's package.json file and downloads the following tools into the node_modules directory:

  • Bower – client-side code package manager
  • Http-Server – simple local static web server
  • Karma – unit test runner
  • Protractor – end-to-end (E2E) test runner

Running npm install will also automatically use bower to download the AngularJS framework into the app/bower_components directory.

Note the angular-phonecat project is setup to install and run these utilities via npm scripts. This means that you do not have to have any of these utilities installed globally on your system to follow the tutorial. See Installing Helper Tools below for more information.

The project is preconfigured with a number of npm helper scripts to make it easy to run the common tasks that you will need while developing:

  • npm start: Start a local development web server.
  • npm test: Start the Karma unit test runner.
  • npm run protractor: Run the Protractor end-to-end (E2E) tests.
  • npm run update-webdriver: Install the drivers needed by Protractor.

Install Helper Tools (optional)

The Bower, Http-Server, Karma and Protractor modules are also executables, which can be installed globally and run directly from a terminal/command prompt. You don't need to do this to follow the tutorial, but if you decide you do want to run them directly, you can install these modules globally using, sudo npm install -g ....

For instance, to install the Bower command line executable you would do:

sudo npm install -g bower

(Omit the sudo if running on Windows)

Then you can run the bower tool directly, such as:

bower install

Running the Development Web Server

While Angular applications are purely client-side code, and it is possible to open them in a web browser directly from the file system, it is better to serve them from an HTTP web server. In particular, for security reasons, most modern browsers will not allow JavaScript to make server requests if the page is loaded directly from the file system.

The angular-phonecat project is configured with a simple static web server for hosting the application during development. Start the web server by running:

npm start

This will create a local web server that is listening to port 8000 on your local machine. You can now browse to the application athttp://localhost:8000/index.html.

To serve the web app on a different IP address or port, edit the "start" script within package.json. You can use -a to set the address and -p to set the port. You also need to update the baseUrl configuration property in e2e-test/protractor.conf.js.

Running Unit Tests

We use unit tests to ensure that the JavaScript code in our application is operating correctly. Unit tests focus on testing small isolated parts of the application. The unit tests are kept in test files (specs) side-by-side with the application code. This way it's easier to find them and keep them up-to-date with the code under test. It also makes refactoring our app structure easier, since tests are moved together with the source code.

The angular-phonecat project is configured to use Karma to run the unit tests for the application. Start Karma by running:

npm test

This will start the Karma unit test runner. Karma will read the configuration file karma.conf.js, located at the root of the project directory. This configuration file tells Karma to:

  • Open up instances of the Chrome and Firefox browsers and connect them to Karma.
  • Execute all the unit tests in these browsers.
  • Report the results of these tests in the terminal/command line window.
  • Watch all the project's JavaScript files and re-run the tests whenever any of these change.

It is good to leave this running all the time, in the background, as it will give you immediate feedback about whether your changes pass the unit tests while you are working on the code.

Running E2E Tests

We use E2E (end-to-end) tests to ensure that the application as a whole operates as expected. E2E tests are designed to test the whole client-side application, in particular that the views are displaying and behaving correctly. It does this by simulating real user interaction with the real application running in the browser.

The E2E tests are kept in the e2e-tests directory.

The angular-phonecat project is configured to use Protractor to run the E2E tests for the application. Protractor relies upon a set of drivers to allow it to interact with the browser. You can install these drivers by running:

npm run update-webdriver
You don't have to manually run this command. Our npm scripts are configured so that it will be automatically executed as part of the command that runs the E2E tests.

Since Protractor works by interacting with a running application, we need to start our web server:

npm start

Then, in a separate terminal/command line window, we can run the Protractor test scripts against the application by running:

npm run protractor

Protractor will read the configuration file at e2e-tests/protractor.conf.js. This configuration file tells Protractor to:

  • Open up a Chrome browser and connect it to the application.
  • Execute all the E2E tests in this browser.
  • Report the results of these tests in the terminal/command line window.
  • Close the browser and exit.

It is good to run the E2E tests whenever you make changes to the HTML views or want to check that the application as a whole is executing correctly. It is very common to run E2E tests before pushing a new commit of changes to a remote repository.

Common Issues

Firewall / Proxy issues

Git and other tools, often use the git: protocol for accessing files in remote repositories. Some firewall configurations are blockinggit:// URLs, which leads to errors when trying to clone repositories or download dependencies. (For example corporate firewalls are "notorious" for blocking git:.)

If you run into this issue, you can force the use of https: instead, by running the following command:git config --global url."https://".insteadOf git://

Updating WebDriver takes too long

Running update-webdriver for the first time may take from several seconds up to a few minutes (depending on your hardware and network connection). If you cancel the operation (e.g. using Ctrl+C), you might get errors, when trying to run Protractor later.

In that case, you can delete the node_modules/ directory and run npm install again.

Protractor dependencies

Under the hood, Protractor uses the Selenium Stadalone Server, which in turn requires the Java Development Kit (JDK) to be installed on your local machine. Check this by running java -version from the command line.

If JDK is not already installed, you can download it here.

Error running the web server

The web server is configured to use port 8000. If the port is already in use (for example by another instance of a running web server) you will get an EADDRINUSE error. Make sure the port is available, before running npm start.

Now that you have set up your local machine, let's get started with the tutorial: Step 0 – Bootstrapping



May 2016

This is a test for bot

This is a test for bot on 2016-05-23.

Power overwhelming!

May 2016

Left Navigation Component Guide

The left navigation is a special component that is designed to be dragged and dropped into the iparsys (inherited parsys) at the left column of a three-column page of a parent web page and is inherited by all of its children pages. This component has some configurable elements, while its links are dynamically populated by the child and grand-child pages of the original page where the component begins.

Dropping the Left Navigation Component to a Parent Page

The Three Column page template has an iparsys at the top left column specifically designed to house the Left Navigation and propagate it down the site hierarchy.

When the component is dropped, the author must select a starting path, which typically should be the same page that the Left Navigation component was dropped in. After this configuration, the component scans all the children pages down to the second level and populates the navigation links with the titles and links to the respective child pages:

Rearranging the order of the sub pages in the site hierarchy would also reflect on the order of navigation links in the Left Navigation.

Additionally, if certain pages on the site that are on the same level (sibling) of the 1st and 2nd level child pages (i.e. Activity Services page or Running Data page), it will automatically show in the navigation. To prevent this from happening, the author can toggle the "Hide in Navigation" option in the Page Properties of the given child page.

Dec 2015

Left Navigation

General Page Information

Page title CMS-controlled.
Page URL  

How page was reached

  1. User entered URL directly.
  2. User arrived from external search.
  3. User navigates via the Left Navigation to access sub pages


  1. n/a


API docs – PSD:



Other notes


Analytics Describe analytics tagging for the page

User Interface  

Left Navigation Component – API Docs Activity Services


API Docs Page – Default


API Docs Page – Hover State


Console Page




API Docs Page – Brand Guidelines



Functional Notes







Optional / Required

Design/Edit Mode

CMS Component/Field Label Naming Suggestions

CMS Considerations



Left Navigation Component Load
  1. This component is dynamically generated based on the page structure hierarchy the author has defined in CQ 
  2. The order of navigation items are governed by the page order of the page structure (crawling page based on the child nodes) 


    1. The author can rearrange the order of the items displayed in the Left Navigation by rearranging the page order in CQ
  3. CQ Dialog has one element to call out the starting point of what the component should display
  4. Allow the ability to not display a navigational item in page properties (leverage page property of the page) 
  5. User can see this component in pre-authenticated state on Three-Column Page template such as API Docs listing pages or Brand guidelines on 
  6. User can view categories with the main section of the page content
  7. User can expand and collapse the main section to view respective sub-categories within each section
  8. Main body content area page reflects the selected sub-category item from the Left Navigation


No min/max # of items (based on author's governance)

Editable in Edit mode.

Design (CSS and Javascript) code changes will be implemented and deployed by designer/developer


Provide contextual guidance for content authors.


1 Category Header Text Load
  1. Display the Header title of the docs category name that is automatically populated by the Main navigation items under the Primary Navigation


    1. Allow the author to overwrite the Category Name
  2. In current usage, the header corresponds to one of the Doc categories that the end-user has selected from the main navigation item: Docs from Primary Navigation
  3. For Docs Primary navigation menu, it currently consists of the following categories, in which the Header field is populated from one of these categories:


    1. Get STarted
    2. API Docs
    3. Brand Guidelines
Required Automatically populated by Primary Navigation      
  1. Upon hovering any of the Header will highlight the chosen item in the menu list in orange text
  2. Only one item would be at hover state each time. (The visual is just showing a sample of how hover state looks like, it is not a true representation that all the links being highlighted at once)
  3. Displays the container in a lighter shade#F1F1F5 in top and mid section
    @start-color: #f1f1f5; @mid-color: #f1f1f5; @color-stop: 60%; @end-color: #e6e6ec
  1. If the user has moved to another sub-page, the left nav can be used to get back to the Category page.
  2. The Category Header is persistent and maintain integrity for all the sub-pages


    1. E.g. API DOCS should be displayed whether the user has selected Activity Services or Test Console. The selected page title in the left nav will be highlighted in black.
2 Sub-Category/ Page Title Text Load
  1. Display the sub-category Page title from Page properties of that page, it is automatically populated based on the page structure
  2. Each Detail page is a page defined within CQ
  3. The first Page section should be expanded at default
  4. Can consist of more than 1 Page title for end user to navigate to other Docs pages if there are multiple sub-categories within the API Doc category (e.g. Activity Services, Other Services)


No min/max

  1. Upon hovering any of the text will highlight the text in orange (#fa5400)
  2. Only one item would be at hover state each time. (The visual is just showing a sample of how hover state looks like, it is not a true representation that all the links being highlighted at once)



  1. Upon click on the Page Title will display the page content of the selected page on the right side and expand the sections list underneath this page in the Left Navigation
  2. If the viewing page is already on collapse the section and hide the list of Section headings if it is already expanded (minus sign)
  3. Upon click again will expand the section with the list of headings
3 Section Heading Title Text Load
  1. Display a list of the Page Title for each of the Detail Pages that belong within the category
  2. For example, Activities Services category consists of the following sections:


    1. Aggregate Sport Data
    2. List Activities
    3. Activities by Experience Type
    4. Activity Detail
    5. GPS Data
  3. The Section heading should correspond to each of the items listed in theAggregate Page List component in the main body of the page
  4. The list in the Left Nav is generated


No min/max

3a Hover State   Hover
  1. Upon hovering any of the Section Heading will highlight the chosen item in the menu list in orange text
  2. Only one item would be at hover state each time. (The visual is just showing a sample of how hover state looks like, it is not a true representation that all the links being highlighted at once)
3b Selected State   Click
  1. Upon clicking any of the Section heading or any title in the Left NAv will display the selected item in a highlighted state (black).  


    1. If the selected menu item is a section on the right, the main body of the page will reflect that tile.  
    2. If it is a bevel link off to refresh page content, then the detail page title will reflect the selected state.
4 Link Title Text Load
  1. Display page title of the additional pages that can be navigated within the Left Nav, it may be a link off destination or another category page hierarchy (e.g. Test Console)
  2. Can be displayed with the #6 Bevel arrow


No min/max

4a     Hover
  1. Upon hovering the text displays the upper part of the container in a lighter shade #F1F1F5 and the text in orange
    @start-color: #f1f1f5; @mid-color: #f1f1f5; @color-stop: 60%; @end-color: #e6e6ec



(not shown)     Click
  1. Upon clicking/selecting the items with the bevel button refresh the page with respective content
  2. The selected item on the Left Nav will be shown in highlighted state in black.
5a Expanded State (Minus Sign) Style Load/Click
  1. Expanded state/Minus Sign indicates the page section has been expanded
  2. Upon end user's discretion to expand or open any section.
  3. The remaining Doc Pages should be collapsed
  4. More than one section can be expanded at any given time for comparison
  5. Display the expand or collapse sign options if there are sub-section/detail pages within the category page
  6. Upon clicking it will revert to display the opposite sign (plus sign) and collapse to only display the category title

Collapsed State

(Plus Sign)

Style Load/Click
  1. Collapsed state/Plus Sign indicates the page section has been collapsed and has sub-section/detail pages available within the category
  2. Display the expand or collapse option if there are sub-section/detail pages within the category page
  3. Upon clicking it will revert to display the opposite sign (minus sign) and expand to display the category title and its sub-section titles
6 Bevel Style Load/Click
  1. Display the Bevel if the content is linking off to a new page content
  2. Upon click will refresh the page with the respective content for the selected item
  1. Upon hovering the bevel hover state displays the upper part of the container in a lighter shade #F1F1F5 and the text in orange
    @start-color: #f1f1f5; @mid-color: #f1f1f5; @color-stop: 60%; @end-color: #e6e6ec
7 Link List Component Load
  1. Display the component
  2. This component can be displayed beneath the Left Navigation component or right hand rail
  3. It is not part of the Left Navigationcomponent.

CQ Technical Specifications

CQ component configuration

Item Value
Relative Path /apps/nike-developer-cq/components/content/leftNavigation
jcr:title Left Navigation
jcr:description  Left Navigation Component
jcr:PrimaryType cq:Component


Dialog field definitions

Required Optional (by field type)
Help & Label Fields


Tab Dialog Field Set

Field Label



Default Value

Available values and/or default value

Field Length

Extended Validation or Field behavior

Sub Label Description
1 1 Left Navigation


pathfield N Current Page        

Select the path of the top level page from which to collect the sub-pages as navigation links. This component gathers sub-pages two levels deep.

Dec 2015