• Download source - 241.3 KB

Introduction

In this tutorial, which has been extracted from the open access book Building Front-End Web Apps with AngularJS and Parse.com, we show how to build a minimal web application with the AngularJS framework and the cloud storage service Parse.com. Such an app is a front-end app, because most parts of the app's code are executed on the front-end, while only the persistent storage functionality is executed on the back-end server(s) in the cloud infrastructure managed by Parse.com. If you want to see how it works, you can run the minimal app discussed in this article from our server.

The minimal version of an AngularJS data management app discussed in this tutorial only includes a minimum of the overall functionality required for a complete app. It takes care of only one object type (Book) and supports the four standard data management operations (Create/Read/Update/Delete), but it needs to be enhanced by adding further important parts of the app's overall functionality:

• Part 2: Taking care of constraint validation

• Part 3: Managing unidirectional associations assigning authors and publishers to books

• Part 4: Managing bidirectional associations also assigning books to authors and to publishers

• Part 5: Handling subtype (inheritance) relationships in a class hierarchy

Background

We assume that the reader is already familiar with HTML and has some programming experience. For a short introduction to, or refresher of, JavaScript, please check the CodeProject article JavaScript Summary (about which a reader said that "In over 20 years programming, this is the single best overview of any language ever!").

Coding the App

The purpose of our example app is to manage information about books. That is, we deal with a single object type: Book, as depicted in the following figure:

What do we need for such an information management application? There are four standard use cases, which have to be supported by the application:

1. Create: Enter the data of a book that is to be added to the collection of managed books.
2. Read: Show a list of all books in the collection of managed books.
3. Update the data of a book.
4. Delete a book record.

These four standard use cases, and the corresponding data management operations, are often summarized with the acronym CRUD.

For entering data with the help of the keyboard and the screen of our computer, we can use HTML forms, which provide the user interface technology for web applications.

For maintaining a collection of persistent data objects, we need a storage technology that allows to keep data objects in persistent records on a secondary storage device, either locally or remotely. An attractive option for remote storage is using a cloud storage service, where data is stored in logical data pools, which may physically span multiple servers in a cloud infrastructure owned and managed by a cloud service company. A cloud storage service is typically reachable via a web API, which is often called a "REST API". For our minimal AngularJS app, we will use the cloud service platform Parse.com via its REST API.

Step 1 - Set Up the Folder Structure

In the first step, we set up our folder structure for the application. We pick a name for our app, such as "Public Library", and a corresponding (possibly abbreviated) name for the application folder, such as "publicLibrary". Then we create the following folder structure:

publicLibrary
|-- index.html
|-- js
|   |-- app.js
|   `-- controllers.js
|-- partials
|   |-- createBook.html
|   |-- deleteBook.html
|   |-- main.html
|   |-- showAllBooks.html
|   `-- updateBook.html
`-- src
    |-- angular-route.js
    `-- angular.js

In addition to the index.html file for starting the app, we have three sub-folders:

1. The js folder is used for all app-specific JavaScript files.

   • app.js has the task to define a name for our AngularJS app, to declare all dependences, also to organize the relationship between views, their corresponding controllers and even URLs.

   • controllers.js is used for implementing various functions.

2. The partials folder holds all HTML-files for different sub-views, which will be replaced by AngularJS mutually exclusively into the body of index.html.

3. The src folder holds all official libraries like angular.js and angular-route.js.

1.1. The Start Page

The entrance point of our web app, index.html, is used for including all files and creating an ng-view container element for rendering different views:

<!DOCTYPE html>
<html ng-app="publicLibraryApp">
<head>
  <meta charset="UTF-8" />
  <title>Public Library with AngularJS</title>
  <script src="src/angular.js"></script>
  <script src="src/angular-route.js"></script>
  <script src="js/app.js"></script>
  <script src="js/controllers.js"></script>
</head>
<body>
  <div ng-view="ng-view"></div>
</body>
</html>

The AngularJS attribute ng-app of the html element declares the root element of an AngularJS app, here with the name "publicLibraryApp", while the attribute ng-view (typically in a div) defines a container element for rendering view templates in the start page index.html. This approach allows sharing general static content, such as header and footer, among all views. View templates will be rendered into the ng-view div element according to a configuration file app.js.

1.2. Modules and Routes

The app.js file tells Angular the name of our app, defines dependencies, and manages the routes, controllers and URLs:

var publicLibraryApp = angular.module('publicLibraryApp',
    ['ngRoute', 'plControllers']);
