This was the case for me when I needed to check for changes on a rather deeply nested class.

The Problem

Angular 1 uses $scope.$watch to actively check for changes.

In my scenario, the built in equality checker had a really hard time with my class. So much so, that it would cause a Max call size exceeded error every time it tried to run $watch.

We already had a function that would compare only the attributes on the class that mattered, but $watch doesn't support custom comparators.

The Solution

You'll need to keep a copy of the previous state somewhere. We have a service that has the original copy of the class, so we used that to determine if the local copy changed.

Here's what it looks like:

Warning - your equals function will run on every digest cycle, so perf matters. Return early!

Here, we provide $watch with a function that returns a value. Angular will keep track of that value for you. We are going to take advantage of that and simply return a boolean that changes when our custom compare function says that the object has changed.

After you determine that a change has happened, don't forget to update your previous version

Final Thoughts

This is a simple trick that can get you out of a bind, but again, be very mindful of how your build your custom comparator logic.

I ran into one of those instances recently when implementing an HTTP Interceptor.

The Problem

The Angular 1 code relied on $rootScope.$broadcast in order to tell other parts of the app when an HTTP call responded with a server error. (This mechanism will be changed once all of its players are migrated to Angular 2)

Unfortunately, there is no built in way to send a broadcast from an Angular 2 service to the Angular 1 $rootScope.$broadcast mechanism.

The Solution

At this point, it is either refactor the Angular 1 code to decouple the broadcast handlers from the components they live in (not a bad idea, since it'll have to happen during the migration anyways), or figure out a way to pass broadcasts between the two versions.

I opted for the latter since there are other places in the app that will need broadcasts all the way up until I'm fully migrated.

Caleb Williams and I were chewing on this challenge in the breakroom one day and this is the result!

First, we create a service that Angular 1 and 2 can both use to send each other broadcast messages.

This service has two public Subjects. One is for broadcasts coming from Angular 2 ( ng2Broadcasts ), and the other is for broadcasts coming from Angular 1 ( ng1Broadcasts ). It also has two convenience functions for updating each Subject.

The intent here is that each version's interested parties can subscribe to the broadcasts coming from the other version.

In my case, I want to just relay all broadcasts coming from Angular 2 straight onto $rootScope.$broadcast.

So we downgrade the BroadcastInterfaceService and do just that.

Then, in Angular 2 when you need to send a broadcast to Angular 1, you import BroadcastInterfaceService and call .sendToNg1().

Likewise, in Angular 1 code, we'd inject broadcastInterface and call .sendToNg2(). Unfortunately, there is no way to listen to all Angular 1 $broadcasts and relay them. Any interested party in Angular 2 needs to subscribe to the ng1Broadcasts Subject and listen for a specific message.

Final Thoughts

Broadcasts aren't really "a thing" in Angular 2 since everything is moving towards RxJs Observables, but during a migration it may not be possible to completely discard them. This is one way to bridge the gap in the interim.

It's been 2 months since I wrote about swapping $watch for observeOnScope, so I thought I'd post a follow up! In that 2 months we have finally found the time to educate the team on Observables and actually implement these swaps in our production application!

In doing so, we ran across a scenario that I hadn't covered in the "Quick-Swap" article.

The Problem

$watchGroup.

We had a couple of places where we had the need to detect changes on several objects, then run one function if any of them changed (think auto-sorting across multiple list of different types of objects).

It looks something like this:

Controller1.$inject = ['$scope'];  
function Controller1($scope) {  
    $scope.property1 = {};
    $scope.property2 = {};
    $scope.property3 = {};

    $scope.$watchGroup(['property1', 'property2', 'property3'], function(newValue, oldValue) {

        if (newValue && oldValue) {
            //Do Something        
        }
    }, true);
}

Since observeOnScope only takes one attribute (or function), we have a problem.

If you don't need to know which value actually changed, you could combine the object properties with a function and pass it into observeOnScope. However, in our case, our "on-change" function requires the most up-to-date data from all of the objects. With this method, we would have had to do change detection on our change detection in order to figure out which one of the objects actually triggered the change.

You also run into this same problem if you try to use Observable.merge which creates a single Observable out of multiple.

You could also break the "on-change" function up and split each object into its own Observable and Subscription. However, in our case, that would result in a lot of repeated code, which we didn't want to do.

The Solution

Enter Observable.combineLatest! This function accepts any number of Observables. Then when something changes, it emits a list of the most recent values for each Observable in the order that it was given to the combineLatest function.

It looks like this:

Controller1.$inject = ['$scope', 'rx', 'observeOnScope'];  
function Controller1($scope, rx, observeOnScope) {  
    $scope.property1 = {};
    $scope.property2 = {};
    $scope.property3 = {};

    rx.Observable.combineLatest(
            observeOnScope($scope, 'property1', true),
            observeOnScope($scope, 'property2', true),
            observeOnScope($scope, 'property3', true)
        )
        .subscribe(function(changes) {

          /*  changes will look like this:
             [
                  {newValue: {...}, oldValue:{...}},
                  {newValue: {...}, oldValue:{...}},
                  {newValue: {...}, oldValue:{...}}
             ]
         */
        });
}

As you can see, we now have a predictable object that gives us the new value for each "watched" property every time any of them change.

Final Thoughts

If you're wondering if there's a thing that rxjs can do, the answer is most likely "yes". There are a TON of helper functions and built in functionality. The hard part is finding it.

Thankfully, the documentation is continually getting better. Things like RxMarbles are also attempting to help with this.

In fact, here is the RxMarble for combineLatest!

Note: I wrote this article to help my teammates understand my quest to eradicate $watch in our application. I hope it helps someone else, too!

Observables are very powerful and have a lot of different functionality, but they can also be very simple to use. Here, we will convert a few $watch's to observeOnScope.

observeOnScope uses $watch in the background, but switching will gain you access to the wide world of Observers and will start to move you down the future path where Angular 2 has switched to exclusively using Observables for change detection.

The rx.angular.js Library

RXJS provides a helper library to use Observables on Angular 1.x projects.

Here is the documentation.

For this discussion, we'll only be using the observeOnScope function. You give it a $scope and an attribute and it creates an Observable with them.

Begin by adding rx.angular to your bower files.

bower install angular-rx --save  

Then add the files to your html.

<script src='http://blog.dustinnation.com/bower_components/rxjs/modules/rx-lite/rx.lite.js' ></script>  
<script src='http://blog.dustinnation.com/bower_components/rx-angular/modules/rx.lite.angular/rx.lite.angular.js' ></script>  
<script src='http://blog.dustinnation.com/bower_components/angular/angular.js' ></script>  

Tip: Make sure you import rx.angular.js before angular.js or it gets mad.

Note: The documentation doesn't say you need to import rxjs, but I had to.

Lastly, we need to declare RXJS as a dependency to our app.

angular.module('app', [  
  ...
  'rx',
  ...
]);

Converting Basic Watchers

Non-"controllerAs" controller

We'll start by looking at a controller that's directly using the $scope object. Here's its $watch:

Controller1.$inject = ['$scope'];  
function Controller1($scope) {  
    $scope.property1 = false;

    $scope.$watch('property1', function(newValue, oldValue) {

        if (newValue && oldValue) {
            //Do Something        
        }
    });
}

$watch expects the property name and the function that is to be run when the property changes.

Similarly, you'll need both when converting to observeOnScope.

It expects the following arguments:

• scope - the scope we're working on
• propertyName or function - the property name, or a function that returns the value to be checked. (The function will be called with the provided scope as its parameter.)

First, you'll need to declare observeOnScope as a dependency of the controller.

Controller1.$inject = ['$scope', 'observeOnScope'];  
function Controller1($scope, observeOnScope) {  
    ...
}

Then we define an Observable on the thing we were $watching. That definition would look like this:

observeOnScope($scope, 'property1');  

But you still need to tell the application what to do when the Observable changes. That is accomplished with a "subscription."

Subscriptions are functions that are called when the Observable changes. When fired, they are given an object that has the attributes newValue and oldValue.

observeOnScope($scope, 'property1')  
    .subscribe(function(change) {

        if (change.newValue && change.oldValue) {
            //Do Something        
        }
    });

That's it! You're done!

Here's what the controller looks like now:

Controller1.$inject = ['$scope', 'observeOnScope'];  
function Controller1($scope, observeOnScope) {  
    $scope.property1 = false;

    observeOnScope($scope, 'property1')
        .subscribe(function(change) {

            if (change.newValue && change.oldValue) {
                //Do Something        
            }
        });
}

Converting a controllerAs Controller

This conversion follows the same formula as described above, but you need to be careful to provide the right attribute name (just like you have to be careful with a $watch)

// controllerAs: 'ctrlAs'
ControllerAs1.$inject = ['$scope'];  
function ControllerAs1($scope) {  
    var vm = this;

    vm.property1 = false;

    $scope.$watch('ctrlAs.property1', function(newValue, oldValue) {

        if (newValue && oldValue) {
            //Do Something        
        }
    });
}

Becomes...

// controllerAs: 'ctrlAs'
ControllerAs1.$inject = ['$scope', 'observeOnScope'];  
function ControllerAs1($scope, observeOnScope) {  
    var vm = this;

    vm.property1 = false;

    observeOnScope($scope, 'ctrlAs.property1')
        .subscribe(function(change) {

            if (change.newValue && change.oldValue) {
                //Do Something        
            }
        });
}

Observing an Object's Attributes

Sometimes we need to detect changes on attributes of an Object. With $watch we could pass in the optional "deep" boolean parameter, like this:

$scope.object1 = {...};

$scope.$watch('object1', function(){}, true);

Similarly, you can tell observeOnScope to detect "deep" attributes changes. Like this:

$scope.object1 = {...};

observeOnScope($scope, 'object1', true)  
    .subscribe(function(){});

Unsubscribing from an Observable

Sometimes you need to cancel a $watch.

The $watch function returns a function that cancels itself. So you'd cancel it like this:

// controllerAs: 'ctrlAs'
ControllerAs1.$inject = ['$scope'];  
function ControllerAs1($scope) {  
    var vm = this;

    vm.property1 = false;

    vm.cancelWatcher = $scope.$watch('ctrlAs.property1', function(newValue, oldValue) {

        if (newValue && oldValue) {
            //Do Something        
        }
    });

    vm.cancelWatcher();
}

observeOnScope provides a similar feature, but it is a bit more nuanced.

Here's the code, followed by a bit of a technical discussion on what is happening (and why it's useful).

