In this post, I am going to provide an example of how to use the FubuMVC.Coffee NuGet in your FubuMVC application.

Where’s the code?

I’ve created a repository to show of example of all of this in action: https://github.com/jmarnold/FubuOnCoffee

Getting Started

A nice introductory post to FubuMVC’s Asset pipeline is well overdue. I’m going to touch on the simplest configuration and just promise that I’ll get to a more in-depth blog about it later.

First, we start by creating an asset config file (*.asset.config):

For more examples on the syntax, check out the dsl reader.

Configuring the Transform

Running your application with above asset configuration will “run”, but you’re going to get the raw contents of the coffeescript file. In order to enable the transformation, you can install the FubuMVC.Coffee nuget:

Install-Package FubuMVC.Coffee

This will install a zip file inside of a fubu-content directory at the root of your web application. Thanks to the beauty of Bottles, this zip file will be exploded out and the CoffeeScript configuration will be invoked automatically.

Now running your application with above asset configuration will give you the transformed contents of example.coffee.

What is Jasmine?

From the Jasmine docs:

Jasmine is a behavior-driven development framework for testing your JavaScript code. It does not depend on any other JavaScript frameworks. It does not require a DOM. And it has a clean, obvious syntax so that you can easily write tests.

If you’ve done any work with Jasmine (even if it’s a simple “Hello, World!”), you know that the basic setup is the Jasmine Standalone Runner.

What’s wrong with the Standalone runner?

The standalone Jasmine runner requires some basic boilerplate content within html and javascript files to execute your specs. This works great for a very simple setup but as you try to use this in an actual project, you may find yourself feeling the following pains:

• Lack of build/rake/CI integration
• Tedious/repetitive setup required to organize your specs

Let me elaborate on that last one: the standalone runner works great for a single spec file. For each spec file that you want to test, you need an equivalent test runner html file.

My team needed a solution to alleviate this pain…so naturally, I waited for Jeremy to do something about it .

Introducing Serenity

The Jasmine Runner within Serenity leverages Bottles and the Fubu Kayak host to spin up a content-only Fubu application that sits on top of your file system. There are lot of technologies and concepts in play here so I will unpack that statement by way of a nice and detailed example.

All of this is available via my jasmine-example repo on github. You may wish to clone it locally and follow along.

Getting Started

You can obtain the Serenity tools in a variety of ways. The easiest way is simply to install the Serenity package via NuGet. In this example, I began with a simple ASP.NET Empty Web Application and installed the Serenity NuGet package.

After installing the NuGet package, we begin by following the directory structure used by FubuMVC’s Asset Pipeline. All this means is that we have a folder named “content” in the root of our application. Within that content folder is a “scripts” folder. We then place all of our scripts within said folder.

You can view the sample structure here.

Note:
The example repo makes use of Fubu’s ripple infrastructure and rake. If you’re wondering where the NuGets are, simply run a default rake and ripple will pull them down.

Creating your first spec

The Serenity Jasmine runner (from now on I’m just going to refer to it as “the runner”) takes care of pairing up your script and your spec file and it does so by the following convention:

• simple.js (the script)
• specs/
  • simple.spec.js

Let me further explain that one…

Each folder underneath content/scripts is considered a SpecificationFolder. Any files that exist in each of these SpecificationFolders are automatically paired with files within the relative specs folder. The naming convention is simple: “x.js”, “x.spec.js”.

Ok, now that I’m confused you how about we start the runner and you can see it all come together?

Running the spec

There’s a little bit of rake-fu in the repo to make this nice and easy:

rake open_jasmine

This launches the runner in interactive mode (read “development” mode) and provides simple “auto-test” functionality. That is, any file modifications trigger an automatic refresh of the browser.

