Apple’s xCode ships with OCUnit which is “a faithful implementation of xUnit patterns for Objective-C”[Vollmer]. Though useful for testing (it provides the various combinations of assertions covering nulls, exceptions, true, false, and equality), it lacks the capability to produce mock objects. That’s where OCMock comes in. OCMock is a library that works with Objective-c and provides methods that allow you to employ mock objects throughout your own applications. In this post, I’ll be walking through the setup of OCMock in Apple’s xCode environment and running through a few basic use cases for the OCMock library.

 Setting up OCMock

 Before we begin, here’s a rundown of my current environment:

• xCode Version: 4.6.2
• OCMock Version: 2.1
• Objective-C Version: 2.0

“The linker tries to be clever and only includes those symbols that it thinks are used. It gets this wrong with Objective-C categories, and we need to tell it that (a) we’re dealing with Objective-C and (b) that it should load all symbols for the OCMock library.”

If the path to your files is not clearly defined in at least 3(!) places, you will get errors and nothing will work correctly. A third gotcha; the default selection for the project settings is the main project. Your tests (and OCMock) are their own project by default. You have to switch the target from the main project to the test project otherwise you’ll have the right files referenced by the wrong project (and still get errors when you try to use OCMock to test).

OCMock comes in two flavors. There is a framework version and a static library version. In order to do iOS development, you’ll need to use the static library version NOT the framework. The difference between the static library and the framework is how they are deployed with the project. Static libraries are compiled and their binaries are integrated with the application binaries on a compile. Frameworks are linked to and then referenced. Since there’s not a great way to make sure that the end users will have a particular version of a framework installed (without installers/unnecessary complications), static libraries are the best choice for iOS development.

 Setting up Unit Tests

 For this example, I coded up an app that will find the lowest number divisible by all integers from 1 to some arbitrary positive integer supplied by the user (restricted by the maximum value of an int). I originally solved this problem in Java with goals of efficiency and compactness. To facilitate this example, I ported it over to Objective-C following TDD practices. Here’ the original function and my thoughts on breaking it down into testable pieces:

    public String solve(int limit) {
        int[] numbers = new int[limit+1];
        BigInteger result = new BigInteger("1");
        for(int i = 0; i < numbers.length; i++) {
            numbers[i] = i;
        }
        for(int i = 2; i < numbers.length; i++) {
            if(i > 1) {
                result = result.multiply(new BigInteger(String.valueOf(numbers[i])));
                for(int j = i+1; j < numbers.length; j++) { 
                    if(numbers[j] > 1 && numbers[j] % numbers[i] == 0) { 
                        numbers[j] /= numbers[i];
                    }
                }
            }
        }
        return result.toString();

The Setup Phase

Here’s the first piece I considered:

public String solve(int limit) {
        int[] numbers = new int[limit+1];
        BigInteger result = new BigInteger("1");
        for(int i = 0; i < numbers.length; i++) {
            numbers[i] = i;
        }

These operations result in assignment and population (note the actual size of the array is limit+1). In the context of an iOS app, the limit would be a return from user input and would define the dimensions of the numbers array. The array population can be broken out of this section and into its own function to facilitate separate unit testing. In xCode, I wrote the following tests for this piece:

-(void)testInputFieldToNumberConversion {
    [[[inputField stub] andReturn:@"3"] text];
    [[[beController userLimit]expect] intValue];
    [beController convertStringFieldToInt:inputField];
    STAssertEquals(3, [[beController userLimit] intValue], @"User field to Number conversion error");
}

And

-(void)testArrayPopulation {
    NSNumber* testNumber = [[NSNumber alloc]initWithInt:3];
    NSMutableArray* testArray = [beController populateArrayToLimit:testNumber];
    STAssertTrue(4 == [testArray count], @"Array Population error");
}

In the two tests above I used two testing libraries. The STAssertTrue in the testArrayPopulation method is a member of Apple’s built-in OCUnit testing library. Above it, in the testInputFieldToNumberConversion method, I have made use of mock objects and stubs provided by OCMock to simulate an input field object and its text method. I also used the expect method provided by OCMock. The expect method will fail if the specified function is not called on its target object. It is a good way to make sure that program control is moving in the direction you designed it to. I have included the tested Objective-C methods below:

//
//  BEViewController.m
//  BlogExample
//
//  Created by Fairway on 5/3/13.
//  Copyright (c) 2013 Fairway. All rights reserved.
//

#import "BEViewController.h"

@interface BEViewController ()

@end

@implementation BEViewController

@synthesize userRange;
@synthesize userLimit;
@synthesize inputField;
@synthesize displayLabel;
@synthesize calculateButton;

-(id)initWithNibName:(NSString *)nibNameOrNil bundle:(NSBundle *)nibBundleOrNil {
    self = [super initWithNibName:nibNameOrNil bundle:nibBundleOrNil];
    if(self) {
        userLimit = [[NSNumber alloc]init];
        userRange = [[NSMutableArray alloc]init];
    }
    return self;
}

This is the setup of the Object variables ^

-(NSNumber*)convertStringFieldToInt:(UITextField *)textField {
    NSNumberFormatter * f = [[NSNumberFormatter alloc] init];
    [f setNumberStyle:NSNumberFormatterDecimalStyle];
    userLimit = [f numberFromString: [textField text]];
    return userLimit;
}

Here is the conversion tested by testInputFieldToNumberConversion ^

-(NSMutableArray*)populateArrayToLimit:(NSNumber *)limit {
    int top = [limit intValue];
    for(int i = 0; i <= top; i++) {
        [userRange addObject:[NSNumber numberWithInt:i]];
    }
    return userRange;
}

And here is the population piece tested by testArrayPopulation ^

The next chunk is the meat of the algorithm and required a bit more detangling to make it testable.

 The Algorithm

for(int i = 2; i < numbers.length; i++) {
            if(i > 1) {
                result = result.multiply(new BigInteger(String.valueOf(numbers[i])));
                for(int j = i+1; j < numbers.length; j++) { 
                    if(numbers[j] > 1 && numbers[j] % numbers[i] == 0) { 
                        numbers[j] /= numbers[i];
                    }
                }
            }
        }
        return result.toString();

This algorithm executes by dividing all eligible higher factors by the current value of the array as referenced by the loop variable (by eligible I mean division produces a whole number). It takes the array produced by the assignment and population phase above it as input. Starting at index 2 (all indexes contain their corresponding integer 2 => 2 and so on), it will attempt to divide all subsequent items in the array by the current number. At each loop execution, the current number advances. If it’s (the new current number) greater than 1 (Meaning a new factor), the program will enter the loop, multiply the answer by the current number, and then attempt to divide the remaining array members by the current number once more. Here’s an example of what the array will look like over successive passes:

(Note that ‘1’ values are not shown in the result array, but they do exist. Every composite number that does not introduce a new prime reduces to a one and is skipped when the algorithm reaches it)

As you can see from the diagram above, the original array is transformed from its initial form (populated with all the numbers 1…limit) into a state where it only contains prime factors common amongst all numbers in the original array. By multiplying each member, the resulting prime factor array will solve the problem by producing the least common multiple. That separation of operations between the production and aggregation of the prime array is a perfect place to separate out functionality for testing.

 Separation of Concerns

The aggregation and production phases of the algorithm provide a convenient breaking point from which separation of the current function is possible. I did so when I wrote the Objective-C code for this algorithm:

-(void)testArrayAggregation {
    NSMutableArray* testArray = [[NSMutableArray alloc]init];
    for(int i = 0; i < 4; i++) {
        [testArray addObject:[[NSNumber alloc]initWithInt:i]];
    }
    NSNumber* testNumber = [beController aggregateArray:testArray];
    STAssertEquals(6, [testNumber intValue], @"Array Aggregation error");
}

The above testArrayAggregation function tests to make sure that the aggregateArray function in the BEViewController is working correctly.

-(NSNumber*)aggregateArray:(NSMutableArray *)array {
    int ans = 1;
    for (int i = 2; i < [array count]; i++) {
        ans *= [array[i] intValue];
    }
    return [[NSNumber alloc]initWithInt:ans];
}

With the aggregation and setup pieces tested, the only remaining major component is the reduction piece that produces the array containing the answers. This piece took a bit more hardcoding to get correct, but tests the most common case the function will encounter:

-(void)testPrimeFactorGeneration {
    NSMutableArray* testArray = [[NSMutableArray alloc]init];
    for(int i = 0; i <= 10; i++) {
        [testArray addObject:[[NSNumber alloc]initWithInt:i]];
    }
    testArray[4] = [[NSNumber alloc]initWithInt:2];
    testArray[6] = [[NSNumber alloc]initWithInt:1];
    testArray[8] = [[NSNumber alloc]initWithInt:2];
    testArray[9] = [[NSNumber alloc]initWithInt:3];
    testArray[10] = [[NSNumber alloc]initWithInt:1];
    NSMutableArray* temp = [beController determinePrimeFactors: [beController populateArrayToLimit:[[NSNumber alloc]initWithInt:10]]];
    STAssertTrue([temp isEqualToArray:testArray], @"Prime factor generation method not working");
}

And its corresponding function:

-(NSMutableArray*)determinePrimeFactors:(NSMutableArray *)list {
    for(int i = 2; i < [list count]; i++) {
        if(i > 1 ) {
            for(int j = i+1; j < [list count]; j++) {
                if([list[j] intValue] > 1 && [list[j] intValue] % [list[i] intValue] == 0) {
                    int x = [list[j] intValue] / [list[i] intValue];
                    NSNumber *n = [[NSNumber alloc]initWithInt:x];
                    list[j] = n;
                }
            }
        }
    }
    return list;
}

This leaves only two pieces; showAnser and restoreBeginningState. The showAnswer function’s only purpose is to execute the other class functions in the correct order to produce the answer. In essence, it’s a type of miniature integration test; with all of the pieces tested individually, showAnswer tests their cooperation as a unit:

-(void)showAnswer:(id)sender {
    userLimit = [self convertStringFieldToInt: inputField];
    userRange = [self populateArrayToLimit: userLimit];
    NSNumber* number = [self aggregateArray: [self determinePrimeFactors: userRange]];
    if([number intValue] == 1) {
        number = 0;
    }
    [displayLabel setText:[number stringValue]];
    [self restoreBeginningState];
}

Its tests run through all program logic (with the exception of restoreBeginningState):

-(void)testThatAnswerThreeIsSix {
    [[[inputField stub] andReturn: @"3"] text];
    [[[beController displayLabel] expect] setText: @"6"];
    [beController showAnswer: inputField];
    [displayLabel verify];
    [inputField verify];
}

-(void)testThatAnswerTenIs2520 {
    [[[inputField stub] andReturn: @"10"] text];
    [[[beController displayLabel] expect] setText: @"2520"];
    [beController showAnswer: inputField];
    [displayLabel verify];
    [inputField verify];
}

-(void)testThatAnswerTwentyIs232792560 {
    [[[inputField stub] andReturn: @"20"] text];
    [[[beController displayLabel] expect] setText: @"232792560"];
    [beController showAnswer: inputField];
    [displayLabel verify];
    [inputField verify];
}

Last (but not least), I wrote a function that restores the Object variables to their original states. This allows the user to enter a new value after a calculation is performed and receive a valid answer (otherwise old data would produce bad answers):

-(void)restoreBeginningState {
    userRange = [[NSMutableArray alloc]init];
    userLimit = [[NSNumber alloc]init];
}

And its test:

-(void)testRestorationToOriginalState {
    [[beController userRange] addObject:[[NSNumber alloc]initWithInt:3]];
    [beController setUserLimit:[[NSNumber alloc]initWithInt:3]];
    STAssertTrue([[beController userRange]count] == 1, @"restoreBeginningState test error");
    STAssertTrue([[beController userLimit] integerValue] == 3,  @"restoreBeginningState test error");
    [beController restoreBeginningState];
    STAssertTrue([[beController userRange]count] == 0, @"userRange has not been cleared in restoreToOriginalState");
    STAssertTrue([beController userLimit] == nil,  @"userLimit has not been cleared in restoreBeginningState");
}

Executing the program in the simulator yields a working app that correctly produces the LCM of the range defined by user input. That correctness was definitely helped along by TDD and OCMock. Objective-C is not a language that I know well. In unfamiliar domains (where you’re more likely to introduce bugs) TDD becomes even more crucial than normal. In addition to its utility in helping you work through the use cases, interfaces, and method signatures in advance, TDD can also help you figure out how language constructs and libraries work in a new language. If you think you’re producing a primitive int and your test case bombs out with a pointer, you know the class of issue you’re dealing with before you attempt to integrate your functionality into your application. TDD practices are great for isolating and anticipating problems before they happen and can make programming in any language much more productive.

 Resources

If you’re interested on learning more about this topic, here are some related resources:

http://ocmock.org/ – Location of OCMock. Tutorials, install info, api

http://alexvollmer.com/posts/2010/06/28/making-fun-of-things-with-ocmock/ – Insightful blog about using OCMock

http://alexvollmer.com/posts/2010/06/01/cocoas-broken-tests/ – More from Vollmer focusing on unit testing

http://www.amazon.com/Test-Driven-iOS-Development-Developers-Library/dp/0321774183/ref=sr_1_1?ie=UTF8&qid=1368203991&sr=8-1&keywords=tdd+objective+c – A book specifically about TDD in Objective-C (And it’s not bad!)

Companies who like the idea of being agile, but do not like the rigid process of Scrum, often cherry-pick their favorite parts out of the process and try to tack them on to whatever they’re already doing. When their projects grind to a halt and people point fingers, the process is often a convenient target. In that case it should be; writing good software is like baking. If you’re halfway through making lasagna and decide you’d like cake instead you don’t start tossing sugar on top of the cheese. The same is true in software development. It’s better to have good lasagna or good cake then a sticky inedible mess. If you’re going to follow a recipe for software development you have to fully commit to it, all of it, and support it as an organization to be successful.

One of the most common pitfalls for companies trying to implement an agile Scrum process is a lack of stakeholder participation. Having a customer advocate (or the customer themselves) in the room during the project is a critical driver at the heart of Scrum. When the stakeholders are too busy or disinterested to participate, the vision of what the customer wants and the actuality of what the programmers build begins to diverge.

The Scrum process is a collaborative one. It is built on the assumption that the stakeholders will be involved in the decisions driving the creative process. Requirements should not be thrown over the wall to the developers from the business side, or handled by the developers as needed.  Building a requirements backlog should be a process in which the business and technical tribes come together to develop a shared understanding of the needs of the client. If the business side is involved and invested in advancing and informing the process of writing good software, then everyone benefits from reduced churn and improved forecasting clarity.

To succeed in the modern business environment, software companies have to stay agile to respond to evolving customer requirements. The traditional business segmentation that works with blueprints and assembly lines will not work with software development. Organizations need to truly buy into the agile tenant, “customer collaboration over contract negotiation” [Agile Manifesto, http://agilemanifesto.org/], and start allowing their customers to control the work done on their behalf.

First off NuGet is great.  It has made life easier for me as a developer, and now, as an author for the open source generic repository SharpRepository.  It provides a great distribution channel, especially for providing updates.

The NuGet packages for SharpRepository add configuration elements to your Web.Config or App.config to make your life easier and allow for a configuration file way of setting up your repository.  NuGet provides a very simple configuration file transformation process when installing or updating a package. (For more information on it check here.) Basically it merges in your web.config.transform data into your web.config file adding the entries that don’t already exist.

Here is the issue I came across recently.  The SharpRepository.Ef5Repository NuGet package includes the following web.config.transform file:

<configuration>
	<sharpRepository>
	  <repositories>
		 <repository name="ef5Repository" connectionString="DefaultConnection" factory="SharpRepository.Ef5Repository.Ef5ConfigRepositoryFactory, SharpRepository.Ef5Repository" />
	  </repositories>
	</sharpRepository>
</configuration>

After doing the initial install of this package, NuGet will add the <sharpRepository> section close to the bottom of your Web.config file since it didn’t exist previously.  Then as you start your development, you realize that you are using a connection string named “MyConnectionString” (because you hate naming things apparently), so you do the logical thing and change the repository connectionString value in your Web.config file like so:

	<sharpRepository>
	  <repositories>
		 <repository name="ef5Repository" connectionString="MyConnectionString" factory="SharpRepository.Ef5Repository.Ef5ConfigRepositoryFactory, SharpRepository.Ef5Repository" />
	  </repositories>
	</sharpRepository>

Great, everything is working.  Then sometime down the road, you notice there is a brand new shiny version of SharpRepository.Ef5Repository available (due to new amazing features of course, no way there are any bugs to fix, not possible), so you update your package via NuGet and click run to start up your project, only to be shown an exception due to a duplicate key.  So what happened?

When NuGet runs the configuration file transformation it merges in the <repository> element again because the one from the package does not match the one that is in the Web.config file exactly due to the change of the connectionString value.  So the new file looks like this after the update:

	<sharpRepository>
	  <repositories>
		<repository name="ef5Repository" connectionString="MyConnectionString" factory="SharpRepository.Ef5Repository.Ef5ConfigRepositoryFactory, SharpRepository.Ef5Repository" />
		<repository name="ef5Repository" connectionString="DefaultConnection" factory="SharpRepository.Ef5Repository.Ef5ConfigRepositoryFactory, SharpRepository.Ef5Repository" />
	  </repositories>
	</sharpRepository>

So what can we do about it?

In order to get this fixed, I needed to hack together a workaround until NuGet does an upgrade to their XML transformations and maybe includes Visual Studio Web.config Transforms, which are more powerful.  I took advantage of the fact that during installation and upgrade of packages you can provide an Install.ps1 PowerShell script that will run after the files have been copied and the configuration file transformation is done.

Time to break out my non-existent PowerShell skills and put together a script to fix the problem.  When the script is run we may or may not have a duplicate element, but if we do, it will get added below the one that was edited and should be kept.  I also wanted to be able to have this work against both Web.config and App.config files since either one could have the problem depending on the type of project being used.

Each SharpRepository package that touches the configuration files has a version of this script, so my goal was to make it so that the majority of the code is the same from script to script and we just needed to setup which element to look for and clean up.  Here is what I came up with.

# Install.ps1
param($installPath, $toolsPath, $package, $project)

# Path Settings (since this script is used across multiple packages we only need to change these settings in each usually)
$parentPath = "configuration/sharpRepository/repositories"
$keyPath = "repository[@name='ef5Repository']"

Function Clean-Dups-In-Config-File ($localPath, $parentNodePath, $nodePath)
{
	$xml = New-Object xml

	# load config as XML
	$xml.Load($localPath)

	# select parent node to call the RemoveChild on later
	$parentNode = $xml.SelectSingleNode($parentNodePath)

	# select the nodes
	$nodes = $xml.SelectNodes($parentNodePath + "/" + $nodePath)

	if ($nodes.Count -gt 0) 
	{
		# if there are multiple repository names with the same key, then the NuGet update added the additional ones and they will be last
		#	so loop through those nodes, excluding the first one, and remove them
		$i = 1;
		while ($i -lt $nodes.Count) 
		{
			$parentNode.RemoveChild($nodes.Item($i))
			$i++
		}

		# save the config file
		$xml.Save($localPath)
	}
}

# find the Web.config/App.config file if there is one
$items = $project.ProjectItems | where {$_.Name -eq "Web.config" -or $_.Name -eq "App.config" }
Foreach ($item in $items)
{
	# find its path on the file system
	$localPath = $item.Properties | where {$_.Name -eq "LocalPath"}

	# clean duplicate entries
	Clean-Dups-In-Config-File $localPath.Value $parentPath $keyPath
}

This works great so far and cleans up the duplicates.

The Point

Locust is, if you believe the hype, the HOLY GRAIL of obscure Python-based distributed load testing tools with real-time web-based statistics:

I’ve tried a few different times to get Locust up and running on Windows, and every time something has gone wrong enough for me to be demotivated and quit.  ‘Cause, y’know, I’m a quitter.

Until now!

My goal is to help YOU get Locust setup on your Windows machine in the “recommended” way, so you can bring down your server by flooding it with thousands of requests too.  There is something awe-some about having the power to bring down a server remotely just by typing “100,000” in the “How many users?” input box…

Prerequisites

As is the case with most Python and Ruby stuff on Windows, there are a bunch of things you need installed and properly configured to successfully run Locust.  In this post, I document all of the things I needed to make it work.  This is after having tried a bunch of things that didn’t work, uninstalling everything, and starting from scratch.

Python 2.7

Well, hey!  Locust is just a big ol’ Python script, so you need Python.  Let’s just save you a bunch of frustrating hours right now, and tell you that everything we’ll be installing is 32-bit.  That’s because Locust doesn’t support 64-bit Python!  You wouldn’t know that by searching the Locust site, docs, or even searching for “locust python 64 bit” in Google.  But trust me.  32-bit is the way to go.

• Go to http://www.python.org/download
• Look for the latest Python 2.7.x Windows Installer link:
• 
• Download that and run the installer
  • You can keep all of the defaults, but take note of where it installs (probably C:\Python27)
• Once complete, make sure your PATH system environment variable is set correctly (something like this):
• 
• Open a command prompt and enter “python” and see what you see.  Hopefully this:
• 

curl

When you need to download stuff from the command line, you need curl.  You can just download the standalone .exe (32-bit!), or you can install the full cygwin suite, if you want.

I got it for free when I installed git.  You may already have it!  Just type “curl” at a command prompt, and you’ll know.

Python Tools

Next, you’ll need either setuptools or distribute.  For my money, distribute is WAY better.  Or wait, was it setuptools that was better?  Oh, right, it doesn’t matter.

Here is the fast and easy way to install distribute:

• In a command prompt, navigate to your Python install directory (C:\Python27)
• Type this to download and run (install) distribute:

> curl http://python-distribute.org/distribute_setup.py | python

easy_install

Many people like pip better than easy_install, either because of its adorable name, or because it actually displays useful error messages, but easy_install can run Windows executables, and pip can’t.  So we need it.  Even more hilarious is the fact that we will be installing pip in the next step!  BWAAAHAHAHAHAHAAAA!!!!

What’s really cool is that we already have easy_install, since we installed distribute in the last step!

virtualenv (and pip!)

Virtualenv lets you create isolated Python environments, so there’s less of a chance you’ll screw something up.  Don’t worry, you’ll probably screw something else up, because now all of your dependencies have to be available within the isolated environment, but some cool kids told me that virtualenv was the bomb, so I believed them.  Run these from the same command prompt location we were using before and simmer in the coolness:

> curl -O https://raw.github.com/pypa/virtualenv/master/virtualenv.py

> python virtualenv.py dev

> . dev/Scripts/activate

The first line grabs the Python script and drops it in the current directory.  The second line creates a new virtual Python environment called “dev” (YOU can call it whatevs you want!).  The last line “activates”, or switches you over to, the new virtual environment.

“Aw, look, it’s Pip!”

gevent

If you believe what their website says, gevent is a network library that provides a fast event loop.  This is why Locust can simulate eleventy billion users on a single machine.  Or twevinity quillion if you have two machines.

I say, get it!  Here’s how.  From the same command prompt, run:

> easy_install http://pypi.python.org/packages/2.7/g/gevent/gevent-0.13.8.win32-py2.7.exe

greenlets

greenlets are wee micro-threads, or coroutines, that do little cute stuff like “tasks”.  They are best friends with gevent.

Do this from Senor El Command Prompt if you want them, which you do, if you ever want locust to work:

> easy_install http://pypi.python.org/packages/2.7/g/greenlet/greenlet-0.4.0.win32-py2.7.exe

Locust Installation

Finally!  We can install locust, which is furiously simple now that everything else is in place.  We could do this with easy_install, but we installed pip, and haven’t used it, so let’s do that instead:

> pip install locustio

Distributed Test Army!

If you’ll be running this on more than one machine, you will need to install pyzmq and gevent-zeromq for insano-distributed magic-action.  It should be as easy as running pip install for those two, but since it’s Windows, it’s not!

pyzmq

For pyzmq, download the 32-bit version for Python 2.7 from here:  https://github.com/zeromq/pyzmq/downloads.

When you install it, be sure to select a different Python installation!  You need the one you created in virtualenv, so for me, that’s:

C:\Python27\dev

It only needs the root of the installation (there’s a python.exe under that dev directory, and that’s what gets run).

gevent-zeromq

We just need this guy so gevent can talk to pyzmq.  Luckily, you just need this:

> pip install gevent-zeromq

Locust Scripting

If I was 100% accurate in my instructions above, you should have a working install of Locust!  Applause!  Now it’s time to make it do stuff.

The one part of the Locust documentation that’s passable is the scripting stuff.  Although they only have a couple examples, they list all the stuff the API can do.  I’m afraid you’re in for some trial and error if you need to do some of the more advanced stuff, however.

Here’s a script I wrote, which I’ve commented up For Help’s Sake:

# magick.py

from locust import Locust, TaskSet, task

class WebsiteTasks(TaskSet):
    # Do this before tasks start
    def on_start(self):
        # Set any required HTTP Headers
        self.client.headers['Accept-Language'] = "en-US,en;q=0.8"

        # POST some form data
        self.client.post("/home/login", {
            "UserName": "nheldman",
            "Password": "password"
        })

    # Run this task with weighting 2 (twice as much as the one below)
    @task(2)
    def index(self):
        # GET the home page
        self.client.get("/")

    @task(1)
    def contact(self):
        # GET the Contact page
        self.client.get("/contact/")

class WebsiteUser(Locust):
    # What task class are we running?  (the one above!)
    task_set = WebsiteTasks

    # What's the minimum wait time between requests?
    min_wait = 1000

    # And the maximum?
    max_wait = 3000

    # What is our base host for testing (prepended to GETs/POSTs above)?
    host = "http://localhost:64175"

So, the scripting language is a world of its own, but it’s small, and elegant.

Now that I have a script, I can run it like so from Kommand Prompt:

> locust -f magick.py

If that works, the hard part is over.  It should show you now that it’s running:

Running Locust

Okay, fantastic!  Now we have a web monitor running!

Here’s the part where you’re going to think I’m really stupid.  I didn’t know what to do next.  Okay, I’ve done Rails development, node.js development, and worked with plenty of environments that ran a lightweight web server on some port.

So why didn’t I just open a browser and visit http://localhost:8089?

Because it didn’t say I needed to ANYWHERE IN THE LOCUST DOCUMENTATION!

Yes, it should have been obvious to me.  Really obvious.

And yet, because I was following other instructions on the Locust site, I guess I expected it to say “open a browser”.  It didn’t, so I didn’t.

But then I did.

Imagine my joy when I saw this screen.  It’s the first time I realized how I can tell Locust how many users to simulate, and how fast they should ramp up.

Why is it the first time?  Because it’s not ANYWHERE IN THE LOCUST DOCUMENTATION, NOR IS THERE A SCREENSHOT!

So, now it’s easy.  Just type in “100,000” in the first box (yes, ALWAYS start with 100,000 users), and something smaller in the second box, and click “Start Swarming”.

In reality, I started with 100 users, with a hatch rate of 2.

Behold!  You will see the magical-ness that is this:

Interpreting Results

In my example above, I have a comically high number of failures, and an even more comically low number of Requests per Second (RPS).

That’s because after all of this effort installing and configuring, I wanted a screenshot to represent my pain.  I promise it looks better when I write the script correctly.

The columns are mostly self-explanatory, but it’s worth noting that the Median, Average, Min, and Max represent the number of milliseconds it took for the page to load.

Yes, my page load times are abysmal.  Don’t forget to start your .NET site before running load tests against it, or page compiling will invalidate your results!

Conclusion:  Maybe Don't?

Before finding Locust, I used multi-mechanize.  Locust looked shinier and modern-er, and it seemed like it would be much easier to get up and running on Windows.

Although it was just as much of a pain to install and configure, it definitely looks nicer than multi-mechanize, and can probably handle higher simulated load on a single machine.

Multi-mechanize has more charts out of the box, though they can be a bit confusing.

Locust is worth a shot, if what you see above appeals to you.

However, if you have Visual Studio Ultimate, use that.  It’s just better.  It has tightly integrated load testing tools that are flexible and provide meaningful feedback:

Thank you for riding on the Windows Pain Wheel with me.  Here’s hoping Locust documentation gets better, and maybe even shows some swell charts!

When LINQ was first released in 2007, I remember thinking that I wouldn’t use it and I was very happy using SQL for querying the database.  Well, once I started using it I really liked the ability to query lists, XML and SQL Server or other databases all using the same query syntax (for the most part at least).  When starting the generic repository idea that became SharpRepository, it became a logical choice to use.  If a backend had a LINQ provider then it became pretty simple to add it to our list of supported systems:  Entity Framework, InMemory, Cache, RavenDB, MongoDB, and db4o all had LINQ providers that we could find, whether they were developed by the same group or a third party provider.

At some point I started thinking, “how can we integrate with a technology that doesn’t have a LINQ provider?”  And the answer that came to me was, “I’ll just build one, it can’t be that hard right.”  Well, turns out, it’s not the easiest thing to do.  After doing some research, I came across this great article by Ayende Rahien about creating the LINQ provider for RavenDB and, as you can tell by the title, the difficulties which he faced: The Pain of Implementing LINQ Providers.  In it, he refers to the re-linq framework which takes some of the pain out of the process.

What is re-linq?

Instead of dealing with the IQueryable expression tree (which is a really big pain), re-linq gives you an abstract syntax tree that is similar to the original LINQ query.  In implementing a LINQ provider, you will be coding against their QueryModel object, which is easier to consume than the LINQ Expression, and re-linq will evaluate any expressions within the query when it can.  re-linq implements the Visitor Pattern and provides a set of visitors for you to implement for your transformation.

One of the downsides of re-linq is that there isn’t much documentation available.  The most helpful information I found was a Codeproject article, which goes through the process and provides sample code, for creating a NHibernate LINQ provider, which translated LINE into Hibernate Query Language (HQL) that is titled re-linq|ishing the Pain: Using re-linq to Implement a Powerful LINQ Provider on the Example of NHibernate.

My attempt at writing a LINQ Provider

One day I got the strange idea to create an ODataRepository for the SharpRepository project.  Why?  Partly for fun, partly to see if I could, and partly because it could actually come in handy with WebAPI allowing you to easily provide for OData querying.  (It also didn’t hurt that the OData URI Coneventions are pretty simple and can only support a limited subset of LINQ syntax making it easier to implement.)  So while I could create an HttpClient object, query “http://somewebsite.net/Products?$filter=Category eq ‘Electronics’”, get the response and use JSON.NET to translate it to my object models, wouldn’t it be cool to be able to do this instead:

var repos = new ODataRepository<Product>("http://somewebsite.net/");
var products = repos.FindAll(x => x.Category == "Electronics");

My first attempt took me down the path of writing my own visitor class that accepts an Expression.  I got a very simple POC working but quickly realized that expanding it to handle more advanced situations was going to be very tough.  And that is when I ran across re-linq and decided to scrap my initial design and give re-linq a try.

While I am not done with creating this LINQ to OData provider yet, I have plugged away at it off and on for a little while and have made some good progress.  But mostly I have enjoyed the challenge of learning something new and giving it a shot. You can see the full code on the odata branch of SharpRepository on GitHub.  All of the LINQ related code is located here.

Some code

I won’t try to go through all the code in here but will point out a few things that will hopefully give a little overview of what it is like to write a LINQ provider using re-linq.  Please keep in mind that this code is in development and not a final product (in other words, be nice!).  I’ve based the basic structure of the code on the Codeproject article mentioned above and tweaked it for my needs, which really helped getting me going.

When parsing the syntax tree provided by re-linq, you will want to build up an object yourself that better represents the parts of your final query language.  After the tree parsing and visiting is all done, you will use this class to actually build the final query, in my case the OData querystring.  Here is the class I’m using for this purpose:

    public class QueryPartsAggregator
    {
        public QueryPartsAggregator()
        {
            FromParts = new List<string>();
            WhereParts = new List<string>();
        }

        public string SelectPart { get; set; }
        public List<string> FromParts { get; set; }
        public List<string> WhereParts { get; set; }
        public string OrderBy { get; set; }
        public int? Take { get; set; }
        public int? Skip { get; set; }
        public bool OrderByIsDescending { get; set; }
        public bool ReturnCount = false;

        public void AddFromPart(IQuerySource querySource)
        {
            FromParts.Add(querySource.ItemName);
        }

        public void AddWherePart(string formatString, params object[] args)
        {
            WhereParts.Add(string.Format(formatString, args));
        }

        public void AddOrderByPart(string orderBy, bool isDescending)
        {
            OrderBy = orderBy;
            OrderByIsDescending = isDescending;
        }
    }

When I need to build the actual OData querystring to perform the query this object maps nicely as you can see in the code below that handles this part:

            if (_queryParts.ReturnCount)
            {
                querystring += "/$count";
            }

            querystring += "?$format=json&";

            if (_queryParts.Take.HasValue)
                querystring += "$top=" + _queryParts.Take.Value + "&";

            if (_queryParts.Skip.HasValue)
                querystring += "$skip=" + _queryParts.Skip.Value + "&";

            if (!String.IsNullOrEmpty(_queryParts.OrderBy))
                querystring += "$orderby=" + _queryParts.OrderBy + "&";

            var filter = SeparatedStringBuilder.Build(" and ", _queryParts.WhereParts);
            if (!String.IsNullOrEmpty(filter))
                querystring += "$filter=" + filter + "&";

            if (!String.IsNullOrEmpty(_queryParts.SelectPart))
                querystring += "$select=" + _queryParts.SelectPart + "&";

In re-linq, you define an IQueryExecutor that is in charge of running the query based on the QueryModel that re-linq gives it.  Basically this class takes the QueryModel and kicks off the Visitor that goes through it all and builds the QueryPartsAggregator.  For the OData implementation we need to give it the base URL and the name of the collection we are querying.

    // Called by re-linq when a query is to be executed.
    public class ODataQueryExecutor : IQueryExecutor
    {
        private readonly string _url;
        private readonly string _databaseName;

        public ODataQueryExecutor(string url, string databaseName)
        {
            _url = url;
            _databaseName = databaseName;
        }

        // Executes a query with a scalar result, i.e. a query that ends with a result operator such as Count, Sum, or Average.
        public T ExecuteScalar<T> (QueryModel queryModel)
        {
          return ExecuteCollection<T> (queryModel).Single();
        }

        // Executes a query with a single result object, i.e. a query that ends with a result operator such as First, Last, Single, Min, or Max.
        public T ExecuteSingle<T> (QueryModel queryModel, bool returnDefaultWhenEmpty)
        {
          return returnDefaultWhenEmpty ? ExecuteCollection<T> (queryModel).SingleOrDefault () : ExecuteCollection<T> (queryModel).Single ();
        }

        // Executes a query with a collection result.
        public IEnumerable<T> ExecuteCollection<T> (QueryModel queryModel)
        {
          var commandData = ODataApiGeneratorQueryModelVisitor.GenerateODataApiQuery(queryModel);
          var query = commandData.CreateQuery(_url, _databaseName);
          return query.Enumerable<T> ();
        }
    }

At this point we have defined a class structure to represent our OData query, written the logic to take that structure and translate it into the OData querystring to use when making the HTTP request, and we’ve wired up what re-linq needs to kick off the process.  So the only thing left is to write the actual Visitor that parses the QueryModel.  As you can see from the code above, I’ve called this ODataApiGeneratorQueryModelVisitor (I like to keep my class names really short as you can see).  This class inherits from re-linq’s QueryModelVisitorBase and we override the methods as needed.  I won’t show the whole class but this is where we begin to populate the QueryPartsAggregator.

For example, there is a VisitResultOperator method which gets passed a ResultsOperatorBase class.  There are implementations of this base class for when the First() method is called, FirstResultOperator, or when Take() is called, TakeResultOperator, etc.  So when we override this method, for my OData needs it looks like this:

        public override void VisitResultOperator(ResultOperatorBase resultOperator, QueryModel queryModel, int index)
        {
            if (resultOperator is FirstResultOperator)
            {
                _queryParts.Take = 1;
                return;
            }

            if (resultOperator is CountResultOperator || resultOperator is LongCountResultOperator)
            {
                _queryParts.ReturnCount = true;
                return;
            }

            if (resultOperator is TakeResultOperator)
            {
                var exp = ((TakeResultOperator)resultOperator).Count;

                if (exp.NodeType == ExpressionType.Constant)
                {
                    _queryParts.Take = (int)((ConstantExpression)exp).Value;
                }
                else
                {
                    throw new NotSupportedException("Currently not supporting methods or variables in the Skip or Take clause.");
                }

                return;
            }

            if (resultOperator is SkipResultOperator)
            {
                var exp = ((SkipResultOperator) resultOperator).Count;

                if (exp.NodeType == ExpressionType.Constant)
                {
                    _queryParts.Skip = (int)((ConstantExpression)exp).Value;
                }
                else
                {
                    throw new NotSupportedException("Currently not supporting methods or variables in the Skip or Take clause.");
                }

                return;
            }

            base.VisitResultOperator(resultOperator, queryModel, index);
        }

The more complex parts are when Expressions need to be parsed, like in the case of the WhereClause, SelectClause or OrderByClause.  Re-linq provides a base visitor class for handling the expression parsing called ThrowingExpressionTreeVisitor.  As it’s name suggests, it throws an exception if some part of the LINQ syntax is not implemented in your visitor.  That way if you don’t implement the Contains() method, it will notify the user that it’s not implemented instead of just ignoring it and moving along as if it was being used.

The most straight-forward example of this is in parsing a BinaryExpression.  A BinaryExpression is made up of a Left and Right side and a NodeType.  This could be something like (x.Category == “Electronics”) where the Left side is the property x.Category, the Right side is the constant “Electronics” and the NodeType is Equal  It could also be something more complex like (x.Category == “Electronics” && x.Status == true) where the Left side is the BinaryExpression (x.Category == “Electronics”), the Right side is the BinaryExpression (x.Status == true), and the NodeType is AndAlso.

Here is the override of the VisitBinaryExpression method that I’ve made for my OData implemenation:

        protected override Expression VisitBinaryExpression (BinaryExpression expression)
        {
            _expression.Append("(");

            VisitExpression (expression.Left);

            // In production code, handle this via lookup tables.
            switch (expression.NodeType)
            {
                case ExpressionType.Equal:
                    _expression.Append (" eq ");
                    break;

                case ExpressionType.NotEqual:
                    _expression.Append (" ne ");
                    break;

                case ExpressionType.GreaterThan:
                    _expression.Append (" gt ");
                    break;

                case ExpressionType.GreaterThanOrEqual:
                    _expression.Append (" ge ");
                    break;

                case ExpressionType.LessThan:
                    _expression.Append (" lt ");
                    break;

                case ExpressionType.LessThanOrEqual:
                    _expression.Append (" le ");
                    break;

                case ExpressionType.AndAlso:
                case ExpressionType.And:
                    _expression.Append (" and ");
                    break;

                case ExpressionType.OrElse:
                case ExpressionType.Or:
                    _expression.Append (" or ");
                    break;

                case ExpressionType.Not:
                    _expression.Append(" not ");
                    break;

                case ExpressionType.Add:
                    _expression.Append (" add ");
                    break;

                case ExpressionType.Subtract:
                    _expression.Append (" sub ");
                    break;

                case ExpressionType.Multiply:
                    _expression.Append (" mul ");
                    break;

                case ExpressionType.Divide:
                    _expression.Append (" div ");
                    break;

                case ExpressionType.Modulo:
                    _expression.Append(" mod ");
                    break;

                default:
                    base.VisitBinaryExpression (expression);
                    break;
            }

            VisitExpression (expression.Right);

            _expression.Append(")");

            return expression;
        }

As you can see, I am translating the ExpressionType into the proper OData syntax, == becomes “eq”, >= becomes “ge”, etc.  The call to VisitExpression(expression.Left) and VisitExpression(expression.Right) are both very important.  They allow you to further parse the left side of the expression if it is a complex expression itself.  So in my example above where the Left side is (x.Category == “Electronics”), this call to VisitExpression then visits that left side and again has VisitBinaryExpression called allowing that original complex expression to be turned into the following OData query: “((Category eq ‘Electronics’) and (Status eq true))”.

Another example is being able to handle method calls like Contains(“text”),  StartsWith(“text”) or ToLower() and ToUpper().  To handle these we need to override the cleverly named VisitMethodCallExpression().  Here is the code that I wrote to handle those calls:

        protected override Expression VisitMethodCallExpression (MethodCallExpression expression)
        {
            // In production code, handle this via method lookup tables.
            if (expression.Method.Name == "Contains")
            {
                _expression.Append("substringof(");
                VisitExpression(expression.Arguments[0]);
                _expression.Append(",");
                VisitExpression(expression.Object);
                _expression.Append(") eq true");
                return expression;
            }

            if (expression.Method.Name == "StartsWith")
            {
                _expression.Append("startswith(");
                VisitExpression(expression.Object);
                _expression.Append(",");
                VisitExpression(expression.Arguments[0]);
                _expression.Append(") eq true");
                return expression;
            }

            if (expression.Method.Name == "EndsWith")
            {
                _expression.Append("endswith(");
                VisitExpression(expression.Object);
                _expression.Append(",");
                VisitExpression(expression.Arguments[0]);
                _expression.Append(") eq true");
                return expression;
            }

            if (expression.Method.Name == "ToLower")
            {
                _expression.Append("tolower(");
                VisitExpression(expression.Object);
                _expression.Append(")");
                return expression;
            }
            if (expression.Method.Name == "ToUpper")
            {
                _expression.Append("toupper(");
                VisitExpression(expression.Object);
                _expression.Append(")");
                return expression;
            }

            return base.VisitMethodCallExpression (expression); // throws
        }

Conclusion

Hopefully this has given you a glimpse into the crazy world of writing a LINQ provider.  As Ayende Rahien writes, “As a consumer of LINQ, I absolutely adore it, despite some of the issues just discussed. But consuming LINQ is the part that is all sunshine and roses. The task of implementing a LINQ provider is one of Herculean proportion and involves much use of fertilizer, sweat, and hard work.”  I think that does a great job of summing it up actually.

If you’ve used AutoMapper before on a larger sized project, then you’ve probably seen how long and unruly your mapping definitions can become.  This file can grow and grow and just be a pain to deal with.  Luckily, AutoMapper provides a way to separate the definitions up into more logical units.  When doing MVC development, it might be natural to group all the Model/ViewModel mappings for a single controller, but you can break it up however makes logical sense to you.  You would do this by creating a custom Profile for each where you define your mappings for those entities.

To make this a little easier, let’s define a base class for all of our custom Profiles to inherit from.  This also allows us to define any formatters that we want to use across all of our mappings. In this example, we have a date formatter that will take a DateTime or DateTime? and convert it to the standard string display we want for this site.

    public abstract class BaseProfile : Profile
    {
        private readonly string _profileName;
        protected BaseProfile(string profileName)
        {
            _profileName = profileName;
        }

        public override string ProfileName
        {
            get { return _profileName; }
        }

        protected override void Configure()
        {
            ForSourceType<DateTime>().AddFormatter<StandardDateTimeFormatter>();
            ForSourceType<DateTime?>().AddFormatter<StandardDateTimeFormatter>();

            CreateMaps();
        }

        protected abstract void CreateMaps();
    }

Now when we want to create a new profile for AutoMapper we can create it like so:

    public class EventProfile : BaseProfile
    {
        public EventProfile() : base("EventProfile")
        {
        }

        protected override void CreateMaps()
        {
            CreateMap<Event, IndexViewModel.Event>();
            CreateMap<Event, CreateViewModel>();
            CreateMap<Event, DetailsViewModel>();
            CreateMap<Event, EditViewModel>();
            CreateMap<Event, DeleteViewModel>();
        }
    }

This is a trivial example where the properties match perfectly from our Event Model to our ViewModels, but since that isn’t the point of this article I’m not going to worry about it.

Now you just have to tell AutoMapper to load these profiles.  If you have some bootstrapper code you would add it there, if not then Global.asax is a common place (I didn’t say the best place, but it is common and it works).  Here is how you would do that.  You need to call AddProfile<>() for each custom profile we create in order to register it.

            Mapper.Initialize(x =>
                {
                    x.ConstructServicesUsing(ObjectFactory.GetInstance);

                    x.AddProfile<EventProfile>();
                    x.AddProfile<NewsProfile>();
                    x.AddProfile<UserProfile>();
                    x.AddProfile<OrderProfile>();

                    // etc., etc.
                });

            Mapper.AssertConfigurationIsValid();

This definitely helped break up a very large AutoMapper mappings file into smaller more easily managed pieces so I like where it is going.   But after using it for a bit I noticed that I kept forgetting to add my new Profile into this initialization part and that wasted time and was just kind of annoying.  So I decided to change it so I could be lazy and not have to worry about it.

Using reflection we can grab all of the classes that inherit from BaseProfile and then call AddProfile with each of them.  There may or may not be a way to grab all the types and call AddProfile<T>() with it like is done in the code above but I couldn’t figure out how to and quickly found another way so stopped trying.  There is also an AddProflile(Profile profile) method that accepts an instantiated class of type Profile (which BaseProfile inherits from).  So the only thing left to do is code it up:

            Mapper.Initialize(x =>
                {
                    x.ConstructServicesUsing(ObjectFactory.GetInstance);

                    // get all the AutoMapper Profile classes using reflection
                    var profileTypes = typeof(BaseProfile).Assembly.GetTypes().Where(type => type.IsSubclassOf(typeof(BaseProfile)));

                    foreach (var type in profileTypes)
                    {
                        x.AddProfile((BaseProfile)Activator.CreateInstance(type));
                    }
                });

            Mapper.AssertConfigurationIsValid();

If you haven’t seen the Activator.CreateInstance() call before, it creates a new instance of that object type using the default constructor, and that works perfectly for you custom profiles since they don’t need any parameters.  There are also versions of Activator.CreateInstance where you can pass in your parameters in case you run into that scenario.

The result of this is a better organized structure for AutoMapper, especially on larger projects, while making as little work for us each time we need to add a new Profile.

Our heroes have fought their way through the Death Star’s fighter screen and can see the trench. As they enter the trench our pilots stabilize their deflector shields, preparing for the torrent of incoming turbolaser fire that will no doubt be coming their way.

In this post, we’ll take a look at adding some validation rules to our Ship and Pilot models. Hopefully, this effort will prevent our users from… err… having their way with our meek and rather naive Starfighter Recognition Guide. Our exhaust port is small, it’d be a shame to see it damaged by some ham-fisted users.

Validation

In our last post we walked away with a fully-functioning Starfighter Recognition Guide that could save a Ship and any changes (create/update/delete) to its associated Pilots. Neat, right?

Before we run off and save everything willy-nilly, we should probably go about checking to make sure our users provided the data we need. Let’s add some data entry requirements to our application, shall we? Here’s what we need to do:

Ship Requirements

• A Ship must have a name.
• A Ship‘s name must be between 3 and 50 characters.
• A Ship must have a crew.
• A Shipmust have between 1 and 5 crew members.
  • Arbitrary? Sure. But I figure if a Ship has more than 5 crew members, it’s probably a capital ship or on a scale that isn’t appropriate for a Starfighter Recognition Guide.
• A Ship must have a speed.
• A Ship‘s speed must be between 50 and 200… err… thingies per… umm… unit of time.
  • At the risk of having my Star Wars nerd card revoked, I’m not sure how the speed of a starfighter is measured. Yes, I looked it up. Nope, I couldn’t find anything conclusive.

Shown below is the complete Ship model:
app/models/ship.rb

class Ship < ActiveRecord::Base   attr_accessible :armament, :crew, :has_astromech, :name, :speed   attr_accessible :pilots_attributes   has_many :pilots   accepts_nested_attributes_for :pilots,                                 :reject_if => :all_blank,
                                :allow_destroy => true

  validates :name,
            :presence => true,
            :uniqueness => { :case_sensitive => false },
            :length => { :maximum => 50, :minimum => 3 }

  validates :crew,
            :presence => true,
            :inclusion => { :in => 1..5, :message => "must be between 1 and 5" }

  validates :speed,
            :presence => true,
            :inclusion => { :in => 50..200, :message => "must be between 50 and 200" }
end

REFACTOR: The code above has changed a bit from the first post. Specifically, I had to change the :reject_if from lambda { |attrs| attrs.all? { |key, value| value.blank? } to :all_blank. After reading up on the documentation for accepts_nested_attributes_for, the Proc I was using wasn’t good enough. Why, you ask? Well, our Pilot objects have their special _destroy field attached to them. The _destroy attribute can only be true or false, so it won’t ever be blank. The Proc above would allow us to save “empty” Pilot records (i.e. Pilots that have null first_name, last_name and call_sign values). The :all_blank symbol points to an ActiveRecord Proc that deals with this specific issue. Using :reject_if => :all_blank means that any Pilot record with no data will be ignored during the save, which is what we want. So… yay.

Pilot Requirements

• A Pilot must have a first name.
• A Pilot‘s first name cannot be longer than 50 characters.
• A Pilot must have a last name.
• A Pilot‘s last name cannot be longer than 50 characters.
• A Pilot must have a call sign.
• A Pilot‘s call sign must be unique. Case-sensitivity doesn’t matter here – “red 5″ is the same as “Red 5″, which is the same as “RED 5″, etc.
  • To make sure this requirement is enforced, a unique index has been added to the call_sign column of the pilots table. You can see it on line 13 of the database migration script here.

Here’s what the Pilot model looks like with the validation in place:

app/models/pilot.rb

class Pilot < ActiveRecord::Base   belongs_to :ship   attr_accessible :call_sign, :first_name, :last_name, :ship_id   validates :first_name,             :presence => true,
            :length => { :maximum => 50 }

  validates :last_name,
            :presence => true,
            :length => { :maximum => 50 }

  validates :call_sign,
            :presence => true,
            :uniqueness => { :case_sensitive => false },
            :length => { :maximum => 50, :minimum => 5 }
end

Okey doke – now that we have our validation in place, let’s see what happens when we click the “Add Ship” button and then click “Save” without entering anything:

Not too shabby. Coincidentally, we’ll get the same error message if we:

1. Click the “Add Ship” button on the home page to create a new Ship.
2. Click the “Add Pilot” button on the “New Ship” page to… y’know… Add a new Pilot. And stuff.
3. Click the “Add” button on the “Add a Pilot” modal form.
4. We’ll see a new row added to the “Pilots” section of the “Add Ship” form, and all the fields will be empty.

How come we don’t get any errors about the Pilot with empty fields? That’s our Ship‘s :reject_if in action. ActiveRecord saw that the Pilot was “empty”, so it discarded the record.

Allowing a user to click the “Add” button on our “Add a Pilot” modal form with willful and blatant disregard for our carefully-laid requirements is an affront to our humble application. It will not stand, I tell you! ‘Kay – maybe that was a little harsh, but you know what I mean. If we don’t stand up for our app, who will? If we need the user to give us data for a Pilot, we should do what we can to make sure they give it to us. Let’s add some client-side validation to our “Add a Pilot” modal form, so we can tell the user what’s missing when they click the “Add” button.

I poked around on Google for a bit to find a good solution for client-side validation utilities, and there’s no shortage of them. I landed on this article, which uses the jQuery-Form-Validator. The implementation looks pretty straightforward, and +1 for the article because he’s using Twitter Bootstrap too.

The jQuery-Form-Validator

Adding the jQuery-Form-Validator is pretty straightforward. Just get the jquery-form-validator.min.js file to your project. There aren’t any dependencies (outside of jQuery, of course).

Using the jQuery-Form-Validator is also pretty simple. All you have to do is add a data-validation attribute to the element you want to validate. You can visit the GitHub page to see all the validation options that are available (there are quite a few).

You can also customize the error message, by adding a data-validation-error-msg attribute with your customized error message. There are a host of other configuration options available, such as: the position of the error messages, the name of the data-* attribute, the CSS classes for your error messages, etc. You can see them on the GitHub page or on the jQuery-Form-Validator demo page.

Shown below is the code for our Pilot modal form that implements the jQuery-Form-Validator:

app/views/ships/_pilot_fields.html.erb:

<div id="new-pilot-fields" class="modal fade" data-backdrop="static">
  <div class="modal-header">
    <button type="button" class="close" data-dismiss="modal" aria-hidden="true">×</button>
    <h3>Add a Pilot<%= " to the #{ @ship.name } Pilot Roster" unless @ship.name.nil? %></h3>
  </div>
  <div class="modal-body">
    <fieldset>
      <div class="control-group">
        <%= f.label(:first_name, :class => "control-label") %>
        <div class="controls">
          <%= f.text_field(:first_name, :class => "input-xlarge field", :data => { :validation => "required validate_max_length length50", "validation-error-msg" => "First Name is required and cannot be longer than 50 characters." }) %>
        </div>
      </div>

      <div class="control-group">
        <%= f.label(:last_name, :class => "control-label") %>
        <div class="controls">
          <%= f.text_field(:last_name, :class => "input-xlarge field", :data => { :validation => "required validate_max_length length50", "validation-error-msg" => "Last Name is required and cannot be longer than 50 characters." }) %>
        </div>
      </div>

      <div class="control-group">
        <%= f.label(:call_sign, :class => "control-label") %>
        <div class="controls">
          <%= f.text_field(:call_sign, :class => "input-xlarge field", :data => { :validation => "required validate_length length5-50", "validation-error-msg" => "Call Sign is required and cannot be must be between 5 and 50 characters." }) %>
        </div>
      </div>
      <%= f.hidden_field(:_destroy, :class => "field") %>
    </fieldset>
  </div>
  <div class="modal-footer">
    <button id="addButton" type="button" class="btn btn-primary" data-dismiss="modal" aria-hidden="true" title="Add this Pilot to the list of Pilots that are assigned to this Ship.">Add</button>
    <button id="cancelButton" type="button" class="btn btn-inverse" data-dismiss="modal" aria-hidden="true" title="Close this screen without adding the Pilot to the list.">Cancel</button>
  </div>
</div>

<script type="text/javascript">
  pilotFieldsUI.init();
</script>

Just like this fine fellow did, we’ll add some CSS to our application.css file to make sure our error messages appear below the offending element:

app/assets/stylesheets/application.css.scss:

.jquery_form_error_message{
  display: block;
  margin-top: 3px;
  color: #f00;
}

Now all we have to do is wire up the jQuery-Form-Validator to our “Add a Pilot” modal form. Here’s how we do that:

app/assets/javascripts/ships.js:

// Set up the UI/UX for the ships screens.  This object sets up all the functionality we need to:
//  1.  Bind to the "click" event of the "#addButton" on the modal form.
//  2.  Append data from the modal form to the Pilots table.
//  3.  Hide the modal form when the user is done entering data.
//
// If any other events need to be wired up, the init function would be the place to put them.
var pilotFieldsUI = {
    init: function() {
        // Configuration for the jQuery validator plugin:
        // Set the error messages to appear under the element that has the error.  By default, the
        // errors appear in the all-too-familiar bulleted-list.
        // Other configuration options can be seen here:  https://github.com/victorjonsson/jQuery-Form-Validator
        var validationSettings = {
            errorMessagePosition : 'element'
        };

        // Run validation on an input element when it loses focus.
        $('#new-pilot-fields').validateOnBlur();

        $('#addButton').on('click', function(e) {
            // If the form validation on our Pilots modal "form" fails, stop everything and prompt the user
            // to fix the issues.
            var isValid = $('#new-pilot-fields').validate(false, validationSettings);
            if(!isValid) {
                e.stopPropagation();

                return false;
            }

            // This is the code from previous posts...
            formHandler.appendFields();
            formHandler.hideForm();
        });
    }
};

On line 13, we’re building a configuration object that contains our setting for the jQuery-Form-Validator. All we want to do is set the error messages to appear next to the input element, so that’s all we’re setting for now. On line 18, we’re telling the jQuery-Form-Validator to fire whenever one of our elements loses focus. Am I over-explaining? Probably. Almost certainly. But it’s too late now!

On line 23, things get slightly more interesting. Since the “Add a Pilot” modal form isn’t a proper form (remember, it’s a <div> on our Ship form), our “Add” button isn’t a submit. However, we’re going to call .validate on our #new-pilot-fields anyway. If our validation fails, then stop everything and let the user fix their issues.

Now that we’ve wired everything up, here’s what it looks like after a user click’s the “Add” button:

As an added bonus, the validation functionality is carried forward when we add the new Pilot to our “Pilots” section of the Ship form. Here’s what it looks like when a user adds a Pilot successfully, but then removes the Call Sign before clicking save:

Caveat

The trick shown above isn’t 100% bullet-proof – remember we aren’t calling jQuery-Form-Validator’s validate() method when we submit Ship form. It’d be pretty easy to implement, so I’ll leave that as an exercise for you, dear reader. However, we are covered by our server-side validation that we implemented in our models. See?

It’s not perfect, but it’s better than nothing. We’ll try to clean this up in a later post.

Conclusion

We’re definitely closing in on the exhaust port now, ladies and gentelmen! Our Starfighter Recognition Guide’s shields have been hardened with some client-side validation. These shield upgrades will come in handy to deflect the incoming fire our users will no doubt throw at us. Our intrepid heroes aren’t quite out of the woods yet – there’s some additional validation we could add (isn’t there always?), but we’ll handle that as our pilots approach their target.

Reference

Here are some articles/tools that helped me out immensely with this post:

• Easy Client-Side Form Validation for Rails 3.1
• jQuery-Form-Validator
• jQuery-Form-Validator Demo Page

var orderRepository = new InMemoryRepository<Order>();

While this definitely works, it isn’t the best way.  Why?  Well, if you want to switch to an Ef5Repository or want to add caching, you will need to change the code and recompile.  Plus, you are using dependency injection and inversion of control right?  Well this doesn’t work with those patterns of course.   In this post I will cover some of the various ways to create your repository.

Configuration Overview

Before getting into the code for loading up a repository via configuration settings it will be helpful to understand the SharpRepository hierarchy.  Each repository has a specific type of backend that it queries (e.g. InMemory, Entity Framework, RavenDb, MongoDb, Db4o,  Xml, etc.), a caching strategy (e.g. None, Standard, Timeout), and a caching provider (e.g. Memory, memcached, Azure, etc.).

The caching strategy tells the repository the rules for caching.  The Timeout Strategy uses a simple time based rule, for example, cache the query results for 30 seconds, while the Standard Strategy uses Generational and Write-Through caching techniques to provide a more sophisticated caching logic.  And the No Caching Strategy does not do any caching at all (it’s not just a clever name).

The caching provider on the other hand is the specific cache technology that is used.  For simple websites the InMemory caching provider works great and uses the ASP.NET built-in System.Runtime.Caching.MemoryCache. For more advanced needs like distributed caching you would use the memcached provider or the Windows Azure provider and store the cache across multiple servers.

The beauty of this is that both of these can be extended by inheriting from ICachingStrategy or ICachingProvider if the need arises.

Create from Configuration Object

You can create a SharpRepositoryConfiguration object and use that to create your repository.  The SharpRepositoryConfiguration object allows you to build a “profile” and then when you create a specific repository you can choose which “profile” to use.  I think that the code below will help show what I mean.

            var config = new SharpRepositoryConfiguration();
            config.AddRepository(new Ef5RepositoryConfiguration("ef5", "DefaultConnection")); // EF repository named ef5 using the DefaultConnection connection string
            config.AddRepository(new InMemoryRepositoryConfiguration("inmemory", "standard", "memcached")); // InMemoryRepository named default using the none CachingStrategy

            config.AddCachingStrategy(new TimeoutCachingStrategyConfiguration("timeout", 30)); // Timeout strategy named timeout with 30 second cache time
            config.AddCachingStrategy(new StandardCachingStrategyConfiguration("standard")); // Standar d strategy named standard
            config.AddCachingStrategy(new NoCachingStrategyConfiguration("none")); // No caching named none

            config.AddCachingProvider(new InMemoryCachingProviderConfiguration("inmemory")); // InMemory provider name inmemory
            config.AddCachingProvider(new MemCachedCachingProviderConfiguration("memcached", "memcached"));  // memcached provider named memcached and using the memcached section in config file

            config.DefaultRepository = "ef5";
            config.DefaultCachingStrategy = "timeout";
            config.DefaultCachingProvider = "inmemory";

            var userRepos = RepositoryFactory.GetInstance<User, int>(config); // uses the Ef5Repository
            var orderRepos = RepositoryFactory.GetInstance<Order, int>(config, "inmemory"); // uses InMemoryRepository with Standard caching strategy and memcached

As you can see above, the SharpRepositoryConfiguration gets loaded with multiple repositories that can use the various caching strategies and caching providers.  Note that everything is referred to by name.  The specific repository configuration (e.g. Ef5RepositoryConfiguration and InMemoryRepositoryConfiguration) always takes a name first, then anything specific to that type (like the connection string name for EF5), and optionally a caching strategy and provider can be provided last.  If no caching strategy or provider is used, the DefaultCachingStrategy and DefaultCachingProvider are used, and if those aren’t set then no caching is used by default.

This does provide the benefit of being able to setup your configuration in a single location and then pass that configuration in when loading up your repository.  You can then make changes in a single location and it will effect everywhere that you create repositories.  That being said, there may be some cases where you would need programmatic access to the configuration, but most likely this is not what you should be doing.  Well, then why did you show me this?  Good question.  It leads me into the next way of doing things … Web.config (or App.config).

Configuration File

The same basic structure as the configuration object can be used in your Web.config (or App.config).  Note: if you install the NuGet packages it will stub out these sections for you.  For example, if you install SharpRepository.Ef5Repository it will include the proper configSection at the top of the file and create the specific repository using the DefaultConnection connectionstring name.  You can then go in and edit this, but it allows you to not have to code out the assembly type paths, which are kind of a pain.

Here is an example of what the configuration used above would look like in your configuration file:

  <sharpRepository>
    <repositories default="ef5">
      <repository name="ef5" connectionString="DefaultConnection" factory="SharpRepository.Ef5Repository.Ef5ConfigRepositoryFactory, SharpRepository.Ef5Repository"  />
      <repository name="inmemory" factory="SharpRepository.Repository.InMemoryRepositoryFactory, SharpRepository.Repository" cachingStrategy="standard" cachingProvider="memcached" />
    </repositories>
    <cachingProviders default="inmemory">
      <cachingProvider name="inmemory" factory="SharpRepository.Repository.Caching.InMemoryConfigCachingProviderFactory, SharpRepository.Repository" />
      <cachingProvider name="memcached" factory="SharpRepository.Caching.Memcached.MemCachedConfigCachingProviderFactory, SharpRepository.Caching.Memcached" />
    </cachingProviders>
    <cachingStrategies default="timeout">
      <cachingStrategy name="standard" generational="true" writeThrough="true" factory="SharpRepository.Repository.Caching.StandardConfigCachingStrategyFactory, SharpRepository.Repository" />
      <cachingStrategy name="timeout" timeout="30" factory="SharpRepository.Repository.Caching.TimeoutConfigCachingStrategyFactory, SharpRepository.Repository" />
      <cachingStrategy name="none" factory="SharpRepository.Repository.Caching.NoCachingConfigCachingStrategyFactory, SharpRepository.Repository" />
    </cachingStrategies>
  </sharpRepository>

Then in your C# code, you would load them up with the similar calls to RepositoryFactory.GetInstance like so:

var userRepos = RepositoryFactory.GetInstance<User, int>(); // uses the Ef5Repository since it's the default
var orderRepos = RepositoryFactory.GetInstance<Order, int>("inmemory"); // uses InMemoryRepository with Standard caching strategy and memcached

This is a much better approach than using the configuration objects because if you need to make a change, like changing your caching or changing from an InMemoryRepository during your prototyping phase to an Ef5Repository, you can just edit your Web.config file and there is no need for a recompile.

But what if I want to add custom methods to my repository or use constructor injection, how would I do that?  Wow, you are great at helping me move to my next section, thanks.

Custom repositories

There are situations where you will want to create a custom repository so you can add your own methods to it, or just because you like programming against an IUserRepository instead of IRepository<User, int>.  So how would you do that?

    public interface IUserRepository : IRepository<User, int>
    {
        User GetAdminUser();
    }

    public class UserRepository : InMemoryRepository<User, int>, IUserRepository
    {
        public User GetAdminUser()
        {
            return Find(x => x.Email == "admin@admin.com");
        }
    }

Here we create your own UserRepository that has a custom GetAdminUser() method (side note: personally I would put these kind of methods in my Service layer but not everyone would do that, especially on simpler applications).  This isn’t ideal because as mentioned before we are now hard-coding the use of an InMemoryRepository and we would need to change this and recompile if we switch to an Ef5Repository or if we want to add caching logic to this repository.  So here is a cleaner way to handle this:

    public interface IUserRepository : IRepository<User, int>
    {
        User GetAdminUser();
    }

    public class UserRepository : ConfigurationBasedRepository<User, int>, IUserRepository
    {
        public User GetAdminUser()
        {
            return Find(x => x.Email == "admin@admin.com");
        }
    }

Looks pretty much the same huh?  Well there is one big difference, instead of inheriting from InMemoryRepository we are inheriting from ConfigurationBasedRepository.  ConfigurationBasedRepository will use the configuration files to decide which type of repository to create .  Behind the scenes it is calling RepositoryFactory.GetInstance<User, int>() like we used above.

This setup gives you the ability code against IUserRepository while controlling the details of the repository and caching, etc. from your configuration file, allowing for easier maintenance (especially when in development and testing things).

What about dependency injection?

Personally my favorite Ioc container is StructureMap so that is what I’ll be using in my examples.  The same can be done in the Ioc container of your choice.

Let’s say you are creating an MVC application and you have a UserController that will need access to your IUserRepository (or IRepository<User, int> if you haven’t created a custom repository).  You will want to inject the repository into the constructor like this:

        private readonly IUserRepository _repository;
        public UserController(IUserRepository repository)
        {
            _repository = repository;
        }

Or like this:

        private readonly IRepository<User, int> _repository;
        public UserController(IRepository<User, int> repository)
        {
            _repository = repository;
        }

The only thing left to do is wire up StructureMap to be able to handle this.  Let’s just say that getting StructureMap to handle the generic arguments and use them to load the repository from the configuration file took a little Googling.  To make this easy to implement we have created some extension methods to use in your StructureMap registry (we also have equivalent methods for Ninject and Windsor).  All you need to do is install the StructureMap.Ioc.StructureMap NuGet package (or the other IoC packages).  The code that wires it up looks something like this:

            initialization.For(typeof(IRepository<>))
                                 .Use(context =>
                                 {
                                     var genericArgs = context.BuildStack.Current.RequestedType.GetGenericArguments();

                                     return RepositoryFactory.GetInstance(genericArgs[0], repositoryName);
                                 }
                );

            initialization.For(typeof(IRepository<,>))
                                 .Use(context =>
                                 {
                                     var genericArgs = context.BuildStack.Current.RequestedType.GetGenericArguments();

                                     return RepositoryFactory.GetInstance(genericArgs[0], genericArgs[1], repositoryName);
                                 }
                );

Then all you have to do is include the call to ForRepositoriesUserSharpRepository() extension method in your Initialize method like so:

ObjectFactory.Initialize(x =>
            {
                x.Scan(scan =>
                {
                    scan.TheCallingAssembly();
                    scan.WithDefaultConventions();
                });

                x.ForRepositoriesUseSharpRepository();
            });

That’s it.  Now StructureMap will load up the proper repository based on your configuration file when you request an IRepository<User, int> or a custom repository that inherits from it like IUserRepository in our example above.

For Ninject you would call kernel.BindSharpRepository() and for Windsor you can call container.RegisterSharpRepository().

Entity Framework and sharing the DbContext

As of SharpRepository 1.2, you can now use an IoC container to share your DbContext across multiple Ef5Repository instances.  We’ve created a RepositoryDependencyResolver that is used internally to request object instances.  The Ef5Repository uses this, if it has been configured, to get an instance of DbContext.  This allows the user to control the DbContext life-cycle.  We have created NuGet packages for Autofac, Ninject, StructureMap, Unity and Windsor that have custom RepositoryDependencyResolvers for each IoC container.  Just install the package that you need, or it’s really simple to create your own if you are using an IoC not listed here.  Keeping with StructureMap, here is how you would configure everything.

First make sure your StructureMap Registry has an entry for DbContext.  This would set the life-cycle to the ASP.NET page request, which makes the same DbContext available to all your repositories used during that request.

    // Hybrid (once per thread or ASP.NET request if you’re in a web application)
    For<DbContext>()
        .HybridHttpOrThreadLocalScoped()
        .Use<CustomEfEntities>()
        .Ctor<string>("connectionString").Is(entityConnectionString);

Find in your startup code where you are initializing your IoC and after that add the following:

    RepositoryDependencyResolver.SetDependencyResolver(new StructureMapDependencyResolver(ObjectFactory.Container));

This tells SharpRepository to use the StructureMap container (ObjectFactory.Container) to resolve DbContext.

Conclusion

Sorry for the long winding path to getting where I wanted to go, but hopefully showing the flexibility allowed is helpful and will allow you to use SharpRepository however you are most comfortable.  Personally, I like to use StructureMap to handle my dependency injections and will code against IRepository<User, int> unless there is a good reason to create my own custom repository.  In that case, I will have UserRepository inherit from ConfigurationBasedRepository and IUserRepository and code against the IUserRepositry interface.

When we last left our heroes, they fought their way through the superstructure of our application and were setting up to finish it off. Having defeated the TIE fighter screen, our intrepid fighter pilots have descended into the trench of the Starfighter Recognition Guide. Their computers are locked, they’re getting a signal…

In this post, we’ll capitalize on the code and plumbing we implemented here and here. We’ll take a look at the views we put in place and some javascript to make our Starfighter Recognition Guide a bit fancy-pants.

Stabilize your rear deflectors and watch for enemy fighters – there’s gonna be a tubolaser battery’s worth of code in this one.

The Index View

There isn’t a whole lot of interesting stuff going on in the home/landing page of the Starfighter Recognition Guide, (i.e. our index.html.erb). It’s basically a table that shows all of the Ships that have been entered so far. Here’s a pretty picture of what the home page looks like:

I know – neat-o, right?  If you want to see the source code for the index.html.erb view, you can check it out here.

The _form Partial View

Because functionality for adding a new Ship or editing an existing Ship is largely the same, I’ve created a _form.html.erb partial view that encapsulates all the data entry fields and extra goodies that we’ll need to persist our Ships and Pilots. Here’s what it looks like:

app/views/ships/_form.html.erb:

<%= form_for(@ship, :html => {:class => "form form-horizontal"}) do |f| %>
    <fieldset>
      <legend><%= "#{ @ship.name } " unless @ship.name.nil?  %>Ship Information</legend>
      <%= render('error_messages',  bject => f.object) %>
      <div class="control-group">
        <%= f.label(:name, :class => "control-label") %>
        <div class="controls">
          <%= f.text_field(:name, :class => "input-xlarge") %>
        </div>
      </div>

      <div class="control-group">
        <%= f.label(:crew, :class => "control-label") %>
        <div class="controls">
          <%= f.text_field(:crew, :class => "input-xlarge") %>
        </div>
      </div>

      <div class="control-group">
        <%= f.label(:has_astromech, :class => "control-label") %>
        <div class="controls">
          <%= f.check_box(:has_astromech, :class => "checkbox") %>
        </div>
      </div>

      <div class="control-group">
        <%= f.label(:speed, :class => "control-label") %>
        <div class="controls">
          <%= f.text_field(:speed, :class => "input-xlarge") %>
        </div>
      </div>

      <div class="control-group">
        <%= f.label(:armament, :class => "control-label") %>
        <div class="controls">
          <%= f.text_area(:armament, :class => "input-xlarge", :rows => "3") %>
        </div>
      </div>
    </fieldset>

    <fieldset>
      <legend>Pilots <%= "That Fly the  #{ @ship.name }" unless @ship.name.nil? %></legend>
      <%= render('pilots_table', :f => f) %>
      <%= link_to_add_fields("Add a Pilot", f, :pilots, :class => "btn btn-primary", :title => "Add a new Pilot to the list of Pilots that fly this Ship.") %>
      <p></p>
    </fieldset>

    <div class="modal-footer">
      <%= f.submit("Save", :class => "btn btn-primary", :title => "Save the changes to this Ship.") %>
      <%= link_to("Cancel", ships_path, :confirm => "Are you sure you want to cancel?  Any changes will be lost.", :class => "btn btn-inverse", :title => "Cancel the changes and return to the Home page.") %>
    </div>
<% end %>

The interesting part is on line 43, where we’re rendering the _pilots_table.html.erb partial view. Notice how we’re passing our form to it? That’ll allow us to use the fields_for method on the “parent” form (i.e. the Ship‘s form) to generate input fields for all the Ship‘s Pilots. Let’s take a look at the _pilots_table.html.erb partial view, shall we? Yes, let’s:

app/views/ships/_pilots_table.html.erb:

<table id="pilots-table" class="table table-hover table-striped">
  <thead>
    <th>First Name</th>
    <th>Last Name</th>
    <th>Call Sign</th>
  <th></th>
  </thead>
  <tbody>
    <%= f.fields_for(:pilots) do |pilots_form| %>
      <tr class="fields">
        <td><%= pilots_form.text_field(:first_name) %></td>
        <td><%= pilots_form.text_field(:last_name) %></td>
        <td><%= pilots_form.text_field(:call_sign) %></td>
        <% if current_page?(new_ship_path) || current_page?(edit_ship_path) %>
            <td>
              <%= link_to_remove_fields('<i class="icon-remove"></i>'.html_safe, pilots_form, :title => "Delete this Pilot.") %>
            </td>
        <% end %>
      </tr>
    <% end %>
  </tbody>
</table>

On line 9, we’re calling fields_for to generate the input fields for each Pilot associated to our Ship. Also notice on line 16 we’re using our link_to_remove_fields helper method (described in exhaustive detail here) to create a link that will allow us to delete the Pilot if we want. Because we’ve used fields_for to wire up the input fields for our associated Pilots, we can edit any of the Pilots and/or the Ship‘s attributes. When we submit our form, everything will be saved to the database in one swell foop. To see what the POST might look like when this form is submitted, you can take a look here.

To see this in action, let’s take a look at a screenshot of a Ship being edited:

Adding a new Ship and Pilot

As mentioned previously, adding a new Ship is pretty much like editing an existing Ship. Let’s add a new ship to our Starfighter Recognition Guide: The TIE Interceptor. We click the “Add a Ship” button on the home/landing page, and end up with something like this:

Now we click on the “Add a Pilot” button, which renders our _pilot_fields.html.erb partial view as a modal form. We talked about the mechanism to make this work (our link_to_add_fields helper method) in the last post. Shown below is a screenshot of the modal form that allows us to add a new Pilot:

Here’s what the _pilot_fields.html.erb looks like under the covers:

app/views/ships/_pilot_fields.html.erb:

<div id="new-pilot-fields" class="modal fade" data-backdrop="static">
  <div class="modal-header">
    <button type="button" class="close" data-dismiss="modal" aria-hidden="true">×</button>
    <h3>Add a Pilot<%= " to the #{ @ship.name } Pilot Roster" unless @ship.name.nil? %></h3>
  </div>
  <div class="modal-body">
    <fieldset>
      <div class="control-group">
        <%= f.label(:first_name, :class => "control-label") %>
        <div class="controls">
          <%= f.text_field(:first_name, :class => "input-xlarge field") %>
        </div>
      </div>

      <div class="control-group">
        <%= f.label(:last_name, :class => "control-label") %>
        <div class="controls">
          <%= f.text_field(:last_name, :class => "input-xlarge field") %>
        </div>
      </div>

      <div class="control-group">
        <%= f.label(:call_sign, :class => "control-label") %>
        <div class="controls">
          <%= f.text_field(:call_sign, :class => "input-xlarge field") %>
        </div>
      </div>
      <%= f.hidden_field(:_destroy, :class => "field") %>
    </fieldset>
  </div>
  <div class="modal-footer">
    <button id="addButton" type="button" class="btn btn-primary" data-dismiss="modal" aria-hidden="true" title="Add this Pilot to the list of Pilots that are assigned to this Ship.">Add</button>
    <button id="cancelButton" type="button" class="btn btn-inverse" data-dismiss="modal" aria-hidden="true" title="Close this screen without adding the Pilot to the list.">Cancel</button>
  </div>
</div>

<script type="text/javascript">
  pilotFieldsUI.init();
</script>

There isn’t anything very fancy going on in the _pilot_fields.html.erb partial view. I’d go so far as to say the only interesting bit is the script tag at the bottom. What’s going on there? Let’s find out!

Javascript for the Pilot Modal Form

So, we have our Pilot input fields appearing in a modal form. What now? What should happen when a user clicks the “Add” button on the modal form? How will a user be able to add multiple Pilots to a single Ship?

Well, it’d be nice if the newly created Pilot was added to the “Pilots” table shown in the “Add a Ship…” screen (shown above). Ideally, it’d be nice if the rows looked exactly the same as the “Pilots” table in the “Editing…” screen (also shown above).

app/assets/javascripts/ships.js:

var pilotFieldsUI = {
    init: function() {
        $('#addButton').on('click', function() {
            formHandler.appendFields();
            formHandler.hideForm();
        });
    }
};

The code above shows our pilotFieldsUI object literal, which has one function: init. The init function wires up the addButton on our Pilot modal form. As you can see, a couple of methods will be invoked when a user clicks the “Add” button on the Pilot modal form. Let’s check those out next:

app/assets/javascripts/ships.js:

var formHandler = {
    // Public method for adding a new row to the table.
    appendFields: function() {
        // Get a handle on all the input fields in the form and detach them from the DOM (we will attach them later).
        var inputFields = $(cfg.formId + ' ' + cfg.inputFieldClassSelector);
        inputFields.detach();

        // Build the row and add it to the end of the table.
        rowBuilder.addRow(cfg.getTBodySelector(), inputFields);

        // Add the "Remove" link to the last cell.
        rowBuilder.link.appendTo($('tr:last td:last'));
    },

    // Public method for hiding the data entry fields.
    hideForm: function() {
        $(cfg.formId).modal('hide');
    }
};

Again, the formHandler is nothing spectacular. The idea behind the formHandler is like this: the formHandler manages the orchestration of all the fancy UI stuff. He’ll delegate the specifics (e.g. building a row element w/the Pilot input fields) to other objects. In this case, we want to build a row that we’ll add to the Pilots table and we’ll want to hide the modal form when we’re done. To achieve that, we have a couple of methods:

• appendFields: This method will add the input fields from the Pilot modal form and add them as a new row to the Pilots table on the Ship form.
• hideForm: Hides/dismisses the Pilot modal form (thanks, Twitter Bootstrap!).

I wanted to keep all of my IDs and other “magic string” type stuff in one place, so I created a quick cfg object literal that looks like what’s shown below:

app/assets/javascripts/ships.js:

var cfg = {
    formId: '#new-pilot-fields',
    tableId: '#pilots-table',
    inputFieldClassSelector: '.field',
    getTBodySelector: function() {
        return this.tableId + ' tbody';
    }
};

The cfg object is referenced by the formHandler and the rowBuilder. That gives me an excellent segue to the rowBuilder, which looks like this:

app/assets/javascripts/shipsjs:

var rowBuilder = function() {
    // Private property that define the default <TR> element text.
    var row = $('<tr>', { class: 'fields' });

    // Public property that describes the "Remove" link.
    var link = $('<a>', {
        href: '#',
        onclick: 'remove_fields(this); return false;',
        title: 'Delete this Pilot.'
    }).append($('<i>', { class: 'icon-remove' }));

    // A private method for building a <TR> w/the required data.
    var buildRow = function(fields) {
        var newRow = row.clone();

        $(fields).map(function() {
            $(this).removeAttr('class');
            return $('<td/>').append($(this));
        }).appendTo(newRow);

        return newRow;
    }

    // A public method for building a row and attaching it to the end of a <TBODY> element.
    var attachRow = function(tableBody, fields) {
        var row = buildRow(fields);
        $(row).appendTo($(tableBody));
    }

    // Only expose public methods/properties.
    return {
        addRow: attachRow,
        link: link
    }
}();

The rowBuilder has one purpose in life – to build a <TR> element that will be added to the “Pilots” table. The <TR> element will contain the input fields from the Pilot modal form.

The rowBuilder is a bit more complex than his brethren cfg or formHandler. There are some properties/methods of the rowBuilder that don’t need to be called by anyone else, so I wanted to keep those private. To achieve that, I used the revealing module pattern (sounds awesome, right?!) to only expose the methods that should be… err… exposed, I guess. I like this pattern a lot and I think you get a lot of bang for your buck by using it. It’s easy to implement, makes code more readable, and clearly communicates the intent to other developers. With an extra line or two, we’ve told the next guy/girl who works on this project what parts of the rowBuilder are guts/plumbing and what parts are intended for use by other components of our program.

CODE SMELL: The rowBuilder.link property should probably be private and should probably be added to the new <TR> element before it’s returned. Right now, the rowBuilder.link property is used in the formHandler.appendFields() method (line 12 in the formHandler snippet). This is an area that is ripe for refactoring.

With all that javascript, what happens when a user clicks the “Add” button after adding a new Pilot to the Tie Interceptor Ship? Well, the screen looks like this:

Summary: It’s Away!

So… there you have it. We created a new TIE Interceptor Ship with a Pilot named Maarek Stele. Because of our implementation, the user can change any of the Pilot attributes before committing everything to the database. When the user clicks the “Save” button, the POST will contain the Ship and Pilot attributes (again, en example of what the POST will look like can be found here).

Devil’s Advocate: My Scope’s Negative, I Don’t See Anything!

Hey Jeff, how come you didn’t just append a row with new input fields to the ‘Pilots’ table to begin with? What’s with all the modal mumbo jumbo?
Sure, we could’ve done that. If you remember from a long time ago in a post far far away, the mission was to add “child” objects to a parent object using a modal data entry form. Besides, I think the modal data entry form makes for a better user experience. Adding a new row of data entry fields would be a little subtle, don’cha think? If you pop up a modal form in front of the user, there’s no confusion about what’s going on. It’s very clear (I hope, anyway) that the user is supposed to provide data for a Pilot and add it to the list.

Reference

• Railscast 197 was instrumental in getting me started with accepts_nested_attributes_for and fields_for.
• The source code for the Starfighter Recognition Guide can be found here.

In our previous post, our intrepid heroes were hurtling headlong into the trenches of the Starfighter Recognition Guide. They maneuvered through the superstructure of the application, setting up a relationship between themselves (the Pilots) and the Ships they fly. In this post, our ace Rebel pilots will make their approach to the surface of our application.

The Controller

Because all of the heavy lifting is being handled by the ActiveRecord configuration defined in our domain model, the controller for the Ship model is pretty standard fare. As a quick refresher, here’s what the create method in the ships_controller looks like:

  def create
    @ship = Ship.new(params[:ship])

    if @ship.save
      redirect_to(ships_path, :notice => "The #{ @ship.name } ship has been saved successfully.")
    else
      render(:new, :error => @ship.errors)
    end
  end

If you’re interested in looking at the controller in its entirety, you can check it out here.

The Helper Methods

Taking a cue from the Railscast, I’ve added a couple of helper methods to make my life a little easier:

app/helpers/application_helper.rb:

module ApplicationHelper
  def link_to_remove_fields(name, f, options = {})
    f.hidden_field(:_destroy) + link_to_function(name, "remove_fields(this)", options)
  end

  def link_to_add_fields(name, f, association, options = {})
    new_object = f.object.class.reflect_on_association(association).klass.new
    fields = f.fields_for(association, new_object, :child_index => "new_#{ association }") do |builder|
      render(association.to_s.singularize + "_fields", :f => builder)
    end

    link_to_function(name, "add_fields(this, \"#{ association }\", \"#{ escape_javascript(fields) }\")", options)
  end
end

The code above is lifted pretty much verbatim from the Railscast, but I still think it’s worth going over:

• link_to_remove_fields: This method will create a hidden _destroy field (which tells us whether or not the record should be deleted) and a hyperlink that will invoke a javascript method to update our _destroy field.
• link_to_add_fields:This method will:
  • Create a new instance of our association object (a new Pilot in this case).
  • Builds a form that we can use to edit our new Pilot object.
  • The :child_index will be a placeholder that will be replaced by a unique value generated in javascript (more on that in a minute).
  • Build a hyperlink containing a form for our Pilot object.

The fields_for Method

Let’s take a look at what’s going on with the second and third lines of link_to_add_fields (lines 8 and 9 in the code shown above). We’re using the fields_for method to build the Pilot input fields for us. At a high level, the fields_for method allows us to build an HTML form without the <form> tags. That means we can put our fields in the “parent” form without any problems.

The fields_for method takes a few parameters:

• record_name: The name of the type of record we want to create. In our case, we’ll pass “Pilots” for this parameter.
• record_object: An instance of the object we want to add/edit. In our case, this will be a Pilot object. We created a new Pilot object on the previous line of our link_to_add_fields method (line 7 in the code shown above).
• options: Any options that we might want to pass to the fields_for method. In our case, we want a way to uniquely identify each Pilot we create. So, we use a :child_index, and set it to a “placeholder”. For this specific example, our placeholder text will be “new_pilots”. This placeholder will be replaced with a unique identifier when the form is shown (i.e. when the add_fields javascript method is called).

In our fields_for block, we’re asking it to render our _pilot_fields.html.erb partial view. Observe the second parameter, :f => builder is the parent form (i.e. the form that contains the input fields for the Ship we’re working with). This means that the Pilot fields rendered in our call to fields_for will be a part of the “Add a Ship” form, which is exactly what we want.

At this point, our fields variable should look like a bit like this (tidied up so it can actually be read):

×
Add a Pilot



First name


Last name


Call sign




Add Cancel

In the last line of the link_to_add_fields method (line 12 in the code above), we hand off the contents of the fields variable to the link_to_function method. The link_to_function method is setting up a link that will call our add_fields javascript method (described in the next section). The fields value will be used as the content parameter of the add_fields method.

The Javascript

What’s a web app without a little javascript? Our helpers shown above make use of the Rails built-in link_to_function helper. The link_to_function will be used to call the javascript methods shown below.

app/assets/javascripts/application.js:

function remove_fields(link) {
    $(link).prev("input[type=hidden]").val("1");
    $(link).closest(".fields").hide();
}

function add_fields(link, association, content) {
    var new_id = new Date().getTime();
    var regex = new RegExp("new_" + association, "g");
    $(link).parent().after(content.replace(regex, new_id));
    $('#new-pilot-fields').modal('show');
}

Again, the code shown above comes pretty much verbatim from the Railscast. The remove_fields function is pretty straightforward:

1. Find the hidden input field that comes before our “Remove” (our _destroy field) link and set it’s value to 1 (i.e. true, meaning we want ActiveRecord to delete this record for us).
2. Find the closest element that has a class="fields" (in our case, this will be a &ltTR> element) and hide it. Presto! As far as the UI is concerned, we’ve deleted a Pilot!

The add_fields function is a little more involved, but there’s nothing too fancy:

1. Generate an arbitrary unique id based on the current time.
2. Build a regular expression that will search for “new_” + [whatever the name of our association is] (“new_pilots” in our case).
3. Search through our content (the string that represents our Pilot form) and replace “new_pilots” with the unique id we generated in Step 1.
4. Add the Pilotform to the DOM.
   • To be very clear, the HTML shown in the description of the fields_for method will be added to our Add a Ship screen (which we haven’t seen yet, but trust me – it’s on its way).
5. Display the Pilotform as a modal popup.
   • The modal method comes from Twitter Bootstrap.

Now, when a user clicks our “Add a Pilot” link (which we’ll see in the next article), a modal form with our Pilot input fields will appear. Hooray!

Summary: Cut the Chatter, Red 2!

We’re bouncing through the magnetic field with our deflectors on. While we haven’t started our attack run on the views yet, our approach is set up – the code in this post will make setting up our views a whole lot easier. In our next installment, we’ll switch on our targeting computers and attack the views. Before they know it, our Rebels will have a full-fledged Starfighter Recognition Guide with which to record their exploits and tales of derring-do.

Stay on target!