// controllerAs: 'ctrlAs'
ControllerAs1.$inject = ['$scope', 'observeOnScope'];  
function ControllerAs1($scope, observeOnScope) {  
    var vm = this;

    vm.property1 = false;

    vm.propertySubscription = observeOnScope($scope, 'ctrlAs.property1')
        .subscribe(function(change) {

            if (change.newValue && change.oldValue) {
                //Do Something        
            }
        });

    vm.propertySubscription.dispose();
}

This has the same effect as canceling a $watch, in that the function you provide to the subscription will cease to be called when the property changes. However, it has some subtle differences.

The result of calling .subscribe() is what is called a Disposable. This simply means that it's an object that can control whether or not it is active or stopped.

With rx.angular.js when a $scope is destroyed, all subscriptions to it are disposed of by default.

It's important to remember that there are two parts to the change detection now: the Observable and the subscriptions to it.

This allows you to provide an observable from a service, and let different parts of the application control their own subscriptions. So, disposing of a subscription in one controller will not affect the Observable or any other subscriptions to it.

Using a Function to Provide Subject of Observable

$watch can accept a function that returns the value you want to watch. For example:

// controllerAs: 'ctrlAs'
Controller1.$inject = ['$scope'];  
function Controller1($scope) {  
    $scope.property1 = 1;
    $scope.property2 = 2;

    $scope.$watch(function() {
            return $scope.property1 + $scope.property2;
        }, function(newValue, oldValue) {

            if (newValue && oldValue) {
                //Do Something        
            }
        });
}

observeOnScope allows you to pass in a function as well. It will even pass in the scope you provided in the first parameter to this function.