As Figure 1 shows, the start page displays all of the available specifications and then lets you drill down to execute them (like R# groups projects in your solution).

Is it that simple?

In a perfect world, you could install a NuGet via the CLI and be able to just launch the runner immediately. But hey, we’re getting closer, right? I’ve wrapped up all the boiler plate stuff involved in getting started with the runner in this repo so that you don’t have to.

What else can it do?

Here a few highlights that I can dive into more in depth if you’re interested:

• A file named jasmine.helper.js within any specs folder is loaded for your specs. There is an example of this in the repo w/ complex.spec.js
• The runner can also be simply ran as an exe and integrated into your build via exit codes. The default rake task in the repo is an example of how to do this

Any “gotchas”?

There a few very specific things to note here:

1. The runner needs a “serenity.txt” file relative to where your project lies. You can specify the location of the file (and the name) but the contents are used to configure the runner (e.g., “include:MyProject”)
2. The runner makes use of Fubu’s asset pipeline. It tries to be helpful by automatically requiring a script asset named “core”. If you don’t have a “core” (e.g., aliased file, set) then the runner will likely bomb. The example repo has a core.script.config that shows a workaround for this.

Are there any examples in the wild?

FubuValidation recently merged in the fubuvalidation.js work and now leverages the Serenity Jasmine runner as part of its build.

I think Jimmy put it the best when he said: “Yeah, I read your posts but there just wasn’t a whole lot of code”. So this time I’m going to write a post that’s mostly code and see if it helps.

Show me something concrete

Let’s start with an example and then I’ll explain what’s going on:

If you run this example, you’ll be shown a dialog. Clicking “Success” or “Failure” will demonstrate the behavior of a successful or failed http post (respectively).

NOTE:
I’ve noted this in the code several times but here it is again: don’t bother with the “Server” stuff. It’s just a helper to mock the ajax calls since we’re not using a server here.

Custom options

We are making use of the correlatedSubmit method here (an extension to jquery.forms). Notice that we’re passing in the custom “closeDialog” property.

Passing in a hash to correlatedSubmit or as the “options” property of the hash to $.ajax provides a local set of custom options that are made available during the processing of the clientside continuation.

Great, what does that mean? Well, here’s how this works:

Whenever a continuation is received (via the success callback from $.ajax), this custom dialog policy will be inspected. Notice that we’re matching against “continuation.options.closeDialog”. The options property of the continuation contains the same options that you passed in so in this case, “closeDialog” would be true.

Note:
My first pass at this didn’t have these custom options and our conventions were ALWAYS global. You should ask Jeremy what he thought about that.

In case you missed the point here, our policy conventionally closes a jquery ui dialog when the response was successful.

Reusable conventions

Conventions are only “conventions” when they’re reusable. Reusable pieces of code really strut their value when they’re reusable in more than one project.

The “Failure” button demonstrates a failed continuation response from the server. fubuvalidation-js has a built-in convention for detecting those errors and rendering them into the form that originated the request. So simply including fubuvalidation-js into this jsfiddle was enough to get that to work.

From client to server

The validation and “close dialog” policies are pretty useful. For us, they’re very useful because we use them throughout our app. These are just two simple examples of what can be done here. Let’s brainstorm a few more to make sure I’m articulating the power of this correctly:

• Refresh the page (force a full refresh on certain conditions)
• Redirect to a new url
• Display errors (“something went terribly wrong”)
• Keep track of pending ajax requests

The list goes on and on but let’s talk about this “redirect to a new url” idea.

APIs and Continuations

A common technique found in HTTP-based APIs is to provide a set of information regarding a resource when it is created. For example, “POST /users/create” may return things like:

• The ID of the User
• Some urls (e.g., “go here to view the details”, “go here to edit the user”

If you design your endpoints to follow a similar technique, you can plugin policies that use the response and orchestrate the behavior of your system from a central block of code. Of course, in small applications this doesn’t pay off but in large and complex systems the value starts to shine.

Wrapping it up

Hopefully the code speaks for itself and this sparks a few ideas.

In this series of posts, I’m going to cover a few topics:

1. The AjaxContinuation
2. Clientside Continuations
3. Request Correlation
4. Validation (this post)

Correlation by form

Last time I discussed how to correlate your requests with jquery.continuations. One of the gems that ships with continuations is the $.fn.correlatedSubmit method for forms. This method uses the id of the form (a quick unique check is performed) as the correlation id.

fubuvalidation.js

Note:
This isn’t an exhaustive explanation of the new fubuvalidation.js bits. I’ll flush this out in the docs.

Not another one…

First off: no, it’s not “another js validation library”. fubuvalidation makes use of the continuation contract but makes no effort to perform client-side validation. Instead, it aims to bridge that gap between client-side and server-side validation.

The handler

I’m only explaining this because I know I’ll get asked about it. fubuvalidation.js ships with a default handler. This handler renders a nice validation summary, highlights fields, and provides a little bit of interactivity. And of course, the handler is exposed through $.fubuvalidation.defaultHandler so you can override any of the functions that you don’t like. And like the rest of the Fubu projects, you can completely override our defaults if you don’t like them.

Back to my point…

fubuvalidation.js relies on the continuation that is returned by any of your ajax calls via jquery.continuations. Here’s how we plug into the pipeline:

Just another example of what you can do once you get your conventions defined.

In this series of posts, I’m going to cover a few topics:

1. The AjaxContinuation
2. Clientside Continuations
3. Request Correlation (this post)
4. Validation

Correlating your requests

This isn’t a new thing. If you’ve ever dealt with messaging, then you’ve most certainly dealt with the concept. It’s nothing different with the web. But first, let me just answer…

Why?

Why would you want to be able to identify the response for a given request? Here are two that stood out for me:

1. Keeping track of outstanding requests

There’s this fun thing that you run into when you’re doing automated UI testing and it’s called “waiting”. You wait for elements to be shown – sometimes intelligently or blindly (Thread.Sleep – gah). If you’re able to track your pending requests, you can be a little smarter about waiting for operations to complete.

2. Knowing which form made a request

This is an interesting one. When I know which form was a responsible for a given request, I can handle validation much easier and have more fun with conventions (like closing a dialog).

How it works

When a request is initiated, jquery.continuations appends a custom header: X-Correlation-Id. This value originates from one of two sources: 1) randomly assigned for a request 2) the id of the form responsible for the request.

