Building SPA using AngularJS – Part 2

This is the second part of Building SPA using AngularJS Series. The topics we’ll cover are:

• Building SPA using AngularJS – Part 1
• Building SPA using AngularJS – Part 2  (This Post)
• Building SPA using AngularJS – Part 3

Update (2014-May-5) New post which covers adding GulpJS as Task Runner for our AngularJS application:

• AngularJS with touch of GulpJS

Update (2014-June-1) New post which covers Implementing AngularJS Token Authentication using ASP.NET Web API 2 and Owin middleware:

• Token Based Authentication using ASP.NET Web API 2, Owin, and Identity

Building SPA using AngularJS – Part 2

In the previous post we have done all work needed to bootstrap our app with Angular, now we’ll focus on implementing the use cases we mentioned in the introductory post, here we’ll see how powerful and fun working with Angular can be. I will start building those requirements from bottom to top, so we’ll start by services then we move up to the view.

Step 1: Adding service to communicate with Foursquare API:

As we discussed before, services in Angular are singleton objects responsible of doing certain tasks, or they can be used for sharing business logic. To use those custom created services we just need to specify service name in controller, filters, directive, etc… and Angular will inject those singleton objects. Angular is built in a way that it will be able to manage those custom created services so we can use them any place in our app.

There are different ways to create Angular Services, two of them are Service or Factory methods, both will provide us with a singleton shared object, and the only difference is how they are created, I won’t dig more into differences and we’ll use Factory for creating Services. You can read this informative stackoverflow question which highlights the differences.

So let’s add new JS file named “placesExplorerService.js” to the folder “app–>services”, this service will be responsible to send HTTP requests to Foursquare explore places API. For more information about Foursquare explore places API and how you can get your own clientID and secret you can check the official documentation.

Now open the file and paste the code snippet below:

By looking at the code above you will notice that creating a factory is simple, all you need to do is calling app.factory() function where app is shared variable declared in app.js file holding our module “FoursquareApp”.

As well you will notice that we are injecting built-in Angular service named “$resource” into our service, this service won’t work until we inject “ngResource” module to our “FoursquareApp” module, this already done into file app.js.

Basically the built-in $resource is a service which allow us to interact with RESTful data sources, we can use another lower level built-in service called $http but in our case $resource service is sufficient.

Now we need to configure the $resource service by passing the params needed by explore places API, you can check the needed mandatory params by visiting their documentation, what is worth mentioning here that :action param will be translated to a part of the request URL and any another params will be treated as query strings (key, value) pairs. For sure we need extra params to pass it for the API, such as the nearby city and category to explore for. Those params will be sent from the controller, we’ll see this soon. Note: you can use those ClientID and Secret to follow up with this demo app, but I recommend to have your own CleintID and secret.

Do not forget to reference the newly created JS file at the bottom of our shell page (index.html) body.

Step 2: Implementing business logic in controller:

Now we’ll start implementing the functions and model needed to interact with our view “placesresults.html”, if you are following from the previous post, we’ve already created a controller named “placesExplorerController” with a single model (exploreNearby), now we need to expand the models and functions needed to build the app, I’ll paste most of the controller code below and will explain what is going in the next paragraph:

• We’ve injected the “placesExplorerService” and another built-in service named “$filter” into the controller.
• We’ve defined different model objects (exploreNearby, exploreQuery, places array, etc…) where they will be used for two-way data binding between our view “placesresults.html” and the model.
• After we injected the service “placesExplorerService”,  and as this code snippet:
  
  JavaScript

  placesExplorerService.get({ near: $scope.exploreNearby, query: $scope.exploreQuery, limit: $scope.pageSize, offset: offset }, function (placesResult) {});

  1	placesExplorerService.get({ near: $scope.exploreNearby, query: $scope.exploreQuery, limit: $scope.pageSize, offset: offset }, function (placesResult) {});

  
  we were able to issue HTTP GET request to the factory we created, note how we can pass any number of arguments to the get method, and all those arguments (i.e. near, query, limit, etc..) will be translated to query string (key, value) pairs, by having this we were able have a complete GET request with the needed params for server side pagination.
