Understanding the value of Node Modules

“Separation of concerns” is, perhaps, the most important topic in software development. Understanding how we can properly separate disparate parts of our code so they logically make sense while reducing our coupling to other areas is an essential task in modern software development. Within Node.js logic is generally separated using “modules”.

Those who use Node.js are very familiar with “modules” as they form the backbone to Node development, mostly via npm (Node Package Manager). In these cases, the “modules” expand the functionality of Node and make difficult tasks easier, great examples include express and request. In fact, Node itself is built in a module concept, enabling developers to bring in only what they need. Node also enables you to write custom modules, which are a great way to build solutions which are testable and maintainable.

To begin, this is some code I wrote a while back, it works but its not written very well, and it certainly isnt taking advantage of Node.js provides us:

// prototype functions
String.prototype.asWeekNumber = function() {
    var result = this.match(/\d\d?/);
    return parseInt(result[0].toString());
};

// actual job code
function LoadSchedule() {
     var request = require("request");
     request({
          url: "some/url/returning.json",
          json: true
     }, function(error, response, body) {
          if (!error && response.statusCode == 200) {
               var body = JSON.parse(body.replace(/,+/g, ','));
               var key = Object.keys(body)[0];

                    body[key].forEach(function(item) {
             if (item.length == 10) {
                  var game = createGame(item);
                  addGame(game);
             }
        });
          }
     });
}

function createGame(array) {
  return {
     gameDay: array[0],
     gameTime: array[1],
     gameState: 'P',
     awayTeam: array[3],
     awayTeamScore: 0,
     homeTeam: array[5],
     homeTeamScore: 0,
     weekNumber: array[8].asWeekNumber(),
     year: parseInt(array[9])
  };
}

function addGame(game) {
     // doing some SQL Server stuff
}