It’s up to your web framework to handle shoving the header back into the response. Here’s an example of doing it in FubuMVC:

Assuming that you are sending the header back down through your response, jquery.continuations handles it from there by doing two things:

1) The AjaxCompleted topic

This topic is published through the jquery.continuations event aggregator façade (we use amplify). The message that is published contains a correlationId property with the appropriate value.

2) The continuation processing pipeline

Before the continuation is processed, the correlationId property is set.

Simple usage

I always understand best by seeing some code. Here’s an example of how to keep track of pending requests:

Until next time.

In this series of posts, I’m going to cover a few topics:

1. The AjaxContinuation
2. Clientside Continuations (this post)
3. Request Correlation
4. Validation

$.continuations

I have not had time to make this code public yet, but I promise I’ll get around to it. In the meantime, I’ll explain the concepts and just gist the highlights.

Update:
I’ve released an initial v0.1 version of this called jQuery.continuations.

The Setup

We start by hooking into jQuery’s global $.ajaxSetup call:

This is happening within a module block so the “self” is something I’ve declared above this piece of code.

Our convention is that unless you explicitly provide a success callback to any $.ajax call, you’re going to get this one for free.

Processing Continuations

I’ve talked about policies before and that’s exactly what we’re using to process the continuations. We have two functions: 1) matches(continuation) and 2) execute(continuation). Policies are registered via: $.continuations.applyPolicy() and we have several defaults.

refreshPolicy
Matches when refresh is true.
Simply refreshes the page.

navigatePolicy
Matches when url is not empty
Navigate the window to the specified url.

errorPolicy
Matches when success is false and there are errors
Publishes the ‘ContinuationError’ topic through amplifyjs

payloadPolicy
Matches when the following properties exist: payload, topic
Publishes the specified topic and payload through amplifyjs

We have a couple more but I’ll save those for the next post.

Fun Fact

The payloadPolicy is an interesting one. We knew that we were going to be working w/ websockets but we didn’t start with them. Instead, we used this infrastructure and simply shoved topics/payloads into our continuations. When a response was received, the information was published through amplify and we had structured our code to work against those topics.

When it came time to turn on websockets, we simply started publishing websocket messages through amplify and everything kept working like a charm.

Until next time.

Note:
I want to make note of one thing here. As usual, I will be using FubuMVC as an example implementation of these concepts. However, these concepts are applicable in any web framework.

In this series of posts, I’m going to cover a few topics:

1. The AjaxContinuation (this post)
2. Clientside Continuations
3. Request Correlation
4. Validation

The Ajax Continuation

Like every “convention”, you have to start with some commonality and standardize a few things. For our usage, we chose to use the standard AjaxContinuation in FubuMVC. Here’s a JSON representation:

Nothing too fancy here but this is just the baseline. The point is that while there may be additional properties specified on a particular instance, the properties above will always be there.

Let’s run through each of the properties:

success
Type: bool
Flag indicating whether the request was successful.

refresh
Type: bool
Flag indicating whether the page should be refreshed.

message
Type: string
Server generated message describing the result of the request (or anything else you want to use it for)

errors
Type: Array
An array of AjaxError objects ( { category: ‘’, field: ‘’, message: ‘’ })

AjaxContinuation and FubuMVC

As I said before, this is a first-class citizen in FubuMVC. There are default conventions provided for you. All you need to do is return an AjaxContinuation from one of your actions and we take care of the rest.

But just for sake of clarity, here’s an example:

Don’t worry, I give a lot more information in the next few posts.
Until next time.

fubu new is a command that is available via the Fubu Command Line tool. So, think “rails new” for fubu. Sort of.

If you’re waiting on pins and needles for how to just start using it, skip ahead to the end.