publicLibraryApp.config(['$routeProvider', function ( $routeProvider) {
  $routeProvider
    .when('/main', {
      templateUrl: 'partials/main.html',
      controller: 'TestDatasController'
    })
    .when('/showAllBooks', {
      templateUrl: 'partials/showAllBooks.html',
      controller: 'BooksController'
    })
    .when('/createBook', {
      templateUrl: 'partials/createBook.html',
      controller: 'BooksController'
    })
    .when('/updateBook', {
      templateUrl: 'partials/updateBook.html',
      controller: 'BooksController'
    })
    .when('/deleteBook', {
      templateUrl: 'partials/deleteBook.html',
      controller: 'BooksController'
    })
    .otherwise({
      redirectTo: '/main'
    });
}]);

publicLibraryApp.run(['$http', function ( $http) {
  // Predefine the API's value from Parse.com
  $http.defaults.headers.common = {
    'X-Parse-Application-Id': 'Your_Application_ID',
    'X-Parse-REST-API-Key': 'Your_REST_API_Key'
  }
}]);

We define our app with the name "publicLibraryApp" and dependencies on the module plControllers (to be defined by us) and on the pre-defined AngularJS module ngRoute, which supports URL management providing routing, services and directives for AngularJS apps.

The module plControllers, which will collect all controllers of our app, is defined in the file js/controllers.js:

var plControllers = angular.module('plControllers', []);

After declaring dependencies, we configure our main module publicLibraryApp with publicLibraryApp.config for defining "routes", which are mappings from request URL paths to template/controller combinations, and with publicLibraryApp.run for providing application start-up information such as authentication credentials.

In conjunction with the ngView directive, application routes in AngularJS are declared via the $routeProvider, which is provided in module ngRoute to define a Route-ID for each view and corresponding controller.

For example, the third option of $routeProvider, .when('/createBook', ...) means that when the request URL path is "/createBook", the template partials/createBook.html will be rendered inside the ng-view div element and the app will be controlled by the user-defined controller BooksController.

1.3 The Start Page View Template main.html

When index.html is requested and the request URL path is neither of "/main", "/showAllBooks", "/createBook", "/updateBook" or "/deleteBook", then the $routeProvider calls otherwise(), which takes care that "/main", in combination with the TestDataController, is used as the default route.

<menu>
  <li><a href="#/showAllBooks">
    <button type="button">List all Books</button>
  </a></li>
  <li><a href="#/createBook">
    <button type="button">Add a new Book</button>
  </a></li>
  <li><a href="#/updateBook">
    <button type="button">Update a Book</button>
  </a></li>
  <li><a href="#/deleteBook">
    <button type="button">Delete a Book</button>
  </a></li>
  <li><button type="button" ng-click="clearDatabase()">
      Clear database
  </button></li>
  <li><button type="button" ng-click="createTestData()">
    Create test data
  </button></li>
</menu>

$scope.book = {
  "isbn": "",
  "title": "",
  "year": 0
};

headers: {
  'X-Parse-Application-Id': 'Your_Application_ID',
  'X-Parse-REST-API-Key': 'Your_REST_API_Key'
}

$http({
  headers: {...},
  method: 'GET|POST|...',
  url: 'aRequestUrl'
})
  .success( function () {...})
  .error( function () {...});

<h1>Public Library: List all books</h1>
<table ng-init="getAllBooks()">
  <thead><tr>
    <th>ISBN</th><th>Title</th><th>Year</th>
  </tr></thead>
  <tbody><tr ng-repeat="book in books">
    <td>{{book.isbn}}</td>
    <td>{{book.title}}</td>
    <td>{{book.year}}</td>
  </tr></tbody>
</table>

plControllers.controller('BooksController',
    ['$scope', '$http', function ( $scope, $http){
  ...
  $scope.getAllBooks = function () {
    $http({
      method: 'GET',
      url: 'https://api.parse.com/1/classes/Book'
    })
      .success( function( data){
        $scope.books = data.results;
      })
      .error( function( data) {
        alert("ERROR when getting all books", data);
      });
  };
  ...
}]);

<h1>Public Library: Create a new book record</h1>
<form>
  <div>
    <label>ISBN:
      <input type="text" name="isbn" ng-model="book.isbn" />
    </label>
  </div>
  <div>
    <label>Title:
      <input type="text" name="title" ng-model="book.title" />
    </label>
  </div>
  <div>
    <label>Year:
      <input type="number" name="year" ng-model="book.year" />
    </label>
  </div>
  <div>
    <button type="submit" name="commit" ng-click="addBook()">
      Save
    </button>
  </div>
</form>

