The Personal Trainer app already has a predefined workout and a list of 12 exercises. We need to seed the collections with this data.

Open seed.js from Lesson04/checkpoint1/app/js from the companion codebase. It contains the seed JSON script and detailed instructions on how to seed data into the MongoLab database instance.

Once seeded, the database will have one workout in the workouts collection and 12 exercises in the exercises collection. Verify this on the MongoLab site, the collections should show this:

Everything has been set up now, let's start our discussion with the $http service and implement workout/exercise persistence for the Personal Trainer app.

To pull exercise and workout lists from the MongoLab database, we have to rewrite our WorkoutService service methods, getExercises and getWorkouts.

Open services.js from app/js/shared and change the getExercises function to this:

service.getExercises = function () {
  var collectionsUrl = "https://api.mongolab.com/api/1/databases/<dbname>/collections";
  return $http.get(collectionsUrl + "/exercises", {
        params: { apiKey: '<key>'}
  });
};

Replace the tokens: <dbname> and <key> with the DB name and API key of the database that we provisioned earlier in the Lesson.

Also remember to add the $http dependency in the WorkoutService declaration.

The new function created here just builds the MongoLab URL and then calls the $http.get function to get the list of exercises. The first parameter we have is the URL to connect to and the second parameter is the config object.

The params property of the config object allows us to add query string parameters to the URL. We add the API key (?apiKey=98dkdd) as a query string for API access.

Now that the getExercises function is updated, and the new implementation returns a promise, we need to fix the upstream callers.

Open exercise.js placed under WorkoutBuilder and fix the ExerciseListController by replacing the existing init function implementation (the code inside init) with these lines:

WorkoutService.getExercises().success(function (data) {
    $scope.exercises = data;
});

We use the HTTP promise success callback to bind the exercises list in a controller. We can clearly observe the asynchronous behavior of $http and the promise-based callback in action as we set the exercises data after receiving a server response in a callback function.