Templates

First let’s talk templates. Why? Because that’s what powers this fun little command and they come into two shapes: 1) zip files and 2) git repositories. Yep, I just said git repositories. But first…

What’s in a template?

A template is a folder structure that you want copied over after a set of replacements has occurred. The replacements are pretty simple:

• FUBUPROJECTNAME – The projectName argument specified (fubu new projectName)
• FUBUPROJECTSHORTNAME – The last value of projectName split on “.” (e.g., FubuMVC.Plugin => Plugin)
• GUIDx (where x is a valid number) – A generated and cached guid (more on this)

What all gets replaced?

File contents, file names, and directory names.

I don’t get the “GUIDx” thing

Let’s say you have a template with two projects: 1) A standard class library and 2) a class library used as a testing project for the first.

Problem:

You want a new GUID for both projects but need a way to correlate them so that your second project can reference the first and provide metadata.

Solution:

The first project uses “GUID1” as its ID. The second project uses “GUID2” as its ID. The second project then uses “GUID1” when referring to the first project.

How do I specify a template?

As I mentioned before, there are two ways:

Zip Files

You can specify a zip file using the –z flag.

fubu new MyProject –z my-template.zip

Git Repositories

You can specify a git repository using the –g flag.

fubu new MyProject –g git://my-repo.git

What if I don’t want to type/remember the git url?

I’m glad you asked. You can place a .fubunew-alias file right alongside the fubu.exe executable. The aliases specified in that file can then be used for the –g flag.

We also ship with two default aliases (regardless of the existence of the file):

• fubusln = git://github.com/DarthFubuMVC/rippletemplate.git
• fububottle = git://github.com/DarthFubuMVC/bottle-template.git

New vs. Existing Solutions

The examples above show fubu new working for brand new solutions. That’s great but we’ve found that adding a new project/test project/integration project (etc.) can be a royal pain. No, it’s not hard but it is time consuming.

Appending to an existing solution

Specifying the –s flag and providing the location of a solution file will do a few things for you.

First, we explode the contents and move them into the solution directory (if you have weird folder structures, you can override the output location with the –o flag). Then we loop through the new projects we just created and append them to the solution file that you specified with the –s flag.

What about custom one-off scenarios?

The whole “one-off” scenario first occurred during testing. Then we realized that any useful template will almost ALWAYS have some custom one-off scenario. So we added a nifty little idea:

rake callback script

You can specify a rake file to execute after the templating is finished using the –r flag. You can do whatever you’re capable of doing with rake here. Check out our bottle template for a simple example.

But I always want to execute the script

If you don’t want to have to remember to specify the –r flag, simply name your rake file “.fuburake” and it will automatically get run.

What if I want to exclude certain files in the templating?

Some files exist in your template just for executing (e.g., rake callbacks, a placeholder file to read a value). Simply create a .fubuignore file in your template (the syntax is the same as .gitignore). Any files will be excluded in the copy.

For an example of everything in action, take a look at our ripple-ized solution template.

How do I start using it?

Well, a couple of things to note…

Is it available right now?

Yes and No…the new FubuMVC.References nuget will be published on 12/19. At which point, all of the information I just provided will be valid. As of right now, fubu new doesn’t do very much. Sorry, but I wanted to write this blog while I had the chance.

If you want to play with it today, simply clone FubuMVC and build the solution. The exe will be located in src/Fubu/bin/Debug.

When it is available through NuGet, how do I use it?

Add a reference to FubuMVC.References and fubu.exe will be in the tools directory of that package.

One of the questions I hear the most is:

“What’s the Fubu folder structure? Where do I put controllers?”

I admit, I stumble through my answer as I say unhelpful and ambiguous things like “you can do whatever you want”. So, for those of you who have asked me and haven’t received help, consider this as me cashing in my “I owe you”.

ActionCalls

If you haven’t learned about these yet, then you may want to get a little bit of background. I try my best to introduce the subject in my F101 video and Mike Murray gives an overview as he walks you through building your first Fubu application: http://mvc.fubu-project.org/videos

Discovery

The magic of the discovery happens through one very simple interface:

Like most things used in our semantic model construction, we use this interface internally and expose a DSL for convenience. In this case, we do so via the Actions property on the FubuRegistry.

I was going to spend the time to write up about this piece, but Chad Myers already did: Cool stuff in FubuMVC No. 2: Action Conventions

The only thing I want to add is that you can register your own IActionSource implementations via the FindWith method (e.g., Actions.FindWith<MyActionSource>()).