plControllers.controller('BooksController',
    ['$scope', '$http', function ( $scope, $http){
  ...
  $scope.addBook = function () {
    $http({
      method: 'POST',
      url: 'https://api.parse.com/1/classes/Book',
      data: {
        isbn: $scope.book.isbn,
        title: $scope.book.title,
        year: $scope.book.year
      }
    })
      .success( function(){
        alert("SUCCESS: Create book");
        $scope.book = {};
      })
      .error( function( data){
        alert("ERROR: Create book", data);
      });
    };
  ...
}]);

<h1>Public Library: Update a book record</h1>
<form ng-init="getAllBooks()">
  <div ng-hide="book">
    <label>Select book:
      <select ng-model="book" ng-options="book.title for book in books">
        <option value="">---</option>
      </select>
    </label>
  </div>
  <div ng-show="book">
    <div>
      <label>ISBN:
        <output type="text" name="isbn" ng-bind="book.isbn" />
      </label>
    </div>
    <div>
      <label>Title:
        <input type="text" name="title" ng-model="book.title" />
      </label>
    </div>
    <div>
      <label>Year:
        <input type="number" name="year" ng-model="book.year" />
      </label>
    </div>
    <div>
      <button type="submit" name="commit" ng-click="updateBook()">
        Save Changes
      </button>
    </div>
  </div>
</form>

plControllers.controller('BooksController',
    ['$scope', '$http', function ( $scope, $http){
  ...
  $scope.updateBook = function () {
    var bookUrl = 'https://api.parse.com/1/classes/Book/';
    $http({
      method: 'PUT',
      url: bookUrl + $scope.book.objectId,
      data: {
        isbn: $scope.book.isbn,
        title: $scope.book.title,
        year: $scope.book.year
      }
    })
    .success( function () {
      alert("SUCCESS: Update book");
      $scope.book = {};
    })
    .error( function ( data) {
      alert("ERROR: Update book", data);
    });
  };
  ...
}]);

<h1>Public Library: Delete a book record</h1>
<form ng-init="getAllBooks()">
  <div ng-hide="book">
    <label>Select book:
      <select ng-model="book" ng-options="book.title for book in books">
        <option value="">---</option>
      </select>
    </label>
  </div>
  <div ng-show="book">
    <div>
      <label>ISBN:
        <output type="text" name="isbn" ng-bind="book.isbn" />
      </label>
    </div>
    <div>
      <label>Title:
        <output type="text" name="title" ng-bind="book.title" />
      </label>
    </div>
    <div>
      <button type="submit" name="commit" ng-click="destroyBook()">
        Delete
      </button>
    </div>
  </div>
</form>

plControllers.controller('BooksController',
    ['$scope', '$http', function ( $scope, $http){
  ...
  $scope.destroyBook = function () {
    var bookUrl = 'https://api.parse.com/1/classes/Book/';
    $http({
      method: 'DELETE',
      url: bookUrl + $scope.book.objectId
    })
      .success( function () {
        alert("SUCCESS: Delete book");
        $scope.book = {};
      })
      .error( function ( data) {
        alert("ERROR: Delete book", data);
      });
    };
  ...
}]);

plControllers.controller('TestDataController',
    ['$scope', '$http', function ( $scope, $http) {
  ...
}]);

...
$scope.createTestData = function () {
  $http({
    method: 'POST',
    url: 'https://api.parse.com/1/batch',
    data: {
      requests: [
        {
          method: 'POST',
          path: '/1/classes/Book',
          body: {
            isbn: "006251587X",
            title: "Weaving the Web",
            year: 2000
          }
        },
        {
          method: 'POST',
          path: '/1/classes/Book',
          body: {
            isbn: "0465026567",
            title: "Goedel, Escher, Bach",
            year: 1999
          }
        },
        {
          method: 'POST',
          path: '/1/classes/Book',
          body: {
            isbn: "0465030793",
            title: "I Am A Strange Loop",
            year: 2008
          }
        }
      ]
    }
  })
    .success( function () {
      alert("SUCCESS: Create test data");
    })
    .error ( function ( data) {
      alert("ERROR: Create test data", data);
    });
};
...

...
$scope.clearDatabase = function () {
  $http( {
    method: 'GET',
    url: 'https://api.parse.com/1/classes/Book'
  })
    .success( function ( data) {
      var books = data.results;
      var bookUrl = 'https://api.parse.com/1/classes/Book/';
      books.forEach( function ( book) {
        $http({
          method: 'DELETE',
          url: bookUrl + book.objectId
        })
          .error( function ( data) {
            alert("ERROR: Clear database", data);
          });
      });
    })
    .error( function ( data) {
      alert("ERROR: Get all books", data);
    });
};
...