Controller1.$inject = ['$scope', 'observeOnScope'];  
function Controller1($scope, observeOnScope) {  
    $scope.property1 = 1;
    $scope.property2 = 2;

    observeOnScope($scope, function(scope) {
            return scope.property1 + scope.property2;
        })
        .subscribe(function(change) {

            if (change.newValue && change.oldValue) {
                //Do Something        
            }
        });
}

Notice we're using scope.property1 instead of $scope.property1 inside the "subject" function. While not always necessary, this can be really helpful if, for some reason, you need to pass in a different scope than the $scope that you're defining your Observable in. It is "best practice" to limit the scope of this "subject" function to its own closure.

Clean It All Up With Named Functions

If you're feeling feisty...

Controller1.$inject = ['$scope', 'observeOnScope'];  
function Controller1($scope, observeOnScope) {  
    $scope.property1 = 1;
    $scope.property2 = 2;

    observeOnScope($scope, getAdditionResult)
        .subscribe(onValueChange);

    ////////////////

    function getAdditionResult(scope) {
        return scope.property1 + scope.property2;
    }

    function onValueChange(change) {

        if (change.newValue && change.oldValue) {
            //Do Something        
        }
    }
}

Final Thoughts

This article barely scratches the surface of how you can use Observables, but it should give you the gist of how to do a quick 1-for-1 swap with $watch. Enjoy.

After setting up my first route, I decided to pull over the HTML template and the existing styles.

This post is basically a duplicate of the Stack Overflow question that I asked, and then answered myself.

The Problem

Here is the basic format of the pre-existing SASS:

src/app/styles/master.scss

@import 'folder/variables';
@import 'folder/headers';

src/app/styles/folder/_variables.scss

$header-bg: #ababab;

src/app/styles/folder/_headers.scss

h1 {  
  background-color: $header-bg;
}

Unfortunately, after following the instructions on the Github readme, I was getting build errors.

In short, it was complaining that it couldn't find the declarations for variables in one of the SASS partials.

Here was the error:

Build failed.  
File: /my-app/tmp/sassplugin-input_base_pathjFTXlfed.tmp/0/  
src/app/styles/folder/_more.scss (2)  
The Broccoli Plugin: [SASSPlugin] failed with:  
Error: Undefined variable: "$header-bg".  

The Solution

After spending way too much time Googling and searching Stack Overflow, I decided to go line-by-line in the Angular-CLI source to better understand the build process.

As I read, I noticed that there were many ".scss", but none for "_.scss". Just about that time the most recent commit message caught my eye.
feat(SASSPlugin): Allow regexes to be passed to include/exclude certa…

I clicked on the commit, and boom! There was the answer.

angular-cli-build.js

sassCompiler: {  
  cacheExclude: [/\/_[^\/]+$/]
}

You can read the actual commit, here

Final Thoughts

Such a simple solution that took up so much of my time. I have a feeling that as I move forward, I'll find a few more "gotchas" along the way. However, I'm sure the documentation will get better over time, too.

In the interim, I've just been generating a component, renaming all of the files with a "+" if I want that route lazy loaded, then manually inserting the router config.

Lately I've been trying to teach myself Angular 2. Having watched ng-conf talks, I figured that since the angular-cli was more-or-less "blessed" by the Angular team, it might be a good way to spin up some example projects. However, I soon hit a snag.

The Problem

As of the time of writing this, generating routes with the angular-cli does not work out of the box.

Running ng new my-app creates the structure and you start with the following:

my-app.component.ts

import { Component } from '@angular/core';

@Component({
  moduleId: module.id,
  selector: 'my-app-app',
  templateUrl: 'my-app.component.html',
  styleUrls: ['my-app.component.css']
})
export class MyAppAppComponent {  
  title = 'my-app works!';
}

Adding your first route with ng generate route my-route leaves you with:

my-app.component.ts

import { Component } from '@angular/core';  
import { MyRouteComponent } from './+my-route';  
import { Routes , ROUTER_DIRECTIVES, ROUTER_PROVIDERS} from '@angular/router';

@Component({
  moduleId: module.id,
  selector: 'my-app-app',
  templateUrl: 'my-app.component.html',
  styleUrls: ['my-app.component.css'],
  directives: [ROUTER_DIRECTIVES],
  providers: [ROUTER_PROVIDERS]
})
@Routes([
  {path: '/my-route', component: MyRouteComponent}
])
export class MyAppAppComponent {  
  title = 'my-app works!';
}

Note: I recently tried this on my work laptop and none of the ROUTE_PROVIDERS business was included.

All good, right? Unfortunately, if you navigate to /my-route nothing happens. Bummer.

The Solution

Fear not! All it takes to get the router to work is to wire up a few more things.

Credit: https://github.com/angular/angular-cli/issues/708

First, you need to add "Router" to the other router imports. Then all you need to do is add a constructor in my-app.component.ts. Its as simple as constructor(private router:Router) { }

Without further ado, here's the final result:

my-app.component.ts

import { Component } from '@angular/core';  
import { MyRouteComponent } from './+my-route';  
import { Router, Routes , ROUTER_DIRECTIVES, ROUTER_PROVIDERS} from '@angular/router';

@Component({
  moduleId: module.id,
  selector: 'my-app-app',
  templateUrl: 'my-app.component.html',
  styleUrls: ['my-app.component.css'],
  directives: [ROUTER_DIRECTIVES],
  providers: [ROUTER_PROVIDERS]
})
@Routes([
  {path: '/my-route', component: MyRouteComponent}
])
export class MyAppAppComponent {

  constructor(private router:Router) { }

  title = 'my-app works!';
}

Final Thoughts

There is also one more way to make the routes work. If you add a routerLink to my-app.component.html the router will get instantiated behind the scenes. But that's not always the way you need to go about things.

Now that routing's out of the way...maybe I can get SASS working in the build process.

Happy cli-ing and routing!

Earlier this year I had the realization that if I left the project, it would either die or be completely re-written by the next guy. It wouldn't suffer this fate because I've written bad code, but because I'd been using the large feature backlog as an excuse to neglect all of the non-code parts of the project that enable developers to be effective.

The project in question is an application I helped conceive and something that has the potential to make the lives of our internal business customers much easier. Needless to say, I've got an emotional attachment to it and want to see it survive whether I'm working on it or not.

