Heavily drawing inspiration from Ruby on Rails, MVC4’s convention over configuration model
of development soon became the Holy Grail
of .NET web development. The MVC model brought with it the goodness
of proper separation
of concerns between business logic, data, and the presentation logic.
However, the MVC paradigm, was still one in which server side .NET code could be mixed with presentation code. The Razor templating engine, though cleaner than its predecessors, still encouraged and allowed you to mix .NET server side code with presentation logic. Thus, for example, if the developer required a certain <div> tag to be shown if a particular variable ShowDiv was true in the View’s model, the code could look like the following:
Fig 1: To show a div or not. Server side .NET code is used in the View
Mixing .NET code with HTML in views can soon get very messy. Wouldn’t it be nice if the presentation layer (HTML) could be pure HTML? Also, in the ASP.NET MVC model, some
of the business logic invariably resides in the controller. It is tempting to use an antipattern like the one shown above to control whether a div should be shown or not.
However, best practice would indicate that the Controller should not be aware
of the div. The ShowDiv variable in the model should not exist. A controller should ideally, only be used to do the plumbing
of getting the data populated in the model and nothing else. The view (ideally pure HTML) should render the presentation layer based on the model.
In this article we will see how Angular JS, a new JavaScript framework by Google can be used effectively to build web applications where:
1. Views are pure HTML
2. Controllers (in the server sense) are pure REST based API calls
3. The presentation layer is loaded as needed from partial HTML only files.
What is MVVM?
MVVM short for Model View View Model is a new paradigm in web development. In this paradigm, the Model and View stuff exists on the client side through javascript instead
of being processed on the server through postbacks. These frameworks are JavaScript frameworks that facilitate the clear separation
of the “frontend” or the data rendering logic from the “backend” which is typically just a REST based API that loads and processes data through a resource model.
The frameworks are called MVVM as a change to the Model (through javascript) gets reflected in the view immediately i.e. Model > View. Also, a change on the view (through manual input) gets reflected in the model immediately i.e. View > Model. The following figure shows this conceptually (comments are shown in red):
Fig 2: Demonstration
of MVVM in action
In Fig 2, two text boxes are bound to the same variable model.myInt. Thus, changing the view manually (changing one text box through keyboard input) also changes the other textbox in real time demonstrating V > M property
of a MVVM framework.
Furthermore, clicking the button adds 1 to the value
of model.myInt thus changing the model through JavaScript. This immediately updates the view (the value in the two textboxes) thus demonstrating the M > V property
of a MVVM framework.
Thus we see that the model in a MVVM JavaScript framework can be regarded as “the single source
of truth“. This is an important concept. Angular is one such MVVM framework. We shall use it to build a simple app that sends SMS messages to a particular number.
Application, Routes, Views, Controllers, Scope and Models
Angular can be used in many ways to construct web applications. For this article, we shall only focus on building Single Page Applications (SPAs). Many
of the approaches we will follow in this article have alternatives. It is beyond the scope
of this article to explain every nuance in detail but we shall try to touch upon the basic concepts and end up with a working application that can be used to send SMS messages using Sent.ly Plus (a service that is itself built using Angular).
Before you read on, we would like to urge you to forget what you know about Models, Views, Controllers and Routes in the ASP.NET MVC4 framework. All these words have different meanings in the Angular world. Whenever these words are used in this article, they will refer to Angular concepts and not ASP.NET MVC4 concepts.
The following figure shows the skeleton
of the root page
of an SPA:
Fig 3: The skeleton
of a SPA
The skeleton
of the application is based on the Bootstrap starter template which can be found at: http://getbootstrap.com/examples/startertemplate/
Apart from loading the Angular, jQuery and Bootstrap JavaScript libraries, it also loads our custom scripts
/app/js/controllers.js /app/js/app.js
These scripts define the routes, views and controllers which we shall come to in a moment.
Application
Notice that the body tag (Fig. 3) has an extra attribute:
ngapp=”smsApp”
Providing this tag “bootstraps” our single page application. It tells Angular to load a “module” called smsApp. This “module” is defined /app/js/app.js
angular.module('smsApp', ['smsApp.controllers', function () {}])
Fig 4: The definition
of our application module
The line shows above, declares a module called smsApp. It also declares that this module “depends” on another module called “smsApp.controllers”. The smsApp.controllers module will contain all the controllers for our SPA.
Routing and Views
Notice that in the Navbar (in Fig 3) we have included two hyperlinks to:
“#/app” “#/help”
This is how Angular handles routing. Since the URLs start with “#”, they are actually just bookmarks (and not server side resources). However, our route definition (in /app/js/app.js) gives these URLs a special meaning within the Angular framework.
angular.module('smsApp', ['smsApp.controllers', function () {
}])
//Configure the routes
.config(['$routeProvider', function ($routeProvider) {
$routeProvider.when('/binding', {
templateUrl: '/app/partials/bindingexample.html',
controller: 'BindingController'
});
}]);
Fig 5: The definition
of a route with an associated partial view and controller
As we can see from the previous code sample, we are using the $routeProvider object in the configuration
of our smsApp module. Notice how the code “asks for” the $routeProvider object by specifying it as a dependency in the [] braces and then defining a function that accepts it as a parameter. This is known as dependency injection. Please refer to the following link if you want to delve into this topic: http://docs.angularjs.org/guide/di
What the above code snippet is doing is that it is telling Angular that when the URL is “#/binding”, then it should load the HTML snippet (“partial view”) found at /app/partials/bindingexample.html. Also, for this URL, Angular should load the controller called “BindingController”.
We have also marked the div with the class “container” (in Fig 3) with the ngview attribute. This attribute tells Angular that views (partial HTML pages) defined in the routes will be loaded within this div.
You can see that the Angular JavaScript framework, unlike many other frameworks, works purely by extending HTML tags and attributes. It also allows you to extend HTML with your own tags and attributes (through directives) if you so desire, you can find
out more about directives at the following URL: http://www.codeproject.com/Articles/607873/ExtendingHTMLwithAngularJSDirectives
Controllers and Models
We have seen how we define what views and controllers should be loaded for a particular route. Let us now consider how controllers are defined. Our controllers are defined in the file /app/js/controllers.js. The following snippet shows the definition
of the “BindingController” which is loaded when we hit the URL http://localhost:port/index.html#/binding (as we have defined in the route earlier as shown in Fig 5).
Remember that we had defined that our application module “smsApp” depends on the “smsApp.controllers” module (see Fig 4). The code snippet below shows how the “BindingController” defined in the route shown in Fig 5 is defined in the module smsApp.controllers:
angular.module('smsApp.controllers', [function () {
}])
.controller('BindingController', ['$scope', function ($scope) {
$scope.model = {};
$scope.model.myInt = 6;
$scope.addOne = function () {
$scope.model.myInt++;
}
}]);
Fig 6: The definition
of a controller in the “smsApp.controllers” module.
The pieces are falling in place! Remember Fig.2? That was the code
of a partial view that was loaded within the container div
of the skeleton SPA shown in Fig 3. The route definition shown in Fig 5 also defined that the controller called “BindingController” (shown in Fig 6.) was loaded when we loaded the URL: http://localhost:22544/index.html#/binding
The button in Fig 2 was marked with the attribute ngclick=”addOne()” which added 1 to the value
of model.myInt. In Fig 6, we can see that this function is actually defined in the “BindingController”.
Scope
We can see from Fig 6, that in the definition
of “BindingController”, we defined a dependency on $scope and then, as usual, defined a function which “asks for” $scope as per the dependency injection pattern.
So what is $scope? Any guesses? As you might have guessed a scope is a particular “address space” where variables and functions may be defined. This has a similar meaning to scope in a programming language like C#.
Model: The Scope is not the Model
It is tempting to assign variables in the scope directly. For example, we could have defined myInt as $scope.myInt = 6 in Fig 6 instead
of $scope.model.myInt = 6. The reason why this is a bad idea is that scope in hierarchical in Angular. Thus if we were to define a controller which was defined within the another controller (nested controllers), then the inner controller would inherit the scope
of the parent controller. This inheritance would follow JavaScript prototypal inheritance.
Let’s say the parent controller defined a variable through $scope.myInt = 6. The child controller would inherit the scope through java prototypical inheritance. This basically means that the child scope has a variable myInt that points to the parent scopes myInt variable. Now if we assigned the value
of myInt in the parent, the child scope would be updated with the same value as the child scope’s myInt variable points to the parent scope’s myInt variable.
However, if we were to assign the value
of the myInt variable in the child scope, then the link
of that variable to the parent scope would be broken as the variable myInt in the child scope now points to the value 6 and not to the parent scope’s myInt variable.
But, if we defined a variable model in the parent scope, then the child scope will also have a variable model that points to the model variable in the parent scope. Updating the value
of $scope.model.myInt in the parent scope would change the model variable in the child scope too as the variable is pointed to the model variable in the parent scope.
Now changing the value
of $scope.model.myInt in the child scope would ALSO change the value in the parent scope. This is because the model reference in the child scope is pointed to the scope variable in the parent. We did no new assignment to the model variable in the child scope. We only changed an attribute
of the model variable. Since the model variable (in the child scope) points to the model variable in the parent scope, we have successfully changed the value
of myInt in the parent scope. Thus the value
of $scope.model.myInt in the parent scope becomes the “single source
of truth“.
This is a tricky concept, thus it is considered good practice to NOT use scope inheritance. More info on prototypal inheritance in Angular can be found in the “JavaScript Prototypal Inheritance” section at the following URL: https://github.com/angular/angular.js/wiki/UnderstandingScopes.
Building It: An Angular JS application using a .NET Web API Backend
Now that we have a perspective on the basic components
of an MVVM application built using Angular, let’s build something useful. We will build an application that can be used to send
out SMS messages to a given phone number. The following diagram describes the architecture
of the application we are going to build:
Fig 7: Broad application architecture
We are going to add an HTML Partial to our project. This partial will contain the form fields that will accept the phone number and message that needs to be sent as an SMS. It will also display all the messages that have previously been sent.
All the executable code that is run on the occurrence
of events (button clicks etc.) in the view resides in the controller.
The controller interacts with the ASP.NET WebAPI to get a history
of SMS messages, add a message etc. through a REST based API. For the purposes
of simplicity, we will use an in memory data structure for the purposes
of creating this application.
Thus, the tasks ahead
of us are:
Creating the REST WebApi with GET, PUT, POST, DELETE methods.
Creating the SmsView.html partial
Creating the SmsController controller with methods that are called from the SmsView.html partial
Add a new route that loads the controller and the partial.
1. Creating the REST WebAPI
This is a simple task that should be quite straightforward to any .NET developer. The following listing shows our ApiController:
public class SmsMessage
{
public string to { get; set; }
public string message { get; set; }
}
public class SmsResource : SmsMessage
{
public int smsId { get; set; }
}
public class SmsResourceController : ApiController
{
public static Dictionary<int, SmsResource> messages = new Dictionary<int, SmsResource>();
public static int currentId = 0;
// GET api/<controller>
public List<SmsResource> Get()
{
List<SmsResource> result = new List<SmsResource>();
foreach (int key in messages.Keys)
{
result.Add(messages[key]);
}
return result;
}
// GET api/<controller>/5
public SmsResource Get(int id)
{
if (messages.ContainsKey(id))
return messages[id];
return null;
}
// POST api/<controller>
public List<SmsResource> Post([FromBody] SmsMessage value)
{
//Synchronize on messages so we don't have id collisions
lock (messages)
{
SmsResource res = (SmsResource) value;
res.smsId = currentId++;
messages.Add(res.smsId, res);
//SentlyPlusSmsSender.SendMessage(value.to, value.message);
return Get();
}
}
// PUT api/<controller>/5
public List<SmsResource> Put(int id, [FromBody] SmsMessage value)
{
//Synchronize on messages so we don't have id collisions
lock (messages)
{
if (messages.ContainsKey(id))
{
//Update the message
messages[id].message = value.message;
messages[id].to = value.message;
}
return Get();
}
}
// DELETE api/<controller>/5
public List<SmsResource> Delete(int id)
{
if (messages.ContainsKey(id))
{
messages.Remove(id);
}
return Get();
}
}
Once this class is defined, we should be able to access the WebAPI by a simple GET request using the browser: http://localhost:port/api/SmsResource
Notice the commented line: //SentlyPlusSmsSender.SendMessage
The SentlyPlusSmsSender class is defined in the attached solution. We have shown this line as commented as we want to explain the core Angular concepts. If you load the attached solution, this line is uncommented in the source and an actual SMS will be sent!
By default, the API returns XML. For consumption
of the API in Angular, we would like it to return JSON. To change the default to JSON, we make the following change to WebApiConfig.cs file located in the App_Start folder.
public static class WebApiConfig
{
public static void Register(HttpConfiguration config)
{
config.Routes.MapHttpRoute(
name: "DefaultApi",
routeTemplate: "api/{controller}/{id}",
defaults: new { id = RouteParameter.Optional }
);
var appXmlType =
config.Formatters.XmlFormatter.
SupportedMediaTypes.
FirstOrDefault(
t => t.MediaType == "application/xml");
config.Formatters.XmlFormatter.SupportedMediaTypes.Remove(appXmlType);
}
}
We now have our backend REST Api which we can consume from Angular!
2. Creating the SmsView.html partial
This simple partial will define two fields: the destination phone number (international format starting with a +) and the message. These fields will be bound to model.phoneNumber and model.message. We will also add a button that we shall hook up to sendMessage() in the controller. A list
of all previously sent messages (bound to model.allMessages) will also be displayed below the form input. The following code shows the code for the partial:
<!-- If model.errorMessage is defined, then render the error div ->
<div class="alert alert-danger alert-dismissable" style="margin-top: 30px;"
ng-show="model.errorMessage != undefined">
<button type="button" class="close" datadismiss="alert" ariahidden="true">×</button>
<strong>Error!</strong>
<br />
{{ model.errorMessage }}
</div>
<!-- The input fields bound to the model -->
<div class="well" style="margin-top: 30px;">
<table style="width: 100%;">
<tr>
<td style="width: 45%; text-align: center;">
<input type="text" placeholder="Phone number (eg; +44 7778 609466)" ng-model="model.phoneNumber" class="form-control" style="width: 90%" onkeypress="return checkPhoneInput();" />
</td>
<td style="width: 45%; text-align: center;">
<input type="text" placeholder="Message" ng-model="model.message" class="form-control" style="width: 90%" />
</td>
<td style="text-align: center;">
<button class="btn btn-danger" ng-click="sendMessage();" ng-disabled="model.isAjaxInProgress" style="marginright: 5px;">Send</button>
<img src="/Content/ajax-loader.gif" ng-show="model.isAjaxInProgress" />
</td>
</tr>
</table>
</div>
<!-- The past messages -->
<div style="margin-top: 30px;">
<!-- The following div is shown if there are no past messages -->
<div ng-show="model.allMessages.length == 0">
No messages have been sent yet!
</div>
<!-- The following div is shown if there are some past messages -->
<div ng-show="model.allMessages.length == 0">
<table style="width: 100%;" class="table table-striped">
<tr>
<td>Phone Number</td>
<td>Message</td>
<td></td>
</tr>
<!-- The ng-repeat directive is line the repeater control in .NET, but as you can see this partial is pure HTML which is much cleaner -->
<tr ng-repeat="message in model.allMessages">
<td>{{ message.to }}</td>
<td>{{ message.message }}</td>
<td>
<button class="btn btn-danger" ng-click="delete(message.smsId);" ng-disabled="model.isAjaxInProgress">Delete</button>
</td>
</tr>
</table>
</div>
</div>
The above code is commented and should be self explanatory. Conditional rendering is achieved through using the ng-show=”condition” attribute on various div tags.
Input fields are bound to the model and the send button is bound to the sendMessage() function in the controller as through the ngclick=”sendMessage()” attribute defined on the button tag.
While AJAX calls are taking place, the controller sets model.isAjaxInProgress to true. Based on this variable, buttons are disabled through the ng-disabled directive which is added as an attribute to the buttons.
The ng-repeat directive added as an attribute to the tr tag causes the table row to be rendered multiple times much like an ASP.NET repeater.
3. Creating the SmsController controller
The penultimate piece
of our application is the controller which responds to events from our view and interacts with our MVC4 REST WebAPI.
The following listing shows the code we need to add to /app/js/controllers.js. Note that controller definitions can be chained. Also note that this controller “asks for” the $http service. The $http service is a simple way in Angular to do AJAX. So far we have only encountered modules, controllers, views and directives in Angular. The $http is new entity in Angular called a service. More information on Angular services can be found at the following URL: http://docs.angularjs.org/guide/dev_guide.services.understanding_services.
.controller('SmsController', ['$scope', '$http', function ($scope, $http) {
//We define the model
$scope.model = {};
//We define the allMessages array in the model
//that will contain all the messages sent so far
$scope.model.allMessages = [];
//The error if any
$scope.model.errorMessage = undefined;
//We initially load data so set the isAjaxInProgress = true;
$scope.model.isAjaxInProgress = true;
//Load all the messages
$http({
url: '/api/smsresource', method: "GET"
}).
success(function (data, status, headers, config) {
this callback will be called asynchronously
//when the response is available
$scope.model.allMessages = data;
//We are done with AJAX loading
$scope.model.isAjaxInProgress = false;
}).
error(function (data, status, headers, config) {
//called asynchronously if an error occurs
//or server returns response with an error status.
$scope.model.errorMessage = "Error occurred status:" + status;
//We are done with AJAX loading
$scope.model.isAjaxInProgress = false;
});
$scope.delete = function (id) {
//We are making an ajax call so we set this to true
$scope.model.isAjaxInProgress = true;
$http({
url: '/api/smsresource/' + id,
method: "DELETE"
}).
success(function (data, status, headers, config) {
// this callback will be called asynchronously
// when the response is available
$scope.model.allMessages = data;
//We are done with AJAX loading
$scope.model.isAjaxInProgress = false;
});
error(function (data, status, headers, config) {
// called asynchronously if an error occurs
// or server returns response with an error status.
$scope.model.errorMessage = "Error occurred status:" + status;
//We are done with AJAX loading
$scope.model.isAjaxInProgress = false;
});
}
$scope.sendMessage = function () {
$scope.model.errorMessage = undefined;
var message = '';
if($scope.model.message != undefined)
message = $scope.model.message.trim();
if ($scope.model.phoneNumber == undefined ||
$scope.model.phoneNumber == '' ||
$scope.model.phoneNumber.length < 10 ||
$scope.model.phoneNumber[0] != '+') {
$scope.model.errorMessage = "You must enter a valid phone number in international format. Eg: +44 7778 609466";
return;
}
if (message.length == 0) {
$scope.model.errorMessage = "You must specify a message!";
return;
}
//We are making an ajax call so we set this to true
$scope.model.isAjaxInProgress = true;
$http({
url: '/api/smsresource', method: "POST",
data: { to: $scope.model.phoneNumber, message: $scope.model.message }
}).
success(function (data, status, headers, config) {
// this callback will be called asynchronously
// when the response is available
$scope.model.allMessages = data;
//We are done with AJAX loading
$scope.model.isAjaxInProgress = false;
}).
error(function (data, status, headers, config) {
// called asynchronously if an error occurs
// or server returns response with an error status.
$scope.model.errorMessage = "Error occurred status:" + status
// We are done with AJAX loading
$scope.model.isAjaxInProgress = false;
});
}
}]);
We can see from the previous listing how the functions that are called from the view are defined in the controller. It should also be evident how easy it is to make AJAX calls to consume our MVC4 REST WebAPI. Now we are left with the final piece. We need to define a route that associates a particular path with the view we have defined and the controller we have defined.
4. Add a new route that loads the controller and the partial
This is the easiest part
of the puzzle. We simply define another route in the /app/js/app.js file:
$routeProvider.when('/sms', {
templateUrl: '/app/partials/smsview.html',
controller: 'SmsController'
});
Conclusion
In this article we have seen how much
of the server side functionality in the MVC4 framework can be moved to the
browser thus delivering a snappy and fast user interface.
We have seen how we can build client side HTML only views that avoid the messy syntax offered by server side Razor views.
We have built a functioning app from the ground up.
The significant advantage
of this approach to building web apps is that the front end can be completely platform independent. Even though we used ASP.NET to create our REST API, we could just easily have used any other language such as Node.js, Ruby etc without changing a single line
of our front end code.
Angular is a rich framework and we have only touched on basic functionality required to create a SPA. For readers who wish to delve further into the Angular framework, we would recommend the following URL as a starting point: http://docs.angularjs.org/misc/started.
To get started with the code for this project:
Sign up for an account at http://plus.sent.ly (free)
Add your phone number
Go to the “My Identies Page”
Note Down your Sender ID, Consumer Key and Consumer Secret
Download the code for this article at: https://docs.google.com/file/d/0BzjEWqSE31yoZjZlV0d0R2Y3eW8/edit?usp=sharing
Change the values
of Sender Id, Consumer Key and Consumer Secret in the web.config file
Run the project through Visual Studio!