.csharpcode, .csharpcode pre
{
font-size: small;
color: black;
font-family: consolas, “Courier New”, courier, monospace;
background-color: #ffffff;
/*white-space: pre;*/
}
.csharpcode pre { margin: 0em; }
.csharpcode .rem { color: #008000; }
.csharpcode .kwrd { color: #0000ff; }
.csharpcode .str { color: #006080; }
.csharpcode .op { color: #0000c0; }
.csharpcode .preproc { color: #cc6633; }
.csharpcode .asp { background-color: #ffff00; }
.csharpcode .html { color: #800000; }
.csharpcode .attr { color: #ff0000; }
.csharpcode .alt
{
background-color: #f4f4f4;
width: 100%;
margin: 0em;
}
.csharpcode .lnum { color: #606060; }

For the most part, this looks like most of the JavaScript you see every day. It is purely functional and defines many random functions. Most of these cannot be reused without copying which is an obvious violation of DRY (Dont Repeat Yourself). So what can we do?

Thinking about this from a separation of concerns perspective, we probably want to move the code that is making the request and parsing the return into a module. This way, the LoadSchedule method isnt aware of what is being done just that it IS being done.

Here is the updated code for LoadSchedule following the refactor

function LoadSchedule() {
     var spSchedule = require("score_predict_schedule");
     spSchedule.getCurrentSchedule({
          success: function(games) {
               games.forEach(function(game) {
         if (game.weekType != "PRE") {
              // do not load the preseason
              addGame(game);
         }
               });
          },
          fail: function(error) {
               console.log(error);
          }
     });
}

function addGame(game) {
     // do some SQL Server stuff here
}

As you can see, it is A LOT cleaner. The important line is require(“score_predict_schedule”). This bring in our module. Because we have it located under node_modules we dont even need to specify a path. If we look at the source code inside:

// parser reference
var parser = require("./week_parser");

// Module for handling schedule retrieval
module.exports = {
     _createGameFromType10: function(array) {
          var weekInfo = parser.parseWeekInformationFromString(array[8]);
               // return the game parsed from a Type 10 result
          },

     _createGameFromType8: function(array) {
          var weekInfo = parser.parseWeekInformationFromString(array[6]);
          // return the game parsed from a Type 8 result
     },

     getCurrentSchedule: function(handler) {
          var request = require("request");
          var gameList = [];
          var self = this;

          request({
               url: "http://some/url/returning.json",
               json: true
          }, function(error, response, body) {
               if (handler === undefined) {
                    console.log("You must define a handler");
                    return;
               }

               if (!error && response.statusCode == 200) {
                    var body = JSON.parse(body.replace(/,+/g, ','));
                    var key = Object.keys(body)[0];
                    body[key].forEach(function(item) {

                        if (item.length == 10) {
                           gameList.push(self._createGameFromType10(item));
                        } 

                        if (item.length == 8) {
                          gameList.push(self._createGameFromType8(item));
                        }
                   });

                   handler.success(gameList);
               }
               else {
                    handler.fail(error);
               }
          });
     }
};

We see that this has allowed us to break up different parsing branches and thereby allow our caller to not worry about HOW things get parsed, just received the list so it can perform the next step.

Something interesting here is the definition of parser. I was able to also refactor the logic which some specialized parsing into a separate sub module within our custom module. That being the case, I could reference it directly, sans the .js extension. Its definition is identical to this.

The advantage with this approach is now I can more easily write unit tests and bootstrap files to test this code. Before, I would have had to load the entire file and call my method. Seems easy, but it does make testing more difficult in the long run. In addition, if I ever had to do a similar operation I would have had to duplicate large chunks of that code. With this new approach, I can just call require and be done with it.

You will find an approach like this in most software development projects. The rule is “verify all the smaller pieces work so when you put them together into something bigger, its more likely to ‘just work’”.

A Brief Dive into Xamarin for iOS

I recently decided to begin diving deeper into Xamarin for iOS. One of the big reasons I have focused so heavily on learning Objective-C and iOS is to ease this transition. I already possess very solid C# skills so the idea of being able to use C# over Objective-C and still create iOS apps was very appealing to me. However, I still felt that learning the patterns and paradigms of iOS would make it easier to use MonoTouch (the Xamarin product which allows iOS apps to be written using C#); this has proven true.

Xamarin applications are developed one of two ways: 1) through Visual Studio as a plugin or 2) using the Xamarin Studio development environment. In terms of the free trial you can only use Xamarin studio to develop iOS apps on Mac or use the Visual Studio plugin to develop Android apps on Windows. For this brief dive we will be focusing squarely on iOS development on the Mac.

You still need XCode

It doesn’t seem to matter who does what, we can’t get ride of Xcode (unless you build all views by hand). It is no different with MonoTouch as it is still the easiest way to build the interface. However, Xamarin does something pretty cool with this. Open up your Storyboard file (double click) and it will launch Xcode. Wireup the IBOutlets and IBActions as you would normally, however, notice the lack of a .m file.

Save the file and return to Xamarin studio and open your designer.cs file (below):

If you open this file you will see partial methods being used to bind the C# methods to the Objective-C methods they related to. Here is a picture of mine as an example:

As with most files containing generated code you are not going to want to edit this file. Instead you will want to define the actual implementations for these partial methods in the related class file (in my case GitHub.AppViewController), this is usually the file which the designer file is linked to. Here is my implementation of sayHello.

You can see the usage of the AlertView class with the same name as its Objective-C counterpart. This is done intentionally to ease the transition. Notice in this case, I have defined the AlertView to use the PlainTextInput style which will give the popup a textfield for text entry (I am asking for the users name).

Feels like Android

Looking at the above code you notice that for the Delegate property I am assigning the variable _alertViewDelegate. This class is of type MyAlertViewDelegate. I am not sure the reason but the protocols for Objective-C were brought over as classes, instead of interfaces. The Xamarin documentation recommends creating a subtype of any protocol you intend to implement. This is not at all dissimilar from how Android developers approach this sort of situation with Adapters.

Here is the source code for MyAlertViewDelegate:

You can see the the constructor for this classes takes the ISayHello interface, this is so we have a way to call back to our view to update when the delegate method fires (very common paradigm in Android). Notice the class declaration for the View Controller:

By doing this, I am able to assign this class to the delegate property of UIViewController so when the user presses the “OK” button the delegate method Dismissed is fired. From that I can get the input the user provided and then call SayHello on the view controller because I know the class reference given to the constructor implements ISayHello which guarantees the method SayHello exists. SayHello is defined in the view controller so it can then operate on associated views.

Note: The code I write here is demo code and not an example of production ready code. It is rarely OK to have two methods with the same name in a class differentiated ONLY by their casing.

Some Closing Thoughts

Xamarin is a very nice platform that allows .NET developers to use their existing skills for popular mobile platforms. With some basic understanding of iOS patterns and paradigms the transition is very easy and helpful. You still need Xcode for interaction with storyboards and creating GUI elements (same as true when using AppCode from JetBrains) but I really like what Xamarin offers for those of us seeking to truly create unified code bases for all platforms (excluding view code)

A Brief Look at .NET Backends for Azure Mobile Services – Part 2

In the last article we looked at the basics of the new support for .NET in Azure Mobile Services. This included creating a trivial controller that handle some basic math; obviously this was done to communicate concept as this sort of controller would have little value in most applications.

Quick Note: As this is looking at a Preview feature of Azure some of what may be here could be outdated. I wrote this article on 3/16/2014, so bare that in mind.

Problems with the TodoItem Example

When you create a new Mobile Service you are always given a Quickstart Todo item application to help get you started. This is usually quite helpful, however, it can lead to great confusion with the .NET backends, especially if you are just playing around.

Before we get into that, a good tip to help with tracking down errors is to increase the error handling; it would seem set fairly low by default. To do this bring up your WebApiConfig file (under App_Start) and update Register to set the ConfigOptions MinimumTraceLevel to Info. This will do much to increase the information you receive in your Mobile Service logs.

In this same file, you will notice a class definition for an Initializer (the class will inherit from DropCreateDatabaseIfModelChanges). This will be the source of your problems at first. This initiaization pattern was first developed in the early days of Code First Entity Framework, before Migrations became the preferred way. It was designed for development environments where the persistence of the data is less important. It accomplishes this by dropping the entire database when a model change is detected. While this is fine for a local database, no Mobile Service has permission to drop a database in SQL Azure. This means if you publish and then publish again with a model change, your service will cease funcitoning.

I anticipate this is going to change in the future, but it caused me a huge headache during my early research with this; I eventually got to a point where I had to throw away the Mobile Service I had been using and start again. The best way to solve this problem is to use Migrations, but even that has issues.

Problems Migrating

Assuming you are starting with a freshly created Mobile Service and you had downloaded the source code, the first thing you will want to do is run Enable-Migrations (I use the Library Package Manager console). This will update the project and add in the Configuiration class which will, through convention, replace your original Initializer; that said need to at least comment out the SetInitializer call in the WebApiConfig static class (under App_Start).

Side note: I always advocate the data layer should be created in a separate project and separated from the web project. Such an explanation is outside the scope of this article.

With Migrations enabled, you will need to add the initial migration. I generally do ‘Add-Migration “Initial Migration”’ or something to that effect, this is where the problems will come in.

If you run Update-Database the application of the Seed method will fail. The reason for this is curious. Microsoft requires that your objects which will be stored in SQL Azure have their class definitions inherit from EntityData which will provide the standard columns that all Mobile Services feature.

The problem is that, within the Seed method, the CreatedAt column is marked as a clustered index. If you know anything from SQL Server it is that you are only permitted to have one clustered index per table. I believe marking the Id field as a Primary Key (which the migration does) makes it a clustered index as well, thus giving you two. You can easily get around this by removing the Index definition; not sure why this decision was made.

After you do this Update-Database should execute without error.

The server will operate it much the same way to perform the migrations. However, as an added measure, inform the Publish Profile to run Code First migrations at app startup.

This will ensure the Code First migrations run.

Testing

To make testing things easier from this point forward, allow Anonymous access to the Get method of the TodoItemController (below).

        [RequiresAuthorization(AuthorizationLevel.Anonymous)]
        public IQueryable GetAllTodoItems()
        {
            return Query();
        }

You should be able to run the Web project and either use IE, Fiddler or something similar to hit the following URL: http://localhost:#####/tables/TodoItem which will return a JSON file with a couple TodoItem entries inside. You can then run a simple Publish and push your contents to Mobile Services. After completion, your default browser will open to the root page of your Mobile Service. Simple append /tables/TodoItem and you should get the same results as before. If you do not, check your Logs

Adding New Entities

If you have worked with Code First Entity Framework in the past much of this will be a review. First create a class, we will call it Person. Add three properties FirstName, LastName (string), and BirthDate (DateTime) – see below:

    public class Person : EntityData
    {
        public string FirstName { get; set; }
        public string LastName { get; set; }
        public DateTime BirthDate { get; set; }
    }

Notice that the entity inherits from EntityData. This base class provides all of the necessary default fields all SQL Azure tables will have (at least those created through Mobile Services).

The next thing we need is a DbSet (or context). The application comes with one of these already setup (assuming you are using the starter project). For our purposes, we will add the People property to represent the appropriate table. See below

    public class peoplegreeterContext : DbContext
    {
        // Full file omitted for brevity

        private const string connectionStringName = "Name=MS_TableConnectionString";

        public peoplegreeterContext() : base(connectionStringName)
        {
        } 

        public DbSet TodoItems { get; set; }
        public DbSet People { get; set; }
    }.csharpcode, .csharpcode pre
{
	font-size: small;
	color: black;
	font-family: consolas, "Courier New", courier, monospace;
	background-color: #ffffff;
	/*white-space: pre;*/
}
.csharpcode pre { margin: 0em; }
.csharpcode .rem { color: #008000; }
.csharpcode .kwrd { color: #0000ff; }
.csharpcode .str { color: #006080; }
.csharpcode .op { color: #0000c0; }
.csharpcode .preproc { color: #cc6633; }
.csharpcode .asp { background-color: #ffff00; }
.csharpcode .html { color: #800000; }
.csharpcode .attr { color: #ff0000; }
.csharpcode .alt 
{
	background-color: #f4f4f4;
	width: 100%;
	margin: 0em;
}
.csharpcode .lnum { color: #606060; }

This will indicate to Entity Framework that People is a table that should exist in the database, the migrations will indicate that the table should be created when the Update-Database command is executed as part of the deployment process.

Because what you are working with here is effectively just a managed instance of WebAPI the same routing rules apply as you are used to from previous versions. However, as part of Mobile Services you do get some convenience methods and classes as well.

Most of these are contained in the base class TableController where T is a class which inherits from EntityData.

More coming in the final part, part 3

A Brief Look at .NET Backends for Azure Mobile Services – Part 1

For some time now Azure Mobile Services allowed developers to quickly standup a cloud based RESTful endpoint to enable cross device communication. Each instance represented an Node.js instance using ExpressJS for its routing and web configuration. This gave WAMS great power and flexibility when developing applications on the platform, all written in JavaScript. Now, Microsoft has decided to expand the offerings and permit developers to use .NET in addition to JavaScript.

Setup

.NET can only be used as a backend on new Mobile Service instances, existing instances must continue to use Node.js. When creating a new Mobile Service the backend drop down will be visible enabling selection of .NET as a backend. Notice that .NET as a backend is still very much in the preview stages, so much of how it works can (and likely will change).

Unlike with Node.js, the .NET option will require more code to be written by you in Visual Studio as opposed to the web. The entire backend is written as a Web API v2.0 application. This will entail that code must be uploaded to Azure. Currently this is done, as with Azure Websites, with a Publish file, which can be downloaded from the Dashboard.

When developing locally, the solution can be run as a normal Web API through either Kasini, IIS Express, or IIS itself. Create a separate application to access the Web API. For your convience, Microsoft provides a starter application for Windows 8, Windows Phone, and iOS under the lightening cloud icon.

Again, the essence, right now, of the .NET backend is nothing more than a Web API back end.

Controllers

If you have worked with an MVC type framework in the past you should be very familiar with Controllers as the main points of logical facilitation in an application. When you create controllers in your Mobile Service .NET application there is an important distinction to be made between the controller base type. Here is an example of a controller whose calls will talk to an actual table. This code is taken directly from the Todo starter application.

    public class TodoItemController : TableController
    {
        protected override void Initialize(HttpControllerContext controllerContext)
        {
            base.Initialize(controllerContext);
            mytestappContext context = new mytestappContext(Services.Settings.Name.Replace('-', '_'));
            DomainManager = new EntityDomainManager(context, Request, Services);
        }
    }

This is an example of a controller which will represent at Custom API endpoint.

    public class NumberController : ApiController
    {

    }

This distinction is very important. As with Node.js the deployment and routing of your service does get mutated as it is published.

Controlling Access

In the past, when you created an endpoint in Mobile Services, whether it was a Custom API endpoint or a Table, access to that endpoint was defined in the web interface. However, one of the first things to notice with a .NET backend is the reduced number of options available.

The reason is, with .NET as your backend, you are given much more intimate access to the underlying mechanics, at least in the current preview; this is one thing I expect to likely change moving forward. For the time being access is controlled using the RequiresAuthorization attribute and the AuthorizationLevel enum. Here is an example

        [RequiresAuthorization(AuthorizationLevel.Anonymous)]
        public string Get()
        {
            var newGuid = Guid.NewGuid().ToString();
            return newGuid.Split(new[] {'-'})[0];
        }
    }

The AuthorizationLevel enum provides four levels of access:

Anonymous
Application
User
Admin

By providing these features you can restrict the allowed connection to the particular endpoint.

Connecting

In terms of opening a connection to Mobile Services from a connected device the code is no different than it was when talking to a Node.js backend, nor would I expect it to be different. Here is an example of the code for connecting to our Numbers controller.

        public static MobileServiceClient MobileService =
            new MobileServiceClient("http://mytestapp.azure-mobile.net/", "APP KEY");

        private async void AddNumbers(object sender, RoutedEventArgs e)
        {
            var result = await MobileService.InvokeApiAsync("Number", HttpMethod.Post,
                new Dictionary<string, string>
                {
                    {"num1", Number1.Text},
                    {"num2", Number2.Text}
                });

            SumOutput.Text = result.ToString();
        }

This code would be no different if you were talking to Node.js backend. This is where that distinction between ApiController and TableController becomes important in whether you call GetTable or InvokeApiAsync passing the appropriate verb.

Forward Thoughts

So I am not covering talking to a database in this section cause I havent delved as deeply into that I would like. What it appears is that a local MDF is used locally. Now, I would assume some sort of transformation takes place when the publish occurs so that it will use SQL Azure, otherwise it would not make any sense given the size restrictions for SqlCE databases.

All of this, I can say, is backed by Code First Entity Framework, hence you will receive a custom context and fully decorated entity (TodoItem) when you download the starter project. I want to cover this and Scheduled Jobs in more detail in my next posting.

Getting to know RequireJS

RequireJS is one of my favorite libraries because it brings on of my favorite programming concepts to a language (JavaScript) that needs it more than any other: Dependency Injection.

For the uninitiated or the unfamiliar, Dependency Injection (DI) is a means by which developers can specify dependencies for a class or module and have the runtime fulffill those dependencies by means of a mapping, usually defined in either Xml or some kind of Fluent API; my personal preference for DI in .NET is through Ninject. Using DI makes unit testing much easier as it opens up the ability to “mock” components so that they can be configured for the given test being run.

So what does DI have to do with JavaScript and why should you care? Consider how much JavaScript is used in modern web applications, especially when you start bringing in third party libraries like momentjs, KnockoutJS, jQuery, etc. What I have seen happen is you end up with these long lists of JavaScript dependencies which results in additional download time when the user first arrives at your page. Yes, you can use bundling and minification but you are still asking the browser to download JavaScript code that might not even be needed. This is where RequireJS comes in.

RequireJS enables you to organize code into modules which list their dependencies. When you ask for one of these modules RequireJS will check if the library has been downloaded and inject it into the module (if it has already been downloaded, it will not make the fetch). What this means is user’s download libraries as they need them, instead of “in case they need them”. This also produces code that is better organized, more modular, and more testable.

To stat this process, you need to get RequireJS. It can be downloaded here: http://requirejs.org/docs/download.html. However, I would encourage you to read the next section before adding it to the page.

Configure RequireJS

Before RequireJS can begin to manage your JavaScript it has to know what libraries you are using and where to find them (for downloading). This is your configuration file. For this example, we are going to call it main.js and its location will be /Scripts/app/main.js. This path is very important as you will see next.

Define your tag as normal and point it at RequireJS (either locally or remotely, though I recommend locally). Next add a new attribute data-main and point it at your configuration file being sure to NOT include the .js extension. This path needs to be relative to your HTML file. Here is an example:

My structure:

scripts
- app
  - main.js
- require.js
index.html

My tag

<script src="scripts/require.js" data-main="scripts/app/main"></script>

You will find this is very commonly throughout when using RequireJS, the dropping of the .js extension, its part of RequireJS origin’s from the CommonJS module in Node.

So what this code will do is load up the main.js file you created earlier. In effect this becomes your bootstrap (initial) file for your application. That being the case, it makes sense that we would want to provide our configurations here. So let’s add a few: jQuery, underscore, bootstrap, jQueryUI, and momentJS. The first thing we need to do is define their paths.

requirejs.config({
    paths: {
          'jquery': "http://code.jquery.com/jquery-1.10.1.min",
          'jquery.ui': "http://code.jquery.com/ui/1.10.4/jquery-ui",
          'underscore': "../underscore",
          'bootstrap': "../bootstrap/bootstrap.min",
          'moment': "http://momentjs.com/downloads/moment.min"
    }
});

Notice the alias’ being used, these are VERY important as they are used during the injection process to resolve what is needed. In this case we define 5 alias values: jquery, jquery.ui, underscore, bootstrap, and moment. Let’s update the directory structure presented earlier:

scripts
- app
  - main.js
- require.js
- bootstrap.min.js
- underscore.js
index.html

Path’s defined in the configuration are RELATIVE TO THE CONFIGURATION module, not the HTML page (which makes sense as the location of the HTML page could be different). Also, no .js extension are used at all. This code instructs RequireJS where to find the files, but we still have to help it understand dependencies (ie, knowing that if you ask for Bootstrap you need jQuery as well), in RequireJS these are called shims. They are defined as a second argument to config, here is our shim configuration:

requirejs.config({
    paths: {
          'jquery': "http://code.jquery.com/jquery-1.10.1.min",
          'jquery.ui': "http://code.jquery.com/ui/1.10.4/jquery-ui",
          'underscore': "../underscore",
          'bootstrap': "../bootstrap/bootstrap.min",
          'moment': "http://momentjs.com/downloads/moment.min"
    },
    shim: {
         'jquery': { exports: 'jQuery' },
         'jquery.ui': { deps: ['jquery'] ",
         'underscore': { exports: '_' },
         'bootstrap': { deps: ['jquery'] },
         'moment': { exports: ['moment'] }
    }
});

The alias come into play here as we define what that library needs in order to function properly. Keep in mind, that if a module is already defined for RequireJS (that is it uses the define syntax) you do not need to define its shim, RequireJS will simply read it as normal. In fact, when you use RequireJS that is what create to hold your own code. However, in the case of the libraries we are using NONE are defined using the appropriate syntax, so we use a shim configuration for each.

The first line indicates that the alias jquery has no dependencies but exports an object called jQuery (this is the central function which $ aliases). This tells RequireJS that when jquery is listed as a dependency to pass in a reference to jQuery to the module.

Both jquery.ui and bootstrap depend on jquery being present, but they both extend jQuery with additional function calls, so for both we need only list the dependency, but they do not export anything we do not already have.

The final two libraries, moment and underscore are defined similar to jquery. They are simply not written as RequireJS modules, so we need to instruct RequireJS what we expect it to pass to our module when either is listed as a dependency of the module.

In all honesty, this is the extent of the configuration, you are now ready for the hard part: using RequireJS. This is the hard part because this is where many developers, myself included, struggle, because you have to learn how you will organize your code to take advantage of RequireJS. This was easy in object oriented programming where the concept of DI makes complete sense, but its harder in a more imperative language like JavaScript. I will attempt to explain what I have learned using RequireJS.

Your Main is your Ready

Following the configuration file you can define your first RequireJS module, pretend this is the ready function we have all become so familiar with via jQuery. Here is my module:

require(['jquery', 'moment'], function($, moment) {
   $("#btn-show-time").click(function() {
      $("#time-output").text(moment().format('MMMM Do YYYY, h:mm:ss a'));
   });
});

require operates asynchronously, so the callback occurs when all dependencies have been fulfilled. Remember, RequireJS tracks what dependencies have been fulfilled and will not download those files again. This means if you ask for the same dependency more than once, it will not download it again, but simply reuse it.

In some cases you may need a library which doesnt export anything but rather extends an existing library, bootstrap is such an example. To leverage this, there are a couple of options that it is useful to be aware of.

Based on our current design, we have indicated that bootstrap will depend on the jquery dependency, but it will not export anything. If nothing is exported that it cannot be injected (unless it was previously written as a RequireJS module). In this case, we need only add the dependency as an unmapped parameter.

require(['jquery', 'moment', 'bootstrap'], function($, moment) {
   $("#btn-show-time").click(function() {
      $("#time-output").text(moment().format('MMMM Do YYYY, h:mm:ss a'));
   });
});

You can do this with jQuery plug-ins as well, the JS file will be included and will simply add its functions to the jQuery object, just as Bootstrap did above. Obviously, unmapped parameters must come at the end of the dependency chain.

The other option is not indicate that these dependencies export a common object, below is an updated shim configuration illustrating the changes we would make (notice I am not just including Bootstrap in this change).

    shim: {
        'jquery': { exports: 'jQuery' },
        'jquery.ui': { deps: ['jquery'], exports: 'jQuery' },
        'underscore': { exports: '_' },
        'moment': { exports: 'moment' },
        'bootstrap': { deps: ['jquery'], exports: 'jQuery' }
    }

This enables us to do the following when defining out module

require(['bootstrap', 'moment'], function(bs, moment) {
   bs("#btn-show-time").click(function() {
      bs("#time-output").text(moment().format('MMMM Do YYYY, h:mm:ss a'));
   });
});

Between the two approaches, I like the first approach better. It makes more sense and is more explicit about what is being included. There will definitely be cases where more than one plug-in is desired for usage, you would be redefining jQuery all over the place. I prefer one definition of jQuery and then being able to bring in, selectively, the extensions the module needs added on to support its function.

Modular JavaScript Design

Using a module based approach is quickly becoming a common practice for JavaScript developers. Using modules enables developers to take advantage of many of the features OO developers take for granted, such as member hiding and using namespaces to mitigate conflict. Unfortunately, the topic of Module Based JavaScript design is beyond the scope of what I can talk about in this article, but needless to say RequireJS can and does promote this style of coding.

Further, by using injection, you can understand how you can write unit tests around these modules. For more information on RequireJS I recommend reading the project page: RequireJS, the author goes to great length to explain why RequireJS makes sense for modern web application development.

Creating custom Knockout Bindings in Durandal

One of the great strengths of Durandal is its integration with KnockoutJS, one of the more popular MVVM libraries for JavaScript available. The extensibility of Knockout is of particular interest as it allows for custom binds to be written which can do everything from color text based on a condition to initializing JavaScript driven UI components, such as those founds in JQuery UI.

To create these bindings in Durandal we have to take advantage of the plug-in architecture, this starts with a RequireJS module returning an object with an install function. In our example, I am going to demonstrate creating a specialized enable binding for a Bootstrap Select dropdown list.

Important: Understand that the name of this file will play a huge role later on, so make sure it is named pickerEnable. Furthermore, to date I have not been able to get plug-ins to load outside of putting them in the durandal/js/plugins folder. I am not aware if this is a requirement for plug-ins or not.

Here is the our skeleton definition:

define(['knockout', 'jquery', 'bootstrap.select'], function(ko, $) {
    return {
        install: function() {
            
        }
    };
});

Notice that the dependency lists three dependencies but only two variables are passed to the actual module. Libraries like bootstrap.select do not actually export a central object that we can reference, instead they augment an existing reference ($ in this case). By indicating bootstrap.select as a dependency the library will be loaded and additional functions made available to the module.

Our next step is to actually add the Knockout binding, to do that we use the familiar custom binding syntax; this becomes straight Knockout at this point.

define(['knockout', 'jquery', 'bootstrap.select'], function(ko, $) {
    return {
        install: function() {
            ko.bindingHandlers.pickerEnable = {
                init: function(element, valueAccessor, allBindings, viewModel, bindingContext) {
                },
                update: function(element, valueAccessor, allBindings, viewModel, bindingContext) {
                }
            };
        }
    };
});

As you might be aware, everything above is optional so we can actually reduce our binding down to only what we absolutely need. In this case, our binding is very simple so we only need update with a couple of the parameters. So our binding only looks like this:

define(['knockout', 'jquery', 'bootstrap.select'], function(ko, $) {
    return {
        install: function() {
            ko.bindingHandlers.pickerEnable = {
                update: function(element, valueAccessor) {
                }
            };
        }
    };
});

Much cleaner. Now we will add the code to actually carry out the binding’s function. This is purely dependant on what the binding is aiming to accomplish. In our case, we will examine the value applied to the binding and render the selectpicker accordingly. Here is our final code:

define(['knockout', 'jquery', 'bootstrap.select'], function(ko, $) {
    return {
        install: function() {
            ko.bindingHandlers.pickerEnable = {
                update: function(element, valueAccessor) {
                    var value = ko.unwrap(valueAccessor());

                    $(element).prop('disabled', !value);
                    $(element).selectpicker('refresh');
                }
            };
        }
    };
});

As you can see, all we are doing is unwrapping the value being applied to the binding and adding the disabled flag to our element (a box in this case). Now, if this were all we had to do we could use one of the standard Knockout bindings. However, with bootstrap.select an additional call to force the plug-in to re-render the UI is needed, hence our plug-in.

So now we have our code, but we have to actually install it. To this we need to store the code, as mentioned earlier, in the durandal/js/plugins directory. The name of the file (minus the .js extension) dictates the name of the plug-in. In our case, I named the file pickerEnable.js so the plug-in name is pickerEnable.

You can install this plugin along with all of the others. Within the .js file representing your application (hint, it has your call to app.start()). One of the other calls usually featured in this file is a call to app.configurePlugins, below is my call which installs the router, http, widget, dialog, and our custom pickerEnable plug-ins.

    app.configurePlugins({
        router: true,
        widget: true,
        dialog: true
        pickerEnable: true
    });

Notice, we merely pass true and that calls the install function that we defined in the module. You can see now why the name of the file is important to consider.

So hopefully this has given you some insight into how to create custom Knockout bindings within the Durandal framework.

Using Modals with Durandal and ASP .NET MVC

Recently I added Durandal to a portion of our Centare Client Dashboard application to make the experience more modern when managing work items for our various projects. My decision to use Durandal was based on the fact that our existing implementation used KnockoutJS for client side interaction and Durandal relies on Knockout for its view models.

The application is pretty straightforward. The user selects a project from a list and see’s work items in various views (product backlog, current and past iteration/sprint). The items are displayed in a tabular list with each row being clickable. When clicked a modal dialog is presented enabling the user to make changes to the work item.

Because changes need to be reflected in the list, I knew that I would have to use Knockout so that certain fields in the view model representing each line could contain observables. While this sounded great in theory, in ended up falling apart.

Modals in Durandal are created using composition based on the name of the view model backing the modal, this also dictates which view is used for the HTML. The key with a list like this is to create a POVM (Plain Old View Model), that is one that is not defined through RequireJS syntax. Below shows how I got around this:

define(['knockout', 'plugins/http', 'durandal/app', 'jquery', 'jquery.ui'], function(ko, http, app, $) {
    function ctor() {
        var that = this;
        that.workItems = ko.observableArray([]);

        this.compositionComplete = function() {
            that.workItems([]);

            http.get(GetBacklogListUrl()).then(function (result) {
                var canEdit = result.CanEdit;

                that.workItems(response.WorkItems.map(function (v) {
                    return new WorkItemViewModel(v, canEdit);
                }));
            });
        };

       function WorkItemViewModel(json, canEdit) {
            this.canEdit = canEdit;
            this.ID = json.ID;
            this.IsBug = json.IsBug;
            this.Attachments = json.Attachments;
            this.Effort = json.Effort;
            this.State = json.State;
            this.Tags = json.Tags;
            this.Description = json.Description;
            this.AcceptanceCriteria = json.AcceptanceCriteria;
            this.StepsToReproduce = json.StepsToReproduce;
            this.History = json.History;

            this.Title = ko.observable(json.Title);
            this.BusinessValue = ko.observable(json.BusinessValue);
        }
    };

    return new ctor();
});

We are able to declare a local JavaScript class which, since its inside the RequireJS module it can use the injected libraries for the view model. The idea here is to keep your view model definition for the line items as simple as possible, you can open the modal by doing the following:

        this.view = function (data) {
            app.showDialog('/Scripts/app/viewmodels/project/workitem.detail.js', data).then(function (result) {
                if (result != null) {
                    var item = _.find(that.workItems(), function(v) {
                        return v.ID == result.id;
                    });

                    item.Title(result.title());
                    item.BusinessValue(result.businessValue());
                }
            });
        };

Based on convention, this code will attempt to grab HTML from /Scripts/app/views/project/workitem.detail.js/, so we will create a custom Route rule in ASP .NET so load a specific view for this path, below is that route:

            routes.MapRoute(
                name: "Dialog View",
                url: "Scripts/app/views/project/workitem.detail.js/",
                defaults: new { controller = "WorkItem", action = "Detail" });

You notice the call to .then, in Durandal modal dialogs are handled as promises, meaning they will allow you to pass data back on close. This is very useful when creating applications and helps us easily update the source entry after a save operation.

This is where you will use a full blown RequireJS module to represent the work items actual data, the view model being loaded is workitem.detail.js as indicated by the first parameter to app.showDialog.

To close the modal, simply call close on the dialog plugin and pass a reference to the view model itself, this will allow Durandal to determine which dialog to close. Here is an example:

define(['knockout', 'plugins/dialog', 'plugins/http', 'durandal/app', 'jquery', 'bootstrap.wysiwyg', 'jquery.hotkeys'],
    function (ko, dialog, http, app, $) {
    var ctor = function () {
        var that = this;
        
        this.activate = function(ctx) {
        };

        this.attached = function(view, parent) {
        };

        this.saveItem = function () {
            var formData = {
                ID: that.id,
                Title: that.title(),
                BusinessValue: that.businessValue(),
                Description: that.description(),
                AcceptanceCriteria: that.acceptanceCriteria(),
                StepsToReproduce: that.stepsToReproduce(),
                IsBug: that.isBug
            };

            http.post(GetWorkItemSaveUrl(), formData).then(function(result) {
                that.isSaving(false);
                dialog.close(that, that);
            }, function(error) {
                app.showMessage(error.statusText, "Uh oh..");
                that.isSaving(false);
            });
        };

        this.closeWindow = function () {
            dialog.close(that, null);
        };
    };

    return ctor;
});

Its pretty straightforward and works even if you have layered modal dialogs (one on top of the other). Notice that when the user simply closes the window without saving, I pass null otherwise I pass the the view model itself, it is then handled above in then.

I realize that you might be curious what activate, attached, and compositionComplete are; put briefly they are Durandal View Model lifecycle events and they will not be discussed here, you can find more information here: http://durandaljs.com/documentation/Interacting-with-the-DOM.html

Otherwise, look for them in a future entry

Working with Android ListViews

Lists are an integral way to communicate information about a set of data the user is interested in. All mobile platforms provide different ways to define and render lists to the user. In Android the ListView widget is used for this purpose. The widget allows for many features but some that I feel are most important are:

The Adapter
View Types
View Generation
Updating

These concepts are integral to constructing efficient lists that can handle data efficiently and effectively which leads to a more positive user experience.

The Adapter

The best way to think of the Adapter is your data source, but it is much more than that. It often contains specific logic for view generation, type declaration, and updating logic. It is the brain behind the list itself.

The Adapter is always of type BaseAdapter, but often this is too abstract for most cases. There are a variety of derivations of this class, you should look at see what makes the most sense for you; I tend to use ArrayAdapter so I can pass in a typed list to the adapter as the data source. For clarity, I will focus on ArrayAdapter for the remainder of this section.

To make life easy on you, you can pass a Resource ID to the constructor of ArrayAdapter (via super) to indicate which view should be used for each entry. Often, however, inflation is used instead, but we will cover that in ‘View Generation’. For ArrayAdapter the parameters are as follows:

Context context: the activity or receivers calling the adapter. This is often referred to as “the context of the application”
int resource: this is the Resource Id of the layout which will be used to display each item in the data source
int textViewResourceId: The Resource Id of the TextView within the layout which will be used to display the item in the list
T[] objects/List objects: The set of data to be displayed by the list, either in array or List format

As you will see later in ‘View Generation’, the resource approach is used for extremely simple cases and often wont fit more complex scenarios.

View Types

Often it may be necessary to provide sections or other custom formatting between items, these are referred to a different view types. The adapter must know how many different views are being used within its list to aid in rendering. This function is only needed if you intend to define more than one and often it amounts to returning a hard coded numbers based on the number of views being used. Here is an example:

    @Override
    public int getViewTypeCount() {
        return 2;
    }

Very simple.

View Generation

Android, like most platforms does on demand view rendering for lists. What this means is that if a list contains 100 items, but only 10 can be seen on the users screen, Android (via the adapter) will only render 20-30 items. This means when we talk about view generation it cannot be emphasized enough how important efficient code is for the view rendering portion. Never do blocking lookups within here as it will kill the user experience or, at worst, bring up the dreaded ANR (Application Not Responsive) prompt.

View generation is a double edged sword, on the one hand it gives you immense flexibility with respect to how the view looks and functions, but since it is often reliant on Layout Inflation it can make the application feel slow and unresponsive.

Layout inflation is the process of using the Layout Inflation System service to take a Resource ID and convert it into a full fledged View which can be referenced and modified programmatically. It is important to understand that, in accordance with the rendering process above, Android will often re-use views so, NEVER assume, the view you are getting is fresh, and dont force the engine to always inflate either. Below is a sample getView implementation which only shows how a view should be inflated to be as efficient as possible:

    @Override
    public View getView(int position, View convertView, ViewGroup parent) {
        if (theView == null) {
            theView = LayoutInflater.from(getContext()).inflate(R.layout.home_list_item, null);
        }

        return theView;
    }

Notice the if check around the inflater, this ensures that if a view instance is being reused it is not reinflated. Taking this approach will allow the use of whatever view you want, even different views based on conditions (remember to update getViewTypeCount).

Once you have an instance of the view, you can operate on it like you would any other case. For example:

    @Override
    public View getView(int position, View convertView, ViewGroup parent) {
        if (convertView == null) {
            convertView = LayoutInflater.from(getContext()).inflate(R.layout.home_list_item, null);
        }
        
        GameEntry game = getItem(position);
        TextView homeTeamName = (TextView) convertView.findViewById(R.id.homeTeamName);
        homeTeamName.setText(game.getHomeTeamName());

        return convertView;
    }

Here, we get the instance at the given position and assign the Home Team name as the text for a TextView that is declared within that view.

The View Holder Pattern

The inflation approach is extremely popular within Android application due to the flexibility and control it affords. However, this comes at a price as Inflation and calls to findViewById can be very expensive. To counter this, we present the ViewHolder pattern. To implement this for the example above create a static inner class within your adapter with a single member, like below:

    private static class ViewHolder {
        TextView homeTeam;
    }

The idea is to have this class sit within the convertView and be reused as a way to reference the view components within your layout. For example, your updated logic looks like this:

    private View getView(int position, View convertView, ViewGroup parent) {
        ViewHolder viewHolder;

        if (convertView == null) {
            convertView = LayoutInflater.from(getContext()).inflate(R.layout.home_list_item, null);
            viewHolder = new ViewHolder();

            viewHolder.homeTeam = (TextView) convertView.findViewById(R.id.homeTeam);
            convertView.setTag(viewHolder);
        }
        else {
            viewHolder = (ViewHolder) convertView.getTag();
        }

        GameEntry game = getItem(position);
        viewHolder.homeTeam.setText(gameEntry.getHomeTeam()));
        return convertView;
    }

Doing this mitigates the needs to repeatedly call findViewById which increases the rendering response as the user flicks through the list, this can be especially helpful in a longer list with more items.

Updating

Updating items within a list in Android can be a very heavy operation, especially with a larger list. Thankfully Android provides a method to allow the List to update with a single line of code: notifyDataSetChanged().

Understand that the notifyDataSetChanged can ONLY work by looking for changes in the datasource, which will be different depending on your adapter type and how it is fed its data. For example, if you are pulling from a repository, then simply updating your repository ahead of the call to notifyDataSetChanged will be sufficient. If you are working with an Array Adapter realize that your data source is passed into the adapter, so updating it externally will not be reflected in your list. Fortunately, the adapter supports add, insert, remove, and clear to allow you to update the dataset inside the ArrayAdapter ahead of notifyDataSetChanged to see your changes.

Realize that there are many other aspects which are crucial for properly implementing a ListView in Android and making it contribute positively to the user experience. For example, implementing a list with a remote datasource requires different considerations than a static list. Always remember the user and seek to avoid the dreaded ANR (Application Not Responding).

Azure Mobile Services and Node.js

One of the great things about Azure Mobile Services (WAMS) is the fact that not only is it built on Node.js but also that it allows you to fully leverage the power of the platform, specifically though the use of custom Node.js packages downloaded from NPM along with custom packages developed locally.

To allow this interaction to occur it is necessary to enable the Git for your Azure Mobile Service. Doing this is easy, after you create a service, go to the Dashboard and click the link indicated below:

This process can take a while, but when it is complete you will be taken to the ‘Configure’ tab of your Mobile Service. You will see a section titled ‘Source Control’ which will provide you with a Git URL which will be the location for your remote. Note: A full discussion of Git is beyond the scope of this article, I recommend this for reading: http://git-scm.com/

Once you do your ‘Pull’ of the code at this URL you will notice a the following directory structure:

service
- api
- scheduler
- shared
- tables

As you might expect, each folder maps to a specific WAMS feature that supports code being written against it.

In Node.js the require function is used to load an external modules (like those downloaded from NPM) and allow their usage in scripts. The require function, when called, recurses upward looking for directories called node_modules as a location to search for the desired code module. This is important to understand as it can simplify your calls an enable you to isolate certain modules.

Note: I have read that the ‘Shared’ folder is the recommended spot to put shared code (ie modules) in WAMS. I do not agree with this since it undermines the use of require and creates a weird path to be used in the application. In this case, I differ to Node.js standards over Microsoft.

So, from within the service folder, run npm install (command line) and install your favorite package. After completion you should notice a new directory created called node_modules within which is the source of your module. We won’t be talking about the structure of Node.js modules in this post, but I encourage you to read up on them as modularizing code, especially with JavaScript, is a great way to enhance reusability and reduce the code you write.

Realize, that all you just did was add files to your local Git repository and these files can be pushed like another files you would add (appropriate commands pending). Once you push the code up to WAMS it can be used by your scripts. This enables you to use Node.js on WAMS as you would with any other Node.js application.

Here is an example, from a current application, of how a Node.js module loaded this way can be used:

function LoadScores() {
    var request = require("request");

    request({
        url: "http://www.foo.bar",
        json: true
    }, function(error, response, body) {
        if (!error && response.statusCode == 200) {
            var objectArray = body.trimResponse().parseResults().toGameArray();

            // prepare to read from the games table
            for (var i=0; i<objectArray.length; i++) {
                var game = objectArray[i];
                insUpGame(game);
            }
        }
    });
}

Here the request module is used to make a GET request for JSON data which is then stored in a database within Azure. The use of a module here reduces the amount of custom code that is needed for the operation.

I have found that many people are surprised to find that Microsoft choose to use Node.js as the backing technology for WAMS over something IIS; I am not. The reason is that Node.js lends itself to the type of configuration model that WAMS uses in allowing point and click declaration of endpoints and tables, much easier to handle the routing. But more than that, Node.js is an established platform for data intensive applications (used heavily by LinkedIn and Groupon, among others) and given that WAMS intends to allow developers to create a common backend for connected applications the ability to work with and handle data is a given. In my opinion, the deeper integration with Node and the ability to fully leverage the platform give WAMS more long term potential than something like Parse.

Customizing the Action Bar in Android

One of the nice things about Windows Phone is the application bar and the consistency that it can bring for buttons. More and more we are seeing application utilize the application bar for their screen actions; this is good because it reduces confusion for the user when knowing what actions they can take.

With Honeycomb Android introduced the Action Bar to replace the context menu. The advantage that this gave was, like Windows Phone, a consistent location for screen actions. The problem was that the options were not visible by default and required the user to “open” the menu, usually through a hard button. The new action bar combined the title of the screen with allowable options with an expandable menu invoked through a soft button.

But I mentioned consistency with applications and the one thing that I see a lot with Android apps is inconsistency. Despite there being Android Design Guidelines you still see a lot of free form with design, in particular with button location. But one pattern that Google seems to be advocating is, like the application bar in Windows Phone, an application bar look in Android, demonstrated here in the Android Calendar application:

I decided I wanted this UI design in my application for an edit/create screen, however it would appear there is no built in simple way to do this, instead you need to create a Custom View for your Action Bar. I spent some time looking online and really didnt find anything super concrete so I decided to check the Android Calendar source (yeah!! open source). The source is available here: https://github.com/android/platform_packages_apps_calendar

Before you begin:

Understand that the Action Bar is an Android 3.0+ concept and this example will assume that. If you are building an application to target pre-Honeycomb releases (which is still the second largest majority) be mindful that this approach wont work.

1) Theme your activity

The first thing is to set some simple display properties on your activity. The best way to do this is to use a style defined in the AndroidManifest.xml

<activity android:name="MyActivity" android:label="@string/app_name"
          android:theme="@style/ActivityWithActionBar" />

Here is the style which shows the Display Options we are affecting:

    <style name="ActivityWithActionBar" parent="android:Theme.Holo.Light">
        <item name="android:windowNoTitle">false</item>
        <item name="android:windowActionBar">true</item>
        <item name="android:windowBackground">@color/background_color</item>
        <item name="android:actionBarStyle">@style/ActionBarStyle</item>
    </style>

Now, we need a view for the custom action bar view

2) Create your view

Literally what you will be doing is creating a layout which is then inflated and passed into the action bar. Here is the XML for the layout of the custom action bar:

<?xml version="1.0" encoding="utf-8"?>

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
              android:orientation="horizontal"
              android:layout_width="match_parent"
              android:layout_height="match_parent"
              android:divider="?android:attr/dividerVertical"
              android:dividerPadding="12dp"
              android:showDividers="middle">

    <LinearLayout android:id="@+id/action_cancel"
                  style="@style/CustomActionButton">

        <ImageView android:src="@drawable/ic_menu_cancel_holo_light" style="@style/ActionButtonImage" />
        <TextView android:text="DISCARD" style="@style/ActionButtonText" />

    </LinearLayout>

    <LinearLayout android:id="@+id/action_done" style="@style/CustomActionButton">

        <ImageView android:src="@drawable/ic_menu_done_holo_light" style="@style/ActionButtonImage" />
        <TextView android:text="DONE" style="@style/ActionButtonText" />

    </LinearLayout>

</LinearLayout>

We have a horizontal linear layout encapsulating two linear layouts which will masquerade as our buttons. The styles used in this example, all are taken, verbatim from the Android Calendar source, see them here: http://pastebin.com/3xzZcJpc

You will notice that this example uses two drawables for the ‘X’ and the checkmark in the button. These coming directly from the source, download them here:

So, we now have our view XML for the custom action bar.

3) Set the action bar

As I mentioned earlier, there is no built in component that allows for this in a consistent fashion. Instead, using a reference to the activities action bar with the appropriate display options, an inflated view is set as the action bar’s view content. Here is the code that does this:

        View customActionBar = getLayoutInflater().inflate(R.layout.custom_action_bar,
                new LinearLayout(this), false);
        getActionBar().setCustomView(customActionBar);

In this example, the name of our custom action bar view is the layout custom_action_bar. We indicate that our action bar will have a custom view through the setCustomView method call.

One thing which should be pointed out is that when doing this you are no longer utilizing the Option Menu which means when the user presses the button in your custom view it will not send an item action. Instead you need to wire these up manually. Its quite easy as the following code snippet shows:

        View cancelActionView = customActionBar.findViewById(R.id.action_cancel);
        View doneActionView = customActionBar.findViewById(R.id.action_done);

        cancelActionView.setOnClickListener(new View.OnClickListener() {
            @Override
            public void onClick(View v) {
                //To change body of implemented methods use File | Settings | File Templates.
            }
        });

        doneActionView.setOnClickListener(new View.OnClickListener() {
            @Override
            public void onClick(View v) {
                //To change body of implemented methods use File | Settings | File Templates.
            }
        });

For your reference, the majority of how I figured this came from the EditEventFragment in the Calendar source: http://bit.ly/EditEventFragment (617)

So as I stated earlier, Apple has shown us that consistency in a platform is important when you start talking about usability. Knowing where something is regardless of the app brings an instant familiarity for users. Windows 8 is built on this methodology through the use of charms for commonly used features. I think, as I see this in most Google apps and other non-Google apps the inclination is that this should be a established pattern especially edit/create screens.

Hope this helps