So, I set out to fix the situation. I did some research to try and figure out what best practices and tools I could use. After some time I was able to put together a list of things I needed to do in order to harden my project against turnover (or make on-boarding new teammates much easier).

Disclaimer

These articles are written to serve as a jumping off point for someone in a similar situation. They are intended as an entry level discussion. I give some tips on how I implemented the discussed concepts as I produced features, but those who are an on a mature team probably won't gain much from this series.

The List

1. Git the most out of version control (see what I did there?)
2. More better documentation
3. Implement a coding style guide
4. Easily reproducible environments
5. Testing...ugh
6. Utilize build tools
7. Setup continuous integration

Version Control

“Any kind of practice that tracks and provides control over changes to source code” - Wikipedia

Most of us use or have at least heard of version control before. But for those that are new to the subject, its just a system of keeping track of the changes you've made to your code.

Version Control Systems

Software that helps track these changes are called Version Control Systems (VCS).

There are 3 major VCSs to be aware of. They share many of the same major features but have some significant implementation differences. I encourage you to try them all out and choose one that fits your way of thinking and meets your needs.

1. Git
2. Mercurial
3. Team Foundation Server VCS

Git

Git is currently the most popular of the 3 due largely to its widespread adoption in the open source world. Most open source tooling around VCSs assumes that you're using Git. It has been described as the "MacGyver" of VCSs because it has lots of utility functions and there seem to be multiple ways of accomplishing the same thing.

Most of the online repository services support Git, including Github, Bitbucket, and Team Foundation Server.

Mercurial

Mercurial debuted around the same time as Git in 2005. It was a strong competitor to Git until around 2010 when Git seemed to gain critical mass. It has been described as the "James Bond" of VCSs because many people believe usage of it to be more elegant than Git.

The main online repository service that supports Mercurial is Bitbucket.

Team Foundation Server VCS

This is Microsoft's VCS. If your company is mainly a Microsoft shop, there's a good likelihood that you'll want to use TFS as it integrates nicely with all of the Visual Studio environments and tooling.

As you might expect, its only supported by TFS.

VCS Tools

There are many tools out there focused on providing a GUI for VCSs.

Some Git standouts are Tower, Github's Windows client & Github's Mac Client, and SourceTree.

Some Mercurial standouts are SourceTree and TortoiseHg.

TFS is tightly integrated into Visual Studio IDE.

My favorite is SourceTree because I can use it for my Git and Mercurial projects, but you should check them all out and choose the one that best fits you and your needs.

Issue Tracking

Many of the VCS services provide a way for developers and users to submit issues and discuss them. I won't get into issue tracking much here besides to say that many developers, even solo developers, find issue tracking to be a fantastic way of keeping track of required maintenance for their applications.

Commit Messages

Once you're using version control, one of the most important things you can do to help your team understand the changes happening on the project is to write good commit messages.

Good commit messages describe 3 things.

1. The issue being fixed or feature being added
2. The changes made and the rationale behind them
3. Any side-effects the changes bring

Examples

Bad Commit Message

commit -m "Fixed a spinner bug."  

Notice 2 things here.

Firstly, the message is incredibly vague. What spinner bug? Where is it? How'd you fix it?

Secondly, its written in the command line. Executing VCS commands from the command line is not necessarily a bad thing, however, committing from the command line makes it very hard to craft good messages.

Good Commit Message

From a VCS tool

Stops the spinner from showing on form A's "ok" button hover (#123)

Removes the event trigger that caused the spinner to show when the user hovers over the "ok" button.  

As you can see, this message was written in a VCS tool. This allows you to format the message in a way that's conducive to writing good, informative commit messages. Some of the tools even allow you to write commit messages in markdown. Fancy!