Note:
Dependency injection is not around for the DSL pieces for FubuRegistry. However as a workaround (if you MUST),  the bootstrapping mechanism works in a way that you’ll have access to ObjectFactory inside of your action sources. It’s not ideal, but it’s there just in case you need it.

Piecing it together

Underneath the hood, we use the BehaviorAggregator class to operate on all IActionSource implementations and register a behavior chain for each call that is found.

Why do I care?

Scanning is great and it covers you for probably 80% of all use cases (yes, I just made up that statistic). Here’s an example of when it won’t:

Maybe we want to scan our system for all of our known entity types and close on this open generic. Your best bet is to register your own action source that will do exactly that:

And that’s it. It’s simple but powerful.

We’ve had even more questions arising about “what are Bottles” since my last post and our sessions at Pablos Fiesta. I think my favorite question after our explanations is: “WTF is a Bottle?”

Forgive me, you’ll find me mixing “Bottles” and “packages” often. I won’t promise that I’m not going to do this, but I will promise that I’ll be consistent: Bottles (capitalized) means the framework. “bottles” (not capitalized) and “packages” mean the actual files.

WTF is a bottle?

I like this question. Let’s take away all the glamour and expose the interface that changes everything:

This is a cornerstone of the Bottles framework as it represents the smallest unit of data that we’re concerned with. This unit is comprised of a few things. Let me draw your attention to two of them: 1) assemblies and 2) data.

They come in all shapes and sizes. Our most commonly used implementations are: 1) AssemblyPackageInfo and 2) PackageInfo (just a file/directory – typically a zip file).

Playing with your AppDomain

I mentioned that Bottles provides assemblies. That’s great and all, but if you’ve ever spent time loading those into your AppDomain and making every thing play nice, then you understand the pains that are involved. If Bottles does nothing else right as a framework, I’d call it a success because it makes dealing with this a breeze.

Don’t worry, I’ll dive into details but at a high-level Bottles gives you the ability to conventionally load assemblies into your AppDomain and give you a uniform way of responding to them.

So how does it all work?

Execution Flow

The execution of all of Bottles occurs through the static LoadPackages method in the PackageRegistry class. This little gem gives you a DSL for hooking into the loading mechanism while Bottles does it magic.

IPackageFacility

This is the abstraction that allows various frameworks to plugin and make use of the Bottles infrastructure (e.g., FubuMVC, Topshelf). You can specify custom IPackageLoader implementations here and let Bottles know about how you want to find your bottles.

IPackageLoader

These tell Bottles how you want to find your bottles. FubuMVC ships with a few (ZipFilePackageLoader being an important one) and Bottles has its own internal ones.

In fact, Bottles ships with a very important one: LinkedFolderPackageLoader. This allows a “.links” file to be included in your projects so that you can dynamically load other projects in your solution as bottles (rather than installing/uninstalling or dealing with DLL references).

IBootstrapper

So you’ve loaded up your bottles…now what? When you’re configuring Bottles, you can specify custom IBootstrapper implementations which tells Bottles about the all important IActivator interface. This interface is here so that you can find these IActivator implementations however you like (e.g., scan the assembly for implementations with a default constructor, pull them from your IoC container).

IActivator

This little gem allows for “start up” operations within Bottles. FubuMVC actually leverages this internally for some of the Bottles interoperability. For example, we have a Bottles-friendly virtual path provider that gets registered through an IActivator.

This interface has full access to anything in your AppDomain so that options are pretty limitless. On top of that, you are given information about the available packages – which gives access to any files that are part of said package. FubuMVC uses this to register content files (scripts, images, styles, etc.) into its asset pipeline.

The most common custom uses of IActivator that I come across are IoC container-related (e.g., register additional implementations, replace a service).

How does this fit into the NuGet world?

This is a very common question. Here’s my typical answer:

Bottles starts where NuGet leaves off. We’re not in the business of defining the shipping process, just what to do with the contents after they’ve been shipped. In fact, we often use NuGet as our shipping provider for reusable packages.

Why Bottles?

Hopefully my short explanation has already answered this question but I’ll try one more time.

Bottles grew out of a need for dynamic content/assembly loading in FubuMVC. Since it was all sparked during a conversation between Jeremy Miller and Dru Sellers, Bottles was abstracted out into what it is today with the intention of making it consumable through TopShelf.

Assembly loading and all the other tedious crap that comes with this need is not something you want to repeat if you can avoid it. Thus, dev cycles were used to make sure that we never have to do this ever again.

What else can Bottles do?

It’s not ready for prime time yet but there is currently a deployment story in the works for Bottles. This can be everything from “deploy this bottle to topshelf” to “deploy this FubuMVC package to IIS/nginx”.