• We’ve used custom filter which allow us to filter for results returned, we’ll cover how to create filters soon.
• We have created a watch for filterValue, in simple words we’ve added listener for on the “filterValue” attribute of the scope, this listener gets fired when the value of this attribute has changed.
• We’ve added different functions needed to be called from the view, such as “doSearch()” which will be called on the explore button click, as well “pageChanged()” which will be called once the page at the pagination control change.
• Multiple helper functions have been added, those functions are used to build some thumbnails image source.

Now we need to add the filter which will allow users to filter results returned, we’ll be filtering by Place Name or Place Category.

Step 3: Adding custom filter:

To define a custom filter we need to add new JS file named “placeNameCategoryFilter.js” to the folder “app–>filters”, open the file and paste the code below:

Defining a filter is straight forward and it is like defining a factory, all we need to do is to call app.filter() function where app is shared variable declared in app.js file holding our module “FoursquareApp”. We can inject services in filters but in our case the filter is simple, it will accept an array of the places returned from Foursquare API, and filter value, then it will filter the places array for the name or category only, the result of this process is a new filtered places array.

To use this custom filter in “placesExplorerController” is simple, we need just to inject the built-in “$filter” service, then we are able to execute our custom filter by calling:

Step 4: Modifying Places Results View:

Till this point we have the service and controller ready, but we need to work on the view in order to project the results in nice way and enable pushing user inputs from the view back to the service, so let’s open the view “placesresults.html” and paste the code snippet below. Note I’m removing the Bootstrap classes to keep it simple, you can view the full html fragments at github.

Below is an explanation of what we did on this view:

• We’ve used ng-model with model “exploreNearby”, and “exploreQuery”, so once we change the text into the input fields, the models will get updated directly.
• We’ve wired the click event for the explore button with the function “doSearch()” in the controller by using ng-click directives. 
• We’ve used ng-repeat to iterate through the array of filtered places then we can bind the view with each place, notice how we created <li> tag for each place. 
• Inside ng-repeat we’re able to drill into single place data and print it on the view, for example to print place name we’ve used {{item.venue.name}}, as well we’re able to execute helper functions in this simple way: ng-src=”{{buildCategoryIcon(item.venue.categories[0].icon)}}
• We’ve used built-in filters for formatting decimal numbers {{item.venue.rating | number:1}}, you can find more infor about Angular built-in filters here.
• We’ve implemented pagination using Angular Bootstrap UI directive named “data-pagination“, by using this we’re able to implement server side pagination. This pagination control is flexible, you can check how to customize it here.
• We’ve added a link with title “Bookmark Place” which will be used for saving user favorite places, we’ll implement the function “bookmarkPlace()” in the next post.

What is left here is displaying the top 9 thumbnails for the place once the user click on place name, one good way to implement this is to use $modal service which allow us to open modal dialog on top of our search result page, in the next step we’ll add this modal.

 Step 5: Add modal view to view places images

The modal view is normal html view, so let’s add new file named “placesphotos.html” under “app–>views”, I won’t list view html here because its simple and you can check it on github.

To get the images, we need to make HTTP Get request to Foursquare API, this call is some how identical to the previous one, all we need to do here is to create new service named “placesPhotosService” which will be responsible to issue this Get request. So create new JS file named “placesPhotosService.js” under “app–>services”, you can check it’s code on github.

As we mentioned earlier each view has it’s unique controller, so we need to create new controller named “placesPhotosController”, so add new JS file named “placesPhotosController.js” under “app–>controllers”. You can check controller code on github.

Till this moment Angular is not aware that the new view and controller created are tied together, previously we did this using $routeProvider while booting up our application, but in the case of using $modal service we can inform Angular about this relation once we insentiate the modal, remember that we want to display the view as a modal not as partial view, take a look on the code snippet below inside “placesExplorerController”:

By looking at the code above, you will notice that we’ve injected the new service “placesPhotosService” into the controller so we can issue HTTP Get request, as well we’ve injected the service $modal which will be responsible to open the modal dialog. Once we receive the 9 thumbnails successfully from the API, we’ll call $modal.open and inject the template URL, and controller in the configuration section, once this is done Angular will be aware that this template is mapped to this controller. As well we’ve passed the place name and array of 9 thumbnails to the “placesPhotosController”. The final result will be as the image below:

In the next post we’ll add the last functionality in our application which will allow end users to bookmark their favorite places.

Source code is available on GitHub. Demo application is hosted on WindowsAzure.