You'll also notice how specific the first line is. It explains the issue being addressed and also where in the application you'd find the issue (Form A's "ok" button). It even has a reference to an issue number (the VCS you use may have a more integrated way of linking commits with issues).

The second paragraph explains what was done to address the issue. This is where you can get a bit more technical and where you'd go into rationale if necessary.

Branching

Branching is a feature of VCSs that allows you to make as many changes to your code as you want while still maintaining a version that is ready for your users. When you're done making changes, the VCS will assist you in "merging" all of your changes back into the main version.

The Theory

Take the following example:
http://www.gamasutra.com/db_area/images/feature/5900/image001.png

In this example there is a main development branch. A branch for Feature A is started, but before it is finished Feature B is started in its own branch. Likewise, before Feature B is finished, Feature C is started in its own branch. After that Feature B is finished and merged back into the main development branch, then Feature C, then finally Feature A.

The theory here is that at any point in developing Feature's A, B, or C the main development line could be put into production.

My Branching Scheme

The branching scheme I use is based off of a Mercurial plugin called Hg Flow which is also a built in feature in SourceTree. There exists a "Git Flow" as well, but I have little experience with it.

It looks a little something like this:

The heart of the repo is the development branch. It is the branch from which features are started and the branch that completed features join the herd. When a substantial feature set is finished, the development branch merges into the production branch.

Hg Flow and Git Flow have convenience functions to facilitate this including a "Start Feature" button that opens a new branch and even namespaces the feature with "feature/".

Conclusion

Version control is the most basic, yet most powerful thing you can do to start working in a team-friendly environment. Its easy to take shortcuts in branching workflow and in writing commit messages, and we all do it from time to time. However, creating and following VCS guidelines will enable your team and save you from unexpected headaches.

Update

Due to low interest and homeownership keeping me from having as much free time as expected, I have suspended work on this project. I fully intend to pick it back up later in the year. In the mean time, the code is up (as promised) at https://github.com/d-nation/soccer-sim-engine

I've documented it as much as possible. Feel free to use it, improve it, or show me how I'm doing NodeJS wrong! Its my first go at making a Node project, so any feedback is welcome.

Introducing: 3Deke

https://github.com/d-nation/soccer-sim-engine

I've begun creating a service that I'm describing as a "Fantasy Sports Simulation as a Service".

There are a lot of people out there who participate in fantasy sports "sim leagues." However, the means of actually simulating a league's games can be a clunky, time consuming, and tedious task for league operators. Some are forced to manually sync their league's rosters with a video game while others are left to use ancient csv-driven desktop software.

Is this a fantasy sports league?

No. This is simply a simulation engine to be used by "sim league" operators and developers.

I will be standardizing on a player ability ranking scheme (most likely it will align with the EA Sports player abilities), but 3Deke will not be maintaining any type of player, team, or league database. This will allow users to use the game engine in any way they wish and not be beholden to any arbitrary league constraints.

Your league, your way.

How will 3Deke help "sim league" operators/developers?

With 3Deke I aim to make life better for league operators/developers by creating an API driven simulation engine. This opens the possibility for a league to automate simulation straight from league data already saved in the user's own site.

The game engine API will accept basic league information such as team rosters and player ability rankings to start a simulation. When the simulation is finished, the game details can be sent to a callback URL or retrieved upon request. It will even save a play-by-play so that a league's participants can see exactly how a game unfolded.

What sports will be available?

I'm starting with soccer (futbol). The idea for this whole service was sparked by an iPhone "Footy Manager" game, so I decided to start there.

My two main sports passions are the English Premier League and the NHL, so as soon as the soccer engine reaches a viable state, I'll be expanding to a hockey simulation engine.

If there's demand for a different sport following the completion of these two, I'll work on them then.

How detailed will game output be?

Very. Eventually.

I'm creating this in such a way that almost everything about the game can be tracked and reported. However, detail takes time.

Starting out, there will be very basic game statistics such as score and discipline. Over time, new game information will be added such as injuries and substitutions.

Can I trust the game engine?

Yup. It's my plan to open source the engine portion of the service. This provides transparency as well as opens up the engine for peer review and community contributions.

If you're ambitious, you could even use the open source code to implement your own engine service.

What's the timeline?

This is a side project for me, so it'll inevitably take longer to create than I'd like.

That having been said, its my goal to get a very basic version of the engine completed prior to the World Cup finals in order to "predict" a winner. After that minimally viable product (MVP to those in the biz) is ready, things will start rocking. That's the point in which I'll open source the engine and open up the API to beta testers.

What's with the name?

3Deke is a play on the gamer tag I've had since I started playing Eve Online years and years ago (Triple Deke). A "deke" is the hockey equivalent to a "juke" in American football. Remember The Mighty Ducks?

Update (7-29-14)

Due to low interest and homeownership keeping me from having as much free time as expected I have suspended work on this project. I fully intend to pick it back up later in the year. In the mean time, the code is up (as promised) at https://github.com/d-nation/soccer-sim-engine

The Problem

This is all well and good, except that I am building a very large single page app that will have a multitude of modules and views. Do I even need to say how non-maintanable having all of your templates for all of your modules and views on your app's single HTML page is?

So then how does one supply templates to views in a way that's maintainable?

My First Solution

Under a time crunch, and with Google-foo failing me, I came up with a solution that got me part of the way there. I created a requireJS module for each Marionette module that exported a big object of template strings.

The file structure went something like this:

App/  
    -module/
        -models/
        -views/
            -mainView.js
        -module.js
        -templates.js

And the templates.js file looked something like this:

define(function(require){  
    "use strict";

    var template1 =
            "<h1>Hey there!</h1>\
            <p>How goes, <%= name %></p>,

        template2 =
            "...";

    return {
        template1: template1,
        template2: template2
    };
});

This solved a lot of my problems, but still left me with some maintainability nightmares. Here's a pro-con list:

Pros

• No templates in the main HTML file
• Templates live under their modules, keeping modules more modular
• Only one requirement import per view

Cons

• Writing HTML in Javascript (barf)
• A module with lots of templates will have a bloated templates.js file

A Better Solution

This worked for getting me started, so I rolled with it. However, over time the con's listed above really, really bothered me. My IDE's syntax highlighting hated me for it, I had to constantly fight the ' vs " battle in writing HTML strings, keeping track of \'s at end of the lines was hard, and once my views started to use conditional templating and micro-templating, these files got to be hundreds of lines long. Not good.

So, once I'd had enough, I started asking around on Twitter. A lovely user named Boris (@zbzzn) enlightened me to a part of requireJS I'd overlooked...the text plugin. It allows you to declare HTML files (or other text files) as dependencies.

Great! I dropped the text.js file in my app's main folder and got cracking. Now I could separate each template into its own file and pull them in like this:

module/templates/main.html

<dir>Main Template</dir>  

view.js

define(["marionette", "text!module/templates/main.html"],  
    function (Marionette, mainTemplate) {
        "use strict";

    return Marionette.ItemView.extend({
        template: _.template(mainTemplate);
    });    
});

Pros

• No templates in the main HTML file
• Templates live under their modules, keeping modules more modular
• HTML written in HTML

Cons

• Views with multiple templates will need to import multiple files (can get overwhelming)

This alone takes a huge stride towards better maintainability, and for many (most?) this is perfect. However, if you're doing conditional templating and/or micro-templating this method also means that many of your views will need to import multiple templates (I have a few views with 10+ templates). Keeping track of that many imports in the require syntax is a nightmare and creates a ton of unique variable names inside the require module that you have to then remember and not use again.

My Solution

Ok, here's where I get crazy. The con of the previous method of handling templates is actually a pro of the first method I used. "Why not combine them?" I thought. So I did.

I ended up with the following:

App/  
    -module/
        -models/
        -views/
            -mainView.js
        -templates/
            -main.html
            -main-alt.html
            -templates.js
        -module.js

templates.js

define(["text!module/templates/main.html",  
        "text!module/templates/main-alt.html"],
        function (main, mainAlt) {
    "use strict";

    return {
        "main": main,
        "mainAlt": mainAlt
    }
});

mainView.js

define(["marionette", "module/templates/templates"],  
    function (Marionette, templates) {
        "use strict";

    return Marionette.ItemView.extend({
        template: function(serializedModel){
            if (someCondition){
                return _.template(templates.mainAlt);
            } 

            return _.template(templates.main);            
        }
    });    
});

In essence, I moved the multiple template imports into a require module whose only responsibility is templates. Each view now only imports one file for templates, giving the view logic the clear focus. If you need to add, remove, or change the name of a template, it is done in one place. Make your changes in templates.js then in your view, simply change the attribute you're looking at without needing to also change your require import paths.

Final Thoughts

Creating a separate template require module for each Marionette module may seem like I'm adding an unneccessary layer. Maybe. But it gives me a much cleaner view as well as one central access point for templates across all of the module's views. What's more, is that in addition to all of the pro's on both of my lists, after I type the . in templates. I get IDE code completion! No more needing to remember the exact variable name I gave them all when importing. Bonus!

Hate it? Love it? Let me know on Twitter (@D_Naish)

You see, I am the only front-end engineer, developer, and designer on my team. We spent the bulk of last year feverishly releasing feature after feature just to ensure the project didn't lose funding. However, in order to do this I all but neglected documenting anything about my browser-side code.

The Problem

While I've been very diligent in creating a maintainable code base and most of it is pretty straight-forward, I had no documentation around the event-driven parts of my application. To anyone else, it would be very hard to follow the flow of how and what happens when events are triggered.

I decided that I would start with a good code documentation tool. In the past I'd used JSDoc-Toolkit and was pleasantly surprised to see that it had been ported to NodeJS and continued on as JSDoc3.

The awesome part is that it includes several tags for documenting event driven code. The not-so-awesome part is that the tool's usage with Require and Backbone/Marionette is...well...it's less than intuitive at best. This is compounded by spotty documentation and seemingly contradictory advice on Stack Overflow and their Google Group.

The (My) Solution

What I quickly learned is that using JSDoc3 on your RequireJS + Backbone project is less of a science and more of an art. Depending on the coding style, you may be forced to override the functionality of many of the tags. Doing so gives you a lot of flexibility but also requires more work to be done by hand. You can also use this flexibility to tweek how the documentation looks in the generated documentation webpages.

The following is a brief overview of how I chose to implement JSDoc on my project. I'd encourage readers to experiment and explore if this isn't exactly what you're looking for.

The example project structure I'm going to use is as follows:

App  
 -Module1
    -models
        -model1.js
    -collections
        -collection1.js
        -collection2.js
    -views
        -view1.js
    -module1.js
    -vent.js
    -reqres.js    

Models and Collections (Basic)

Lets start with the most basic documentation, a require definition that defines only one model or collection.

Basic Model

The first thing you have to do is to tell JSDoc what this require definition is defining. This is done by placing an @exports tag prior to your define block.

/**
 * @exports module:Module1.Module1/Models/Model1
 */
define(['backbone'], function (Backbone) {  
    "use strict";
    ...
});

You'll notice the module:Module1. prefixing the model's path. If you're using a module or otherwise subdividing your code, you'll want to use this to ensure that the documentation webpage reflects this subdivision.

Also of note is that I'm using capitals for the path. This is partly due to the convention of capitalizing class names, but for me it is mainly stylistic for the webdocs.

Next, we need to define the model as a class. We do that using the @constructor tag.

/**
 * @name module:Module1.Module1/Models/Model1
 * @constructor
 * @augments Backbone.Model
 */
return Backbone.Model.extend({  
    ...
});

Here also use the @name tag to make sure that the class's name matches up with the name we told JSDoc that we're exporting and the @augments tag to specify that we're just adding onto the Backbone.Model object.

Lastly, we need to tell JSDoc that the object being added to Backbone.Model via .extend() is actually the same thing as the class we just told it about. This is done using some tag placement trickery and the @lends tag. It looks like this...

return Backbone.Model.extend(  
  /** @lends module:Module1.Module1/Models/Model1.prototype **/
  {
      ...
  });

Be careful to place the tag comment inside the extend openning parenthesis and the object definition's opening curly-bracket.

Once all of this is taken care of, JSDoc can figure out all of the attributes and functions you add in the model's definition using basic JSDoc techniques.

For example, adding a URLRoot function to the model would look like this...

return Backbone.Model.extend(  
    /** @lends module:Module1.Module1/Models/Model1.prototype **/
    {       
        /**
         * Specify the URL root to fetch from
         * @returns {string}
         */
        urlRoot: function(){
            if(this.get("isCool")){
                return "../cool/"
            }
            else{
                return "../not-cool/";
            }
        }
    });

Putting it all together...

model1.js

/**
 * @exports module:Module1.Module1/Models/Model1
 */
define(['backbone'], function (Backbone) {  
    "use strict";
    /**
     * @name module:Module1.Module1/Models/Model1
     * @constructor
     * @augments Backbone.Model
     */
    return Backbone.Model.extend(
        /** @lends module:Module1.Module1/Models/Model1.prototype **/
        {
            /**
             * Specify the URL root to fetch from
             * @returns {string}
             */
            urlRoot: function(){
                if(this.get("isCool")){
                     return "../cool/"
                }
                else{
                     return "../not-cool/";
                }
            }
        });
});

Basic Collection

Basic collections are documented very similarly to basic model definitions. However, there is one concept that is added: linking in your model in the documentation.

Documenting the link between the collection's model and the already documented model definition also links them on the generated documentation website, which is very convenient.

The linking is done via the @type tag.

collection1.js

/**
 * @exports module:Module1.Module1/Collections/Collection1
 */
define(['backbone', 'models/model1'], function (Backbone, Model1) {  
    "use strict";
    /**
     * @name module:Module1.Module1/Collections/Collection1
     * @constructor
     * @augments Backbone.Collection
     */
    return Backbone.Collection.extend(
    /** @lends module:Module1.Module1/Collections/Collection1.prototype */
    {
        /**
         * This collection contains model1s
         * @type {module:Module1.Module1/Models/Model1}
         */
        model: Model1,

        /** URL to item list */
        url: "/collection1/"
    });
});

Models and Collections (Advanced)

Sometimes you need/want to create multiple models, collections, or both in the same require definition. This can be a bit tricky to document in JSDoc.

My most common use case for this is with ItemViews and CollectionViews, which I'll cover in part II. Another common use case for me - and the one I'm going to use here for an example - is when I have a model that is tightly coupled to a collection (meaning that the model only exists for the purpose of filling this one particular collection).

In this scenario the file define's and returns a collection but also creates an internal model to be used by the collection. This seems to confuse JSDoc, so we have to give it a little extra help.

First, document the definition just as we did before. With the exception that we no longer need to reference an external model.

collection2.js

/**
 * @exports module:Module1.Module1/Collections/Collection2
 */
define(['backbone'], function (Backbone) {  
    "use strict";
    ...
});

Then, we create the model.

/**
 * @exports module:Module1.Module1/Collections/Collection2
 */
define(['backbone'], function (Backbone) {  
    "use strict";

    /**
     * @name module:Module1.Module1/Models/Model2
     * @constructor
     * @augments Backbone.Model
     */
     var Model2 = Backbone.Model.extend(
        /** @lends module:Module1.Module1/Models/Model2.prototype **/
        {
            /**
             * Specify the URL root to fetch from
             * @returns {string}
             */
            urlRoot: function(){
                if(this.get("isAdvanced")){
                     return "../cool/"
                }
                else{
                     return "../not-cool/";
                }
            }
        });
    ...
});

You'll notice that Model2 is tagged in the same way that the stand alone Model1 is above.

Now comes the trickery. After this point, JSDoc really gets confused. We document the collection just like we did above with a "basic" collection, but unfortunately, we have to help it by adding in a @memberof! tag to each of its attributes. The ! at the end of the tag serves to tell JSDoc that it needs to listen to this tag and not try to figure things out on its own.

Here's what the whole thing looks like:

collection2.js

/**
 * @exports module:Module1.Module1/Collections/Collection2
 */
define(['backbone'], function (Backbone) {  
    "use strict";

    /**
     * @name module:Module1.Module1/Models/Model2
     * @constructor
     * @augments Backbone.Model
     */
     var Model2 = Backbone.Model.extend(
        /** @lends module:Module1.Module1/Models/Model2.prototype **/
        {
            /**
             * Specify the URL root to fetch from
             * @returns {string}
             */
            urlRoot: function(){
                if(this.get("isAdvanced")){
                     return "../cool/"
                }
                else{
                     return "../not-cool/";
                }
            }
        });

    /**
     * @name module:Module1.Module1/Collections/Collection2
     * @constructor
     * @augments Backbone.Collection
     */
     return Backbone.Collection.extend(
     /** @lends module:Module1.Module1/Collections/Collection2.prototype */
     {
         /**
          * This collection contains model1s
          * @memberof! module:Module1.Module1/Collections/Collection2
          * @type {module:Module1.Module1/Models/Model2}
          */
          model: Model2,

         /** 
          * URL to item list 
          * @memberof! module:Module1.Module1/Collections/Collection2
          */
         url: "/collection2/"
     });
});

Final Thoughts

Documenting this flavor of Marionette code with JSDoc can present some challenges and can be a downright hassle at times. However, the generated documentation webpage and in-code documentation provide clarity of intent and make it well worth it.

In part 2 I will cover the documentation of Views and Event-Driven code.

On Comments

I grew tired of the 1000's of spam bot comments on my previous blog engine so feel free to contact me on Twitter ( @d_naish ) if you like this article, hate it, agree with me, or think I've got it all wrong...or just want to say hi.

Meetup Details: http://www.meetup.com/DallasJS/events/165754952/

Topic: Real Time Puppetry with Marionette and Firebase

Description:

A brief overview of Firebase.io, Marionette, and how to connect them for painless real time updates of your views.

I'll post the slides and example code here aftwerwards.

As I've alluded to previously, the main project I'm currently working on is an energy/building performance application. One of the requirements is a dynamically populated, interactive chart for historical values of different building parameters (ie room temperatures, heating/cooling modes, etc). The charting library we chose to use for this is called Highstock. It is a specialized version of the Highcharts library that provides a "preview" slider below the actual data, allowing a user to change the date range by sliding some handles around.

The Problem

Out of the box Highstock does much of what I need it to extremely well and very easily, but it feels like its still trying to make the transition from a static "generated once" chart to something that can easily handle interactions such as adding and removing series on the fly and adding data to series that are currently charted.  They have some helper functions that approach these things, but they don't quite address my requirements, so as I encounter needs like these, I end up writing work-arounds.

I currently default all of my charts to start with 30 days of data. However, users frequently need much larger time ranges. I wanted to set up a system where the user puts in a different date and the app determines if it needs to go get more data. Unfortunately Highstock's date-range input validates the user input against the range extremes in the data to make sure the input isn't outside of the current data's date range. This means that if if my chart currently starts on and has data starting on October 10th, inputting October 1st would not pass validation and nothing would happen. Bummer.

So I asked around in their forums and on Stack Overflow and was basically told to edit the Highstock source code. It wasn't hard to find the part that needed to be changed and only 2 lines needed 6 words commented out, but if I edit their source it puts me in charge of maintaining that source going forward.

The Solution

Luckily Highcharts has some fairly decent documentation on how to make a plugin! So that's what I went about doing.

It was pretty straight-forward, but I did have to do a lot of learning about the context that the plugin code runs in. I basically copied the original code that I'd have had to modify out of the source and into the plugin. I made my changes (commenting out like 10 words) and set about figuring out how to get all of the variables in that code defined by the variables accessible to code in the plugin.

Here's the result!
Highstock plugin repo: http://www.highcharts.com/plugin-registry/single/12/Beyond-Extremes
Github page: https://github.com/d-nation/highstock-beyond-extremes

Final Thoughts

I'm not a Highcharts expert, nor am I a plugin guy, but I was presented with the option of taking on a maintainer role for our own version of Highstock, or to write a plugin to augment the original source. With just that criteria it was an easy choice, but when I added in the fact that I could publish it and help out other developers...no brainer.

The Problem

Recently at work we had the need for a real-time notification system. When an event in our system fires, our users need to be alerted live and be able to clear the notifications when they'be been addressed. The problem is that we're a small shop under a time crunch. The other two developers on the team were busy, leaving me to worry about both the back-end and the browser.

The Solution

Enter Firebase. I'm probably going to butcher this and/or sell them short, but... Firebase is a No-SQL database as a service. They offer both REST and websocket interfaces along with full blown security features. Best of all...they maintain a Backbone extension called Backfire!

Backfire is basically a drop in replacement for Backbone Collection that establishes and maintains a connection to the Firebase database of your choosing. Any changes to the database are automatically reflected in the collection and vice-versa.

That sounded like a pretty good match for the Marionette Collection View. Turns out...it is the perfect marriage!  I was able to implement a solution in about 5 hours, even though I'd never used Firebase/Backfire before!

Note: It would've been much quicker, but I had some trouble dynamically specifiying the Firebase I wanted Backfire to point to.  I'll cover it in the tutorial so fear not!

Nitty Gritty

I'm also preparing a tutorial with a sample app, so I won't get into much code detail in this post. I will however, go over the system architecture I used to implement the real-time notification system.

Environment

• Backend: Python running in AWS
• Web-framework: MarionetteJS

Flow

1. A notification is sent from the system to my firebase processing code (Documentation)
2. My Firebase processing code sends a REST call to Firebase
3. Firebase adds the data from the REST call to the database
4. Firebase syncs the new data with any listeners (any connected Backfire collections)
5. Marionette's Collection View knows that there's a change and renders the added notification
6. A user clicks on the "clear button" which removes the model from the Backfire collection
7. Backfire syncs the deletion with Firebase

Diagram

I felt like drawing, so here's the above flow in picture form...

Final Thoughts

This combination was a real time-saver. The amount of total code required to make real-time changes show in your web app is ridiculously low.

Stay tuned later this week for a tutorial...

3/3/14 Update: this tutorial is still in the works...sorry. But I'm giving a talk on it on 3/6/14 at the DallasJS meetup.

The Background

In a previous post I talked about how to make MarionetteJS modules into little reusable apps for use within your big app. However, whilst using this at work I realized that there was something missing.

The Problem

One of the ways I'm using modules like this is with a configuration modal. The configuration can be a new configuration, or it can be an edit to an existing one. The module that is starting up the configuration module already has all of the information that will be needed to edit a particular configuration, it just needs to get it into the freshly started module.

Following? I'm not sure even I am.

Let me try again.

Sometimes I need to pass info to a module when its starting up that may change by the next time the module is started up again.

The Solution...or so I thought

Well, here's where I admit to a mistake. The documentation says you can pass in "any custom arguments" so I tried to do this:

module1.js

define(['marionette', 'mainLayout'], function (Marionette, MainLayout) {  
    "use strict";

    return function(Module1, App, Backbone, Marionette, $, _, options ){
        ...
        this.addInitializer(function(){
            //Do something with the options here, like send them to the layout
            Module1.regions.main.show(new MainLayout({options: options));
        });
        ...
    };

});

And then start it up like this (in App.js or in another module)

var options = {config: some_pre_determined_configuration};  
App.module(name, functionDef, options);  

Technically this works, but not the way I thought. I was thinking that I could pass in arguments every time I started it back up. Turns out that the module only gets the options the first time the "App.module" method is called on the definition function.

Maybe I should've read the docs a bit more closely, because I couldn't figure out why the options I was sending in on the 2nd and 3rd times weren't there.

The (real)Solution

To get around this, I turned to a new old friend: RequestResponse.
I created a "moduleOptions" object in the parent who's doing the starting up the modules.  It will hold any information that any of my modules may need for the next time they start up.

In App.js or in another module that is calling a minion

App.moduleOptions = {};  

Then I setup request handlers as a "getter" and a "setter" for moduleOptions

In App.js or in another module that is calling a minion

reqres.setHandlers({  
    setModuleOptions: function(moduleName, options){
        App.moduleOptions[moduleName] = options;
    },
    getModuleOptions: function(moduleName){
        return App.moduleOptions[moduleName];
    }
});

As you can see, both handlers require a module name.  This is in case you have multiple modules that need options.  It prevents you from having to explicitly define a new variable under App every time you add a new module type.  Instead they just get thrown under App.moduleOptions, keeping your App code nice and clean.

Ok, so now that I've got a way to set the module's start up options and tell it about those options, I just have to make the module ask for them when he/she starts up.

Module1.js

this.addInitializer(function(){  
    ...
    Module1.startOptions = reqres.request('getModuleOptions', "Module1");
    ...
});

I typically don't like to manually put in "Module1" as the argument in case I decide to change the name of the module.  So I pass in Module1.moduleName instead of "Module1".  The less I have to change when I make a change, the better.

Full Examples

App.js

define( ["marionette", "module1”, “app_reqres”], function (Marionette, Module1, reqres) {  
 "use strict";

    var App = new Marionette.Application();
    App.moduleOptions = {};

    //These could be called directly in App.js, but I'm using the reqres
    //to show how one might start another minion from a module.
    reqres.request("setModuleOptions", "Module1", {
        version: "version#",
        regionContainer: ".module1-##" //substitute ## for a unique identifier. I just use an auto-incremented counter
    });
    reqres.request("startModule", null, "someName", Module1);

    App.infoToShare = “Share Me”;

    reqres.setHandlers({
        startModule: function(parent, name, functionDef){
            //Handle sub-modules
            if(parent != null){
                App[parent.moduleName].module(name, functionDef);
            }
            //Handle top-level modules
            else{
                App.module(name, functionDef);
            }
        },
        getInfo: function(){
            return App.infoToShare;
        },
        setModuleOptions: function(moduleName, options){
            App.moduleOptions[moduleName] = options;
        },
        getModuleOptions: function(moduleName){
            return App.moduleOptions[moduleName];
        }
    });
});

Module1.js

define(['marionette', 'app_reqres', 'mainLayout'], function (Marionette, app_reqres, MainLayout) {  
    "use strict";

    return function(Module1, App, Backbone, Marionette, $, _){
        this.addInitializer(function(){
            var rm = new Marionette.RegionManager();

            Module1.startOptions = app_reqres.request('getModuleOptions', Module1.moduleName);

            this.regions  = rm.addRegions({
                main: Module1.startOptions.regionConainer
            });

            Module1.regions.main.show(new MainLayout());
        });

        this.addFinalizer(function(){
            Module1.regions.main.close();
        });
    };

});

Final Thoughts

• I totally get now why it didn't work the way I thought it would.
• Wreqr makes me happy.
• When all else fails, read the docs a little closer.