Go ahead and load the exercise list page (#/builder/exercises) and make sure the exercise list is loading from the server. The browser network logs should log requests such as this:

Exercises are loading fine, but what about workouts? The workout list page can also be fixed on similar lines.

Update the getWorkouts function of WorkoutService to load data from the server. The getWorkouts implementation is similar to getExercises except that the collection name now becomes workouts. Then fix the init function of WorkoutListController along the same lines as the preceding init function and we are done.

That was easy! We can fix all other get scenarios in a similar manner. But before we do that, there is still scope to improve our implementation.

The first problem with getExercises/getWorkouts is that the DB name and API key are hardcoded and will cause maintenance issues in the future. The best way is to inject these values into WorkoutService through some kind of mechanism.

With our past experience and learnings, we know that, if we implement this service using provider, we can pass configuration data required to set up the service at the configuration stage of app bootstrapping. This allows us to configure the service before use. Time to put this theory to practice!

Implementing the WorkoutService provider

Implementing WorkoutService as a provider will help us to configure the database name and API key for the service at the configuration stage.

Copy and replace the updated WorkoutService definition from the services.js file in Lesson04/checkpoint1/app/js/shared. The service has now been converted into a provider implementation.

The service has a configure method that sets up the database name, the API key, and the collection URL address, as given here:

this.configure = function (dbName, key) {
database = database;
   apiKey = key;
   collectionsUrl = apiUrl + dbName + "/collections";
}

The functions: setupInitialExercises, setupInitialWorkouts, and init have also been removed as the data will now come from the MongoLab server.

The implementation of the getExercise and getWorkouts functions has been updated to use the configured parameters:

service.getExercises = function () {
  return $http.get(collectionsUrl + "/exercises",
                   { params: { apiKey: apiKey } });
};

And finally, the service object creation has been moved into the $get function of the provider. $get is the factory function responsible for creating the actual service.

Let's update the config function of the app module and inject the MongoLab configuration into WorkoutService (using WorkoutServiceProvider).

Open the app.js file, inject the new provider dependency WorkoutServiceProvider with the other provider dependencies, and call its configure method with your database name and API key:

WorkoutServiceProvider.configure("<mydb>", "<mykey>");

We now have a better WorkoutService implementation as it allows the calling code to configure the service before use.

The provider implementation may look overtly complex as this could be achieved by creating a constant service like this:

angular.module('app').constant('dbConfig', {
    database: "<dbname>",
    apiKey: "<apikey>"
});

And then inject the implementation into the existing WorkoutService implementation.

The advantage of the provider approach is that the configuration data is not globally exposed. Had we used a constant service such as dbConfig, any other service/controller could have got hold of the database name and API key by injecting the dbConfig service, which would be less than desirable.

The preceding provider refactoring is still not complete and we can verify this by refreshing the workout list page. There will be an unknown provider WorkoutServiceProvider error in the browser developer console.

We have just hit a bug with Angular that causes the config function module to execute before provider registration. This happened because the script registration for app.js precedes the service.js registration in index.html.

There is already a bug (https://github.com/angular/angular.js/issues/7139) logged against this issue and the current workaround is to call the config function at the end, after all provider/service registrations. This requires us to move the config function implementation to a new file.

Note

There was this issue while writing this Lesson. The newer versions of Angular 1.3 and above have fixed this issue. We will still continue with the approach outline given next as it works irrespective of the version of Angular.

Copy the updated app.js and config.js (new file) files from Lesson04/checkpoint1 and update your local copy. Once copied, update the configure function of WorkoutServiceProvider in the config.js file with your database name and API key. And finally, add a reference to config.js in the script declaration section of index.html at the end.

Refresh the workout/exercise list page and the workout and exercise data is loaded from the database server.

Note

Look at the complete implementation in Lesson04/checkpoint1 if you are having difficulty in retrieving/showing data.

Also remember to replace the database name and API key before running the code from checkpoint1.

This looks good and the lists are loading fine. Well, almost! There is a small glitch in the workout list page. We can easily spot it if we look carefully at any list item (in fact there is only one item):

The workout duration calculations are not working anymore! What could be the reason? We need to look back on how these calculations were implemented. The WorkoutPlan service (in model.js) defines a function totalWorkoutDuration that does the math for this.

The difference is in terms of the workout array that is bound to the view. In the previous Lesson, we created the array with model objects that were created using the WorkoutPlan service. But now, since we are retrieving data from the server, we bind a simple array of JavaScript objects to the view, which for obvious reasons has no calculation logic.

We can fix this problem by mapping a server response into our model class objects and returning that to any upstream caller.

Mapping server data to our model and vice versa may be unnecessary if the model and server storage definition match. If we look at the Exercise model class and the seed data that we have added for the exercise in MongoLab, they do match and hence mapping becomes unnecessary.

Mapping server response to model data becomes imperative if:

WorkoutPlan is a prime example of an impedance mismatch between a model representation and its storage. Look at the following screenshot to understand these differences:

The two major differences between a model and server data are as follows:

This clearly means loading and saving a workout requires model mapping. And for consistency, we plan to map data for both the exercise and the workout.

Change the getExercises implementation in WorkoutService to this:

service.getExercises = function () {
    return $http.get(collectionsUrl + "/exercises", {
        params: { apiKey: apiKey}
    }).then(function (response) {
        return response.data.map(function (exercise) {
            return new Exercise(exercise);
        })});
};

And since the return value for the getExercises function now is not a promise object returned by $http (see the following discussion) but a standard promise, we need to use the then function instead of the success function wherever we are calling getExercises.

Change the init implementation in both ExercisesNavController and ExerciseListController to this:

var init = function () {
WorkoutService.getExercises().then(function (data) {
    $scope.exercises = data;
});
};

Look back at the highlighted code for the updated getExercises implementation. There are a number of interesting things going on here that you should understand:

Before we continue any further, let's learn a bit more about promise chaining with some simpler examples. It's a very useful and powerful concept.

Promise chaining is about feeding the result of one promise resolution into another promise. Since promises wrap asynchronous operations, this chaining allows us to organize asynchronous code in a chained manner instead of nested callbacks. We saw an example of promise chaining earlier. The exercises were retrieved (the first asynchronous operation), transformed (the second asynchronous operation), and finally bound to the view (the third asynchronous operation), all using promise chaining. The previous diagram also highlights this.

Such chaining allows us to create chains of any length as long as the methods involved in the chain return a promise. In this case, both the $http.get and then functions return a promise.

Let's look at a much simpler example of chaining in action. The code for this example is as follows:

var promise = $q.when(1);
var result = promise
.then(function (i) { return i + 1;})
   .then(function (i) { return i + 1;})
   .then(function (i) { return i + 1;});
   .then(function (i) { console.log("Value of i:" + i);});

The preceding code uses promise chaining, and every chained function increments the value passed to it and passes it along to the next promise in the chain. The final value of i in the last then function is 4.

As described earlier, such chaining is possible due to the fact that the then function itself returns a promise. This promise is resolved to the return value of either the success or error callback. Look at the preceding code; there is a return statement in every success callback (except the last).

The behavior of promise chaining when it comes to the error callback may surprise us. An example will be the best way to illustrate that too. Consider this code:

var errorPromise = $q.reject("error");

var resultError = errorPromise.then(function (data) {
    return "success";
}, function (e) {
    return "error";
});
resultError.then(function (data) {
    console.log("In success with data:" + data);
}, function (e) {
    console.log("In error with error:" + e);
});

The $q.reject function creates a promise that is rejected with the value as error. Hence, the resultError promise is resolved with the return value error (return error).

The question now is, "What should the resultError.then callback print?" Well, it prints In success with data: error, since the success callback is invoked not error. This happened because we used a standard return call in both the success and error callbacks for errorPromise.then (or resultError).

If we want the promise chain to fail all along, we need to reject the promise in every error callback. Change the resultError promise to this:

var resultError = errorPromise.then(function (data) {
    return "success";
}, function (e) {
    return $q.reject(e);
});

The correct error callback in the next chained then is called, and the console logs In error with error: error.

By returning $q.reject(e) in the error callback, the resolved value of the resultError promise will be a rejected promise ( $q.reject returns a promise that is always rejected).

Promise chaining is a very powerful concept, and mastering it will help us write more compact and well organized code. We will be extensively using promise chaining throughout this Lesson to handle server response and to transform and load data.

Let's get back to where we left off, loading exercise and workout data from the server.

As we fixed the getExercises implementation in WorkoutService earlier, we can implement other get operations for exercise- and workout-related stuff. Copy the service implementation for the getExercise, getWorkouts, and getWorkout functions of WorkoutService from Lesson02/checkpoint2/app/js/shared/services.js.

Pay special attention to implementation for both the getWorkouts and getWorkout functions because there is a decent amount of data transformation happening in both the functions due to the model and data storage format mismatch.

The getWorkouts function is similar to getExercises except it creates the WorkoutPlan object and the exercises array is not mapped to the list of class objects of Exercises, instead server structure of {name:'name', duration:value} is used as it is.

The getWorkout function implementation involves a good amount of data mapping. This is how the getWorkout function now looks:

service.getWorkout = function (name) {
  return $q.all([service.getExercises(), $http.get(collectionsUrl
    + "/workouts/" + name, { params: { apiKey: apiKey } })])
    .then(function (response) {
        var allExercises = response[0];
        var workout = new WorkoutPlan(response[1].data);
        angular.forEach(response[1].data.exercises,
          function (exercise) {
            exercise.details = allExercises.filter(function (e) {
            return e.name === exercise.name; })[0];
          });
       return workout;
    });
};

There is a lot happening inside getWorkout that we need to understand.

The getWorkout function starts the execution by calling the $q.all function. This function is used to wait over multiple promise calls. It takes an array of promises and returns a promise. This aggregate promise is resolved or rejected (an error) when all promises within the array are either resolved or at least one of the promises is rejected. In the preceding case, we pass an array with two promises: the first is the promise returned by the service.getExercises function and the second is the http.get call (to get the workout with a specific identifier).

The $q.all function callback parameter response is also an array corresponding to the resolved values of the input promise array. In our case, response[0] contains the list of exercises and response[1] contains workout collection responses received from the server (response[1].data contains the data part of the HTTP response).

Once we have the workout details and the complete list of exercises, the code just after this updates the exercises array of the workout to the correct Exercise class object. It does this by searching the allExercises array for the name of the exercise as available in the workout.exercises array item returned from the server. The end result is that we have a complete WorkoutPlan object with the exercises array setup correctly.

These WorkoutService changes warrant fixes in upstream callers too. We have already fixed both ExercisesNavController and ExerciseListController. Fix the WorkoutListController object along similar lines. The getWorkout and getExercise functions are not directly used by the controller but by our builder services. Let's now fix the builder services together with the workout/exercise detail pages.

We fix the workout detail page and I will leave it to you to fix the exercise detail page yourself as it follows a similar pattern.

ExeriseNavController, used in the workout detail page navigation rendering, is already fixed so let's jump onto fixing WorkoutDetailsController.

WorkoutDetailController does not load workout details directly but is dependent on the resolve route (see route configuration in config.js) invocation; when the route changes, this injects the selected workout (selectedWorkout) into the controller. The resolve selectedWorkout function in turn is dependent upon WorkoutBuilderService to load the workout, new or existing. Therefore the first fix should be WorkoutBuilderService.

The function that pulls workout details is startBuilding. Update the startBuilding implementation to the following code:

service.startBuilding = function (name) {
    var defer = $q.defer();
    if (name) {
        WorkoutService.getWorkout(name).then(function (workout) {
            buildingWorkout = workout;
            newWorkout = false;
            defer.resolve(buildingWorkout);
        });
    } else {
        buildingWorkout = new WorkoutPlan({});
        defer.resolve(buildingWorkout);
        newWorkout = true;
    }
    return defer.promise;
};

In the preceding implementation, we use the $q service of the Promise API to create and resolve our own promise. The preceding scenario required us to create our own promise because creating new workouts and returning is a synchronous process, whereas loading the existing workout is not. To make the return value consistent, we return promises in both the new workout and edit workout cases.

To test the implementation, just load any existing workout detail page such as 7minWorkout under #/builder/workouts/. The workout data should load with some delay.

This is the first time we are actually creating our own promise and hence it's a good time to delve deeper into this topic.

Creating and resolving a standard promise involves the following steps:

The preceding startBuilding function follows the same pattern.

An interesting thing about the preceding startBuilding implementation is that, in the case of the else condition, we immediately resolve the promise by calling defer.resolve with a new workout object instance, even before we have returned a promise to the caller. The end result is that, in the case of a new workout, the promise is immediately resolved once the startBuilding function completes.

The ability to create and resolve our own custom promise is a powerful feature. Such an ability is very useful in scenarios that involve invocation and coordination of one or more asynchronous methods before a result can be delivered. Consider a hypothetical example of a service function that gets product quotes from multiple e-commerce platforms:

getProductPriceQuotes(productCode) {
    var defer = $q.defer()
    var promiseA = getQuotesAmazon(productCode);
    var promiseB = getQuotesBestBuy(productCode);
    var promiseE = getQuotesEbay(productCode);
    $q.all([promiseA, promiseB, promiseE])
      .then(function (response) {
         defer.resolve([buildModel(response[0]),
         buildModel(response[1]), buildModel(response[2])]);
        });
    defer.promise;
}

The getProductPriceQuotes service function needs to make asynchronous requests to multiple e-commerce sites, collate the date received, and return the data to the user. Such a coordinated effort can be managed by the Promise/defer API. In the preceding sample, we use the $q.all function that can wait on multiple promises to get resolved. Once all the remote calls are complete, the then success callback is invoked. The hypothetical buildModel function is used to build a common Quote model as the response can vary from one e-commerce platform to another. The defer.resolve function finally collates the new model data and returns it in an array. A well-coordinated effort!

When it comes to creating and using the defer/Promise API there are some rules/guidance that come in handy. These include:

Other than creating our own promise and resolving it, there is another way to achieve the same behavior. We can use another Promise API function: $q.when.

when(value);

service.startBuilding = function (name) {
    if (name) {
        return WorkoutService.getWorkout(name)
         .then(function (workout) {
            buildingWorkout = workout;
            newWorkout = false;
            return buildingWorkout;
         });
    } else {
        buildingWorkout = new WorkoutPlan({});
        newWorkout = true;
        return $q.when(buildingWorkout);
    }
};

Fixing startBuilding is enough to make the workout detail page load data. We can verify this and make sure the new workout and existing workout scenarios are loading data correctly.

We do not need to write a callback implementation in our WorkoutDetailController. Why? Because the route resolve configuration takes care of it. We touched upon the resolve route in the last Lesson when we used it to inject the selectedWorkout object into WorkoutDetailController. Let's try to understand how this refactoring for asynchronous calls and promise implementation has affected the resolve function.

return WorkoutBuilderService.startBuilding($route.current.params.id);

Taking the bottom-up approach, the first thing that needs to be fixed is WorkoutService. Update the addWorkout function as shown in the following code:

service.addWorkout = function (workout) {
  if (workout.name) {
    var workoutToSave = angular.copy(workout);
    workoutToSave.exercises = 
    workoutToSave.exercises.map(function (exercise) {
         return {
                name: exercise.details.name,
                duration: exercise.duration
         }
      });
    workoutToSave._id = workoutToSave.name;
    return $http.post(collectionsUrl + "/workouts", workoutToSave,
 { params: { apiKey: apiKey }})
    .then(function (response) { return workout });
}}

In getWorkout, we had to map data from the server model to our client model; the reverse has to be done here. Since we do not want to alter the model that is bound to the view, the first thing we do is make a copy of the workout.

Next, we map the exercises array (workoutToSave.exercises) to a format that is more compact for server storage. We only want to store the exercise name and duration in the exercises array on the server.

We then set the _id property as the name of the workout to uniquely identify it in the database of the Workouts collection.

Lastly, we call the post function of the $http API, passing in the URL to connect to, data to send, and extra query string parameter (apiKey). The last return statement may look familiar as we again perform promise chaining to return the workout object as part of the promise resolution.

Why not try to implement the update operation? The updateWorkout function can be fixed in the same manner, the only difference being that the $http.put function is required:

return $http.put(collectionsUrl + "/workouts/" + workout.name, workoutToSave, { params: { apiKey: apiKey } });

The preceding request URL now contains an extra fragment (workout.name) that denotes the identifier of the collection item that needs to be updated.

The last operation that needs to be fixed is deleting the workout. Here is a trivial implementation where we call the $http.delete API to delete the workout referenced by a specific URL:

service.deleteWorkout = function (workoutName) {
    return $http.delete(collectionsUrl + "/workouts/" + 
    workoutName, { params: { apiKey: apiKey } });
};

With that it's time now to fix WorkoutBuilderService and WorkoutDetailController. The save function of WorkoutBuilderService now looks like this:

service.save = function () {
    var promise = newWorkout ? WorkoutService.addWorkout(buildingWorkout) : WorkoutService.updateWorkout(buildingWorkout);
    promise.then(function (workout) {
        newWorkout = false;
    });
    return promise;
};

Most of it looks the same as it was earlier except that newWorkout is flipped in the then success callback and this returns a promise.

Finally, WorkoutDetailController also needs to use the same callback pattern for handling save and delete, as shown here:

$scope.save = function () {
    $scope.submitted = true; // Will force validations
    if ($scope.formWorkout.$invalid) return;
    WorkoutBuilderService.save().then(function (workout) {
        $scope.workout = workout;
        $scope.formWorkout.$setPristine();
        $scope.submitted = false;
    });
}
service.delete = function () {
   if (newWorkout) return; // A new workout cannot be deleted.
   return WorkoutService.deleteWorkout(buildingWorkout.name);
}

And that's it. We can now create new workouts, update existing workouts, and delete them too. That was not too difficult!

Let's try it out; open the new Workout Builder page, create a workout, and save it. Also try to edit an existing workout. Both scenarios should work seamlessly.

There is something interesting happening on the network side while we make POST and PUT requests to save data. Open the browsers network log console (F12) and see requests being made. The log looks something like this:

There is an OPTIONS request made to the same endpoint before the actual POST is done. The behavior that we witness here is termed as a prefight request. And this happens because we are making a cross-domain request to api.mongolab.com.

It is important to understand the cross-domain behavior of the HTTP request and the constructs AngularJS provides to make cross-domain requests.

Cross-domain requests are requests made for resources in a different domain. Such requests when originated from JavaScript have some restrictions imposed by the browser; these are termed as same-origin policy restrictions. This restriction stops the browser from making AJAX requests to domains that are different from the script's original source. The source match is done strictly based on a combination of protocol, host, and port.

For our own app, the calls to https://api.mongolab.com are cross-domain invocations as our source code hosting is in a different domain (most probably something like http://localhost/....).

There are some workarounds and some standards that help relax/control cross-domain access. We will be exploring two of these techniques as they are the most commonly used ones. These are as follows:

A common way to circumvent this same-origin policy is to use the JSONP technique.

The JSONP mechanism of remote invocation relies on the fact that browsers can execute JavaScript files from any domain irrespective of the source of origin, as long as the script is included via the <script> tag. In fact, a number of framework files that we are loading in Personal Trainer come from a CDN source (ajax.googleapis.com) and are referenced using the script tag.

In JSONP, instead of making a direct request to a server, a dynamic script tag is generated with the src attribute set to the server endpoint that needs to be invoked. This script tag, when appended to the browser's DOM, causes a request to be made to the target server.

The server then needs to send a response in a specific format wrapping the response content inside a function invocation code (this extra padding around response data gives this technique the name JSONP).

The $http.jsonp function of AngularJS hides this complexity and provides an easy API to make JSONP requests. The jsFiddle link at http://jsfiddle.net/cmyworld/v9y4uby2/ highlights how JSONP requests are made. jsFiddle uses the Yahoo Stock API to get quotes for any stock symbol.

The getQuote method in the fiddle looks like this:

$scope.getQuote = function () {
  var url = "https://query.yahooapis.com/v1/public/yql?q=select_*_from_yahoo.finance.quote_where_symbol_in_(%22" + $scope.symbol + "%22)&format=json&env=store%3A%2F%2Fdatatables.org%2Falltableswithkeys&callback=JSON_CALLBACK";

$http.jsonp(url).success(function (data) {
    $scope.quote = data;
});
};

To make a JSONP request using AngularJS, the jsonp function requires us to augment the original URL with an extra query string parameter callback=JSON_CALLBACK verbatim. Internally, the jsonp function generates a dynamic script tag and a function. It then substitutes the JSON_CALLBACK token with the function name generated and makes the remote request.

Open the preceding jsFiddle page and enter symbols such as GOOG, MSFT, or YHOO to see the stock quote service in action. The browser network log for requests looks like this:

https://query.yahooapis.com/... &callback=angular.callbacks._1

Here, angular.callbacks._1 is the dynamically generated function. And the response looks like this:

angular.callbacks._1({"query": …});

The response is wrapped in the callback function. Angular parses and evaluates this response, which results in the invocation of the angular.callbacks._1 callback function. Then, this function internally routes the data to our success function callback.

Hope this explains how JSONP works and what the underlying mechanism of a JSONP request is. But JSONP has its limitations, as given here:

At the end, we must realize JSONP is more of a workaround that a solution. As we moved towards Web 2.0, where mashups became commonplace and more and more service providers decided to expose their API over the Web, a far better solution/standard emerged: CORS.

Cross-origin resource sharing (CORS) provides a mechanism for the web server to support cross-site access control, allowing browsers to make cross-domain requests from scripts. With this standard, the consumer application (such as Personal Trainer) is allowed to make some types of requests termed as simple requests without any special setup requirements. These simple requests are limited to GET, POST (with specific MIME types), and HEAD. All other types of requests are termed as complex requests.

For complex requests, CORS mandates that the request should be preceded with a HTTP OPTIONS request (also called a preflight request), that queries the server for HTTP methods allowed for cross-domain requests. And only on successful probing is the actual request made.

The best part about CORS is that the client does not have to make any adjustment as in the case of JSONP. The complete handshake mechanism is transparent to calling code and our AngularJS AJAX calls work without any hitch.

CORS requires configurations to be made on the server, and the MongoLab servers have already been configured to allow cross-domain requests. The preceding POST request to MongoLab caused the preflight OPTIONS request.

We have now covered the $http service and cross-domain invocation topics. The next topic that needs our attention is the $resource service.