The "Tech. Arch."

Creating Mobile Apps With KnockOutJS, PhoneGap & jQuery Mobile

techarch — Sat, 29 Dec 2012 15:38:57 +0000

Intro

In part 4 we built a complete working version of the Savings Goal Simulator as a rich web app where each view model, view and view mediator is nicely modularized. How could we leverage our browser-side markup and logic to create a mobile app, portable across multiple platforms such as IOS, Android, Windows Mobile? Well, the goal of this post is to present a potential approach. (Of course you can take a peek at the “So What?” section)

The idea behind PhoneGap is to provide a cross-mobile-platform framework allowing a self-contained web app built using HTML5 + CSS3 + Javascript to run inside a full screen web view, while allowing access to the device features such as for example: geolocation, accelerometer, camera, storage, etc..

So PhoneGap will serve as our foundation. For each platform you intend on supporting, you will use the corresponding SDK, code project templates and PhoneGap runtime. Let’s take a look at the 3 most common platforms:

On IOS, the SDK and application consist of:

a CordovaLib libray
an XCode project template
a main module launching a UIApplicationMain
an AppDelegate class launching a ViewController
a ViewController loading the main page (index.html) of your app into a WebView

On Android, the SDK and application consist of:

an Apache Cordova JAR containing the Java implementation of PhoneGap for the Android platform
an Eclipse project template
a DroidGap parent class used for your own Java Droid activity class loading the main page (index.html) of your app.
an assets/www folder containing web resources (.html, .js, .css, images, etc.)

On Windows Mobile Phone, the SDK and application consist of:

a WP7CordovaClassLib library
a XAML application with a phone application page containing a CordovaView
a CordovaView including a browser window hosting the main page (index.html) of your app
a www folder containing web resources (.html, .js, .css, images, etc.)

In summary, for each platform, PhoneGap is used to create a sort of “launcher” application, which starts a “controller“, which in turns loads your main .html web page into a full-screen web view, and exposes underlying platform features through a Javascript API.

So with PhoneGap, we will keep the launcher part of our mobile app fairly small and trivial. Consequently the minimum skills and associated learning curve for each platform we’ll want to target will also be more manageable. The majority of your app components will be based on standard HTML5 + CSS3 + Javascript.

Synopsis

The approach will consist of:

Creating (or leveraging parts of) a minimal web app using HTML and Javascript
Hosting the web app in a PhoneGap “launcher” app (based on the desired mobile platform)
Leveraging jQuery Mobile UI widgets for a consistent look and feel
Theme the app using CSS3 including transitions
Expand the web app functionality while:
- Modularizing pages and views using a templating engine
- Partitioning application logic between view models and view mediators
- Using KnockoutJS for data-binding

Prerequisites

Your starting point may differ based on your current skills and experience:

If you already have a significant development experience on a given platform (e.g. Mac OSX with XCode, or Windows with Visual Studio), then download the SDK for your platform and follow the corresponding Getting Started Guide. You will benefit from a more integrated experience and faster device emulation.

Note for IOS: an Apple Developer License will be required if you want to deploy the app to your device (otherwise you will only be able to use the emulator).
If you have limited overall experience, starting out with the Android platform and the Aptana Studio IDE (a custom version of the Eclipse IDE optimized for HTML5/CSS3 and Javascript development) might be easier as you can run it on any OS (Windows, Mac, Linux). To get started you will need to install the following tools (in order):
Note: I recommend the basic tutorial to create a basic Android app to ensure all the prerequisites are installed correctly. Then you can follow the PhoneGap Getting Started Guide for Android.

In the rest of this tutorial I will assume that your mobile development environment is configured and working, and that you have successfully followed the PhoneGap Getting Started Guide. In the next sections I will use the Android platform as an example.

High-Level Steps

Note: this tutorial builds upon the previous four tutorials and assumes you have built a rich interactive web application using view models, view mediators, and modularized views.

Before we get started, here is a bird’s-eye-view of the steps we will be going through in details in later sections:

Creating the actual app shell using PhoneGap’s Getting Started Guide for the platform you want to start out with.
Test the basic sample shell to make sure everything is working correctly
Customize the assets/www folder structure including all needed JS libraries
Add all needed references for CSS and Javascript files
Define placeholder / container divs for each “logical” jQuery Mobile page
Create separate sets of files for each logical page:
- view markup (.html) based on a templating engine
- view model code (.js)
- view mediator code (.js)
Create a main application Javascript module responsible for
- loading all view markup / templates
- initialize all view mediators (wich in turn initialize their respective view model and data bind the view model to the view)
- trigger the overall rendering of the main page by jQuery Mobile
Create a phone and a tablet version of the main web page (e.g. index.phone.html vs. index.tablet.html
Customize the mobile controller to load the appropriate index page based on device type (phone vs. tablet)
Tailor the look and feel (layout, styling, etc.) for the tablet vs. phone version
Prepare for packaging
Host your app on an “app store”

Building Our App Step-By-Step

Once we are finished the mobile version of the Savings Goal Simulator will look like this:

Let’s download the version of PhoneGap from http://phonegap.com/download and extract the content to a PhoneGap folder (e.g. PhoneGapSDK). We’ll use the content later.

Creating The Android Application Shell

On the Android platform, the application shell takes the form a Java class called an “activity“. It inherits from the android.app.Activity which is the mobile app’s main application “controller“ in the Model-View-Controller sense.

So let’s get started in Aptana Studio and follow the steps from the PhoneGap Getting Started With Android guide:

From Aptana Studio, select File, New Project to start the project creation wizard
Expand the Android folder and select “Android Application Project”
Let’s name the application and Eclipse project “Savings Goal Simulator”
Customize the namespace e.g.: com.yournamespace.savingsgoalsimulator
Select the minimum version of the Android SDK your app should require, e.g. API7: Android 2.1
By default the project folder will be created in the default Eclipse workspace project unless you want to customize the path.
Click Next
Accept the default icon settings for now (you can customize them later) and click Next
Accept the default kind of activity settings and click Next
Accept the default activity settings and click Next – the project will then be created:

At this point we have a basic Android app that you can run in the simulator:

Select Run, then Run,
Select “Android Application” in the Run As dialog, then click Ok
The emulator will boot Android
Then click and drag the lock to the right to unlock the virtual phone, your app will appear:

Let’s take a brief look at what was generated:

Expand the src folder recursively until you can see and double-click on the MainActivity.java file.

package com.yournamespace.savingsgoalsimulator;
import android.os.Bundle;
import android.app.Activity;
import android.view.Menu;  

public class MainActivity extends Activity {

    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
    }   

    @Override
    public boolean onCreateOptionsMenu(Menu menu) {
        getMenuInflater().inflate(R.menu.activity_main, menu);
        return true;
    }
}

}

The MainActivity class inherits from the core Android Activity class
The OnCreate method calls setContentView to create the main view based on the layout provided
Under the res\layout folder, open the activity_main.xml resource
The RelativeLayout includes a TextView for which the text is provided by the string resource named hello_world
Under res\values, open the strings.xml resource and find the definition of hello_world

Once we upgrade our app to PhoneGap, we will no longer use an Android content view nor a layout. Instead we will use a web view loaded with a local web page.

Creating The PhoneGap Application Shell

PhoneGap provides a subclass of Activity called DroidGap which instead of creating an Android content view based on a layout, will create a web view and load the .html page of your choice, which like any page will load stylesheets and scripts, and run the Javascript code. So we’ll make the necessary changes to upgrade the default app to PhoneGap:

Let’s copy the Cordova Java archive (cordova-2.2.0.jar as of this writing) of the lib\android located in our PhoneGapSDK folder we extracted earlier to the libs folder of your project (the folder currently contains a file named android-support-v4.jar). The Cordova JAR will now appear in Aptana Studio under libs.
Now we need to add the Cordova JAR to the Java Build Path. In AptanaStudio, right click on the libs folder, select “Build Path”, then select “Configure Build Path”, select the “Libraries” tab, click on “Add JARs …”, drill down to the libs folder of your project, select the Cordova JAR, and click OK.
The Cordova JAR will also appear under the “Referenced Libraries” folder of your project.
Let’s go to the MainActivity Java class source file. Since we’re no longer going to need the default Android Activity approach, let’s replace the 2 imports related to android.app.Activity and android.view.Menu by a import for the org.apache.cordova.* namespace:
```
package com.yournamespace.savingsgoalsimulator;
import android.os.Bundle;
import org.apache.cordova.*
```
Let’s change the parent class for MainActivity to the new DroidGap class:
```
public class MainActivity extends DroidGap
```
Now we’ll change the implementation of the onCreate method. So let’s replace the line starting with setContentView by the following code which load the content from a local url:
```
@Override
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    super.loadUrl("file:///android_asset/www/index.html");
}
```
Let’s remove the onCreateOptionsMenu method as it is no longer needed.
If we ran the app again, the emulator would tell us that the index.html could not be loaded which makes sense since we have not created it yet!
Note that PhoneGap is looking for the resource in a www folder under a logical androidasset folder. Although it might seem counter-intuitive Android maps the “androidasset” url folder to the physical assets folder! So right click on assets and create the www folder.

Under assets/www, create an index.html web page file with the following basic HTML source:



    
        Cordova
    
    
        Hello World

Re-run the app and the page should now display in the emulator. At this point we just exercized the basic ability for the DroidGap class to load a web page into a web view. We’ll soon add the Cordova Javascript library to the page so we can expose the bi-directional API between the web page and the actual device. But first we need to add the permissions PhoneGap will need to the application. For that, double-click on the AndroidManifest.xml and switch to the XML view. Locate the line starting with the and insert the following lines above it, then save the XML file:

Technically your application may only need a subset of these permissions, but for this tutorial we’ll add them all. Additionally, if you want the application to support orientation changes, add the following attribute before the end of the
android:configChanges="orientation|keyboardHidden|keyboard|screenSize|locale"

The whole opening

To allow our WebView to interact with the PhoneGap / Cordova plugins for the mobile device we need to add configuration information to our res resource folder. So copy the xml folder located in the android folder of the PhoneGapSDK folder to the res folder of our project:

Note: if you forget this step, later the mobile app will show an error message indicating that the Cordova class cannot be found since the WebView will not be able to locate the Cordova plugins.

As in our original Creating Rich Interactive Web Apps With KnockOut.js – Part 2 tutorial, let’s further expand the www folder into subfolders, by creating a scripts subfolder, and below that a vendor subfolder. Now go back to the PhoneGap SDK folder and copy the Cordova Javascript library file (cordova-2.2.0.js as of this writing) to our new assets/www/scripts/vendor folder.

Let’s create a separate application.js shell module under our assets/www/scripts folder. The module will contain the code to initialize our web page but for now, let’s keep it minimal and let’s provide 2 functions: InitializeApplication and OnLoad:

function InitializeApplication() { alert("Application Initialized!"); } function OnLoad() { InitializeApplication(); }

Let’s switch to the index.html page and add our 2 Javascript files to our tag:

Cordova

And for now, let’s add a call to the OnLoad function to the body onload event of the page:

Hello World

Now you should be able to re-run the application and see the alert pop-up.

Note: if you don’t see the alert, verify the scripts and the page. You can also troubleshoot the index.html from your favorite browser debugging tools (e.g. Chrome, Developer Tools). This is always the best technique to troubleshoot your Javascript anyway.

We’re now ready to dig into the application initialization lifecycle! The browser triggered the onload event once the page has been loaded. PhoneGap / Cordova will trigger a different event named deviceready once the bidirectional API between the mobile device and Javascript has been fully initialized. To react to the deviceready event we will need to add an event listener once the onload event has been triggered. So let’s add a new function named OnDeviceReady to our application.js module. We’ll move the call to InitializeApplication from OnLoad to the new function since we actually want to initialize our app once the deviceready event has occurred.

function OnDeviceReady() { InitializeApplication(); }

Now let’s setup the event listener in the OnLoad function:

function OnLoad() { document.addEventListener("deviceready", OnDeviceReady, false); }

This allows us to customize the InitializeApplication to use some of the device information exposed by PhoneGap:

function InitializeApplication() { alert("Welcome to PhoneGap " + device.cordova + " version " + device.version + " for " + device.platform + " on device: " + device.name ); }

Now let’s run the application again and our alert with the device information should appear!

This concludes the creation of the basic PhoneGap application shell. In summary here is what our application does:

Android launches our MainActivity class which inherits from the DroidGap

The onCreate method of DroidGap creates a WebView

The onCreate method of MainActivity sets the url content of the WebView to index.html

Our index.html loads the Cordova library and our application.js

The onload event of the page sets up an event listener for the PhoneGap deviceready event

Once PhoneGap is fully initialized the deviceready event is triggered

Our custom InitializeApplication function is called – at that point the PhoneGap API is fully operational

Applying a jQuery Mobile “Veneer”

Introduction to jQuery Mobile

Since our app is built using HTML and CSS we can create a complete custom look and feel for our app. This is fine if you are creating something truly unique like a game or something very graphical.
But if you are planning on creating an application focused on manipulating data I would recommend following mobile UI conventions. One easy way to ensure a more standardized look that your customers will feel familiar with is to leverage jQuery Mobile. You will benefit from:

a set of common UI elements optimized for a mobile experience

larger buttons and easier to use form controls

toolbars, listviews, collapsible panels, grids

navigation between “logical pages”

cross-platform compatibility helping you create a uniform experience across devices

customizable themes

Here is how jQuery Mobile makes this possible:

jQuery Mobile allows declaration of its custom UI elements by augmenting traditional HTML elements with new attributes. E.g.: a jQM button is created by enhancing the anchor tag with a data-role=”button” attribute (as well as other attributes to add details about how the button should be rendered, such as with an icon positioned above the label):

Add Contact

As the DOM is loaded, jQuery Mobile injects additional needed elements and CSS classes based on the various data-* attributes to produce the desired effect.

I would not be providing a balanced view point if I did not mention the following associated challenges:

Since “logical pages” are defined using div elements enhanced with data-role=”page” attribute which causes the physical .html page to become large and difficult to maintain:

We’ll use external views based on templates and the jQuery View Loader plugin to address this issue.

Defining common elements such as the bottom toolbar for each “logical page” also requires the use of templates if we do not want to duplicate the markup over and over.

Since the markup is automatically enhanced as it is being loaded, dynamically changing elements becomes a bit more complicated since jQuery Mobile needs to be notified to “re-enhance” the new markup fragments. This will become even more apparent when we use a viewmodel to view data-binding library like KnockoutJS. But again there are some solutions.

Overall despite the learning curve and the need to make jQuery Mobile “play nice” with other libraries manipulating the DOM, the benefits strongly outweigh the challenges. This tutorial will provide the necessary guidance to increase your chances of success.

Adding A jQuery Mobile Shell

First, download the full ZIP version of jQueryMobile and extract it out locally.

Before we add the files to our project, let’s create a css folder under assets/www. This will provide a central place for all CSS files needed for our application.

Let’s create a jquery.mobile folder under assets/www/css

Now copy the .css files (only) and the images folder from your extracted jQueryMobile ZIP to assets/www/css/jquery.mobile. Your project structure should now look like this:

And then copy the .js files from your extracted jQueryMobile ZIP to assets/www/scripts/vendor

Since jQuery Mobile builds on top of the jQuery Core, download both the development and production versions of jQuery and copy the corresponding .js files to assets/www/scripts/vendor. Your project structure should now look like this:

Now let’s go back to our index.html page and add the jQuery Mobile stylesheets. We’ll also add a meta tag to provide device information which will be leveraged by jQuery Mobile to optimize rendering for the device.

Let’s include the .js files for jQuery and jQuery Mobile in between the cordova JS and our application.js

And let’s define a minimal jQuery Mobile “logical page“

Savings Goal Simulator

Welcome!

powered by PhoneGap and jQueryMobile

Let’s run the app in the simulator:

jQueryMobile fires an event named mobileinit as soon as it starts executing. Since we may want to override some of the framework defaults (more on that later), let’s add a script with an event handler for mobileinit. Since we want to setup the event handler before jQuery Mobile starts to load, we’ll define the script right before the inclusion of jQuery Mobile.

In the jQuery world, a ready event is triggered on the document once the page has fully loaded. But in jQuery Mobile, since you can have multiple “logical pages”, jQuery Mobile will trigger a pageinit event on a given page once it has been created and initialized. So typically we’ll setup an event handler for pageinit when triggered on the main / “home” logical page. This handler will perform any initialization specific to that page. So let’s add the following script below our “logical page” definition:

Now run the application. What do you notice?
The “page-home is ready!” alert message appears BEFORE the PhoneGap alert message!
Why is that?
Well, jQuery Mobile starts processing the markup as soon as it is created while PhoneGap deviceready event is not triggered until the whole physical page is loaded and until the PhoneGap library is fully initialized.

IMPORTANT: The initialization code for our application will need to be split according to when various initializations are needed. For example:

If we need to fetch data from a remote app, we should trigger the fetch from a [jQuery Mobile] pageinit event

If we need to use data from or related to the device (e.g. local storage), we should retrieve the data from the deviceready [PhoneGap] event

So at this point, we have a minimal PhoneGap + jQuery Mobile application!

Transforming Our Savings Goal Simulator Web App Into A Mobile App

At the end of Creating Rich Interactive Web Apps With KnockoutJS – Part 4 we had a very modular browser-side rich web app. As you will see we’ll be able to adapt the code to “make it fit” with the PhoneGap and jQuery Mobile framework. At a high-level we will need to:

adapt our views to fit mobile device dimensions

enhance our view markup with jQuery Mobile attributes (e.g.: data-role, etc.)

Installing The Web Version Of The Savings Goal Simulator

So let’s first migrate the source of the web version of the Savings Goal Simulator to our mobile project:

Download the source code for the web version of the Savings Goal Simulator from GitHub

Extract and open the download source

Copy the application.css from savings-goal-simulator-master\css\ to the assets\www\css folder of your project

Copy only the subfolders of savings-goal-simulator-master\scripts\ to the assets\www\scripts folder of your project (do not copy the application.js)

Rename the index.html in savings-goal-simulator-master to index.web.html

Copy index.web.html from savings-goal-simulator-master to assets\www

Rename the application.js in savings-goal-simulator-master to application.web.js

Copy application.web.js in savings-goal-simulator-master to assets\www\scripts

So far your project workspace should now reflect the new folders under assets\www\scripts and the new files:

To make troubleshooting easier, let’s make a couple changes so that we can run the web version using index.web.html in a browser. This way we can always compare our mobile version to the web version to help identify and resolve potential issues.

Open index.web.html, look for a reference to application.js and rename it to application.web.js (since we renamed that Javascript file earlier)

Open Google Chrome (or your favorite browser), and open the Developer Tools

Drag index.web.html to the browser

Test the app – it should work fine – you will notice that there is no “styling” since we did not copy the jQuery UI theme (because we will use jQuery Mobile instead)

Now we are ready to adapt our web app into a mobile app.

Rudimentary Migration Of The Savings Goal Simulator Source Code

The idea is to progressively enhance the basic index.html we created in the “Adding A jQuery Mobile Shell” section by incorporating elements of the web version of the app. The modest goal for this section is to be able to bring up the Savings Goal Simulator in the mobile device simulator.

In Creating Rich Interactive Web Apps With KnockoutJS – Part 2, we implemented asynchronous parallel loading of Javascript libraries using LAB.js to speed up the loading process of our web application. We will apply the same technique to our mobile app.

In index.html, let’s load the LAB.js Javascript library after loading application.js and let’s add a script block:

Now let’s replace the script loading for jquery.mobile-1.2.0.js by a call to load the script via LAB.js:

If we try to run our app we will notice that the “page-home is ready!” alert never pops-up and that we see an “$ undefined” error in the console. This is due to the fact that our scripts are being loaded in parallel of our page execution. So the code we had pageinit event handler we had placed below our page definition needs to be synchronized with our LAB.js-based script loading:

Now the application should work correctly in the simulator.

We can proceed and add requests to load all other Javascript libraries we’ll need:

If you run the app in the simulator or the browser you will see in the console that each of the module is being loaded.

Currently the body of our index.html page has a div with a data-role of “content“, let’s replace our “Welcome!” text in the div with the content of body tag from our index.web.html:

Savings Goal Simulator

powered by PhoneGap and jQueryMobile

As a brief reminder, the scripts of type text/html represent definition of jQuery Templates used to render views / panels within the app using data-bind tags. So the data-role=”content” div contains 3 views to track the savings goal, scenarios, and corresponding forecast. If we run the app now the views will not appear as we have not yet ported over the view loading logic.

In the web version, the view loading is done in the InitializeApplication function of application.web.js. Let’s copy the content of application.web.js at the end of application.js and rename the InitializeApplication we just copied to LoadApplicationViews.

Now we need to make the call to LoadApplicationViews before jQuery Mobile gets a chance to run. So let’s insert a wait block before loading it using LAB.js:

If you look at the code for LoadApplicationViews you will notice that it using the jQuery View Loader library to identify and load all templates (scripts of type text/html).
Note: make sure you at least have version 0.3 of jQuery View Loader (to ensure compatibility with jQuery Mobile).

function LoadApplicationViews() { if (typeof(console) != 'undefined' && console) console.info("LoadApplicationViews starting ..."); // Configure the ViewLoader $(document).viewloader({ logLevel: "debug", success: function (successfulResolution) { InitializeViewMediators(); }, error: function (failedResolution) { // Loading failed somehow if (typeof(console) != 'undefined' && console) { console.error("index.html page failed to load"); } } }); if (typeof(console) != 'undefined' && console) console.info("LoadApplicationViews done ..."); }

You should now be able to run the application and see the views appear (in the simulator or browser).

As you can see, even though the app actually works, it is not really usable and we will definitely need adapt the layout and styling of the web app to fit the much smaller screen dimensions of a mobile device.

Adapting The UI For Mobile Use

Overall our goals will be to:

optimize the layout of all panels to ensure you can see all critical elements of the app

make input fields, buttons and controls larger so our fingers can easily work with them

adding sliders where appropriate to allow easy change to numeric values

using collapsible panels to maximize the use of space

So let’s start with the “savings goal” panel first.

In Aptana Studio, expand the assets/www/script/views folder containing all our views, then expand index which contains partial views (with an underscore prefix) for the index.html page, and open the _savings-goal.view.html page:

I would recommend to make a copy of the file and name it _savings-goal.web.view.html and change the reference to the file in index.web.html:

This way we can keep a baseline of what the web version looks like while we customize the mobile version.

Currently, it consists simply of a section with pairs of label + input (or span) tags:

Savings Goal Amount:
Savings Max Duration (In Months):
Savings Target Per Month:

Let’s wrap the first pair of label + input with a div with a data-role=”fieldcontain” so that jQuery Mobile can enhance it to make the field bigger.

Savings Goal Amount:

Let’s repeat the process for the remaining pairs:

Savings Max Duration (In Months):

Savings Target Per Month:

Let’s add a header above all data-role=”field-contain” blocks:

Goal

Savings Goal Amount:

Savings Max Duration (In Months):

Savings Target Per Month:

If you run the app in the simulator you will notice that sometimes the jQuery Mobile “look” appears and sometimes it does not. This is due to timing issues between the web view and jQuery Mobile. To remedy this, we’ll request a jQuery Mobile “refresh” of our page by triggering a create event on our page div. Let’s add that as the final script statement to execute once LAB.js has completed the processing of jquery.mobile-1.2.0.js:

Let’s run the app in the simulator again:

Now the 2 input fields are big enough for a phone but notice the type of keyboard that comes up if you bring focus to the amount field:

This is a text keyboard. What we need is to tell the device to use a numeric keyboard. This is accomplished using new HTML5 attributes: type, min, and max. So let’s add them to the amount input tag:

And let’s test again:

Yippee, we now have a numeric keyboard, and notice that there is a Next button to navigate to the next input field!

Let’s repeat the technique for the max number of months field:

Now we can use the appropriate numeric keypad to enter values, but it is still not very convenient if we want to vary the values and really test their impact. What we need is the jQuery Mobile slider.

In AptanaStudio expand the assets/www/scripts/viewmediator folder and let’s open the sgs.mediator.savings-goal.js module which includes the view mediator responsible for the UI interactions between the view and the viewmodel. Look for the function named sgs.mediator.savingsgoal.setupViewDataBindings and let’s add the following statements to initialize sliders for our input fields:

// Add sliders to our input fields $('#savings-goal-amount').slider(); $("#savings-max-duration").slider();

The whole function should now look like this:

sgs.mediator.savingsgoal.setupViewDataBindings = function(renderedNodes, boundViewModel) { // Declare the HTML element-level data bindings $("#savings-goal-amount") .attr("data-bind","value: savingsGoalAmount"); $("#savings-max-duration") .attr("data-bind","value: savingsMaxDuration"); $("#savings-target-per-month") .attr("data-bind","text: savingsTargetPerMonthFormatted()"); // Ask KnockoutJS to data-bind the view model to the view var viewNode = $('#savings-goal-view')[0]; var viewModel = sgs.mediator.savingsgoal.getViewModel(); ko.applyBindings(viewModel, viewNode); // Initialize default for value models linked to masked fields var pageSettings = GetPageSettings(); viewModel.savingsGoalAmount(pageSettings.defaultSavingsGoal || 0); viewModel.savingsMaxDuration(pageSettings.defaultSavingsMaxDuration || 0); // Add sliders to our input fields $('#savings-goal-amount').slider(); $("#savings-max-duration").slider(); if (typeof(console) != 'undefined' && console) console.info("sgs.mediator.savingsgoal.setupViewDataBindings done!"); }

Now let’s re-run the app, you should see the 2 sliders

And moving the sliders should automatically change the values.

Let’s shorten our labels to save space:

Shorten “Savings Goal Amount:” to just “Amount:”

Shorten “Savings Max Duration (In Months)” to just “Period (In Months):”

Shorten “Savings Target Per Month:” to “Per Month:”

Adapting The Stylesheets For Mobile Use

So far we have only used the default style sheets from jQuery Mobile. Let’s integrate the original application.css from the web version.

In index.html, after the jQuery Mobile stylesheet, let’s include application.css:

To allow the application to adapt to different form factors, we will create different CSS files and direct the browser to use the appropriate stylesheet based on the media directive.

Under assets/www/css, let’s create two new CSS files:

application.phone.css

application.tablet.css

In index.html, after the include for application.css, let’s add two new include statements, each specifying what values the media query should match.

This stylesheet should be used if the maximum device width is 1024px which usually means a tablet.

This stylesheet should be used if the maximum device width is 480px which usually means a phone.

Now let’s tweak our original application.css

Let’s remove the styles details for the section element:

section { }

Let’s remove the standard padding for the h2 element:

section header h2 { margin: 0; }

Let’s remove the styles details for the #savings-goal-view element:

#savings-goal-view { }

Let’s adjust the styles details for the #savings-goal-view label rule:

#savings-goal-view label { display: inline-block; text-align: right; width: 90px; }

Let’s adjust the styles details for the #consumption-scenarios-view rule:

#consumption-scenarios-view { margin: 5px 0; }

Let’s adjust the styles details for the #savings-forecast-view rule:

#savings-forecast-view { margin: 5px 0; }

Let’s adjust a new rule to override the border and padding used in our jQuery Mobile ui-field-contain divs:

.ui-field-contain { border: none; padding: 0; }

Let’s adjust a new rule to override the font used in our jQuery Mobile labels:

.ui-field-contain label { font-size: 10px; margin: 2px 2px; }

Let’s adjust a new rule to override the width used in our jQuery Mobile sliders:

div.ui-slider { width: 30%; }

Let’s create an override rule for the collapsible panels:

.ui-collapsible-inset .ui-collapsible-content { border-color: black; border-style: solid; border-width: 1px; }

Let’s run the app in the browser and simulator to see our new styling:

At this point we could continue adapting the look of the Savings Goal panel, by adjusting the CSS styles to make it fit a little bit more tightly. The easiest way to do that is to use your trusted browser developer tool to learn what styles are being used by jQuery Mobile and to experiment.

I will leave this as an exercise for the reader.

Adapting The Consumption Scenarios View For Mobile Use

In the web version of the application, the different type of coffee consumption options consists or set of radio buttons layed out in a table. But at minimum for a phone version of the app we need to conserve the vertical space so we can see the goals, a subset of the consumption options, and the savings forecast.

So let’s use collapsible panels for each type of consumption option such as “type” (of beverage), size, and frequency. This way as a user you can expand the option you want to play with, tweak the current and proposed settings, see the impact on the forecast, and repeat the process.

First, let’s make a copy of the _consumption-scenarios.view.html file under assets/www/scripts/view/index and rename the copy to _consumption-scenarios.web.view.html and change the reference to the file in index.web.html:

Again we now have a baseline of the original web version.

Now open the _consumption-scenarios.view.html file in Aptana Studio. Locate the header tag, and let’s wrap the “Weekly Coffee Consumption” title in an h2 tag:

Weekly Coffee Consumption

Right below the header but before the table, let’s add a div of [jQuery Mobile] data-role “collapsible-set” indicating that contained elements of data-role “collapsible” can be grouped together.

Let’s add a div of data-role “collapsible” for our consumption type option. The div will contain a h3 for the panel title, followed by a table element to hold the details of our option

Consumption Type

Current Habits Proposed Change

Now we can move the markup related to the drink types from the original table over to the second row of our new table within the collapsible div:

Consumption Type

Current Habits Proposed Change

Regular
Latte
Espresso

Regular
Latte
Espresso

Let’s remove all the
tags since we no longer need them since jQuery Mobile is enhancing our DOM and styling new elements.

Let’s run in the browser and the simulator.

You will notice a couple things:

The collapsible element does expand and collapse when we toggle it

jQuery Mobile has rendered our radio buttons as regular buttons. Apparently jQuery Mobile require a radio button group to be codified as a fieldset with a data-role of “controlgroup“.
So let’s replace our div for the current-drink-type:

by a fieldset – note that we’ll request a “mini” version (using data-mini=”true”) to minimize the vertical space taken by the resulting jQuery Mobile radio button group:

Let’s re-run:

Now let’s repeat the process for the other 2 types of consumption options (Size and Frequency):

Add a div of data-role “collapsible” for our consumption option. The div will contain a h3 for the panel title, followed by a table element to hold the details of our option.

Move the markup related to the consumption option from the original table over to the second row of our new table within the collapsible div

Change the div containing the radio buttons into a fieldset of data-role “radiobuttongroup”

For the frequency collapsible panel, the “Other:” option has an input field associated with it. So we will need to wrap the input field with a div of data-role “field-contain”, and add HTML5 type, min and max attributes:

To allow the input field to be positioned to the right of the radio button, we will need to move the markup for data-role “fieldcontain” inside the label tag of the radio button like so:

Other:

If you run in the browser or simulator, you will notice that the input field is not positioned where we would like it. So let’s add a CSS class on the div data-role “fieldcontain” named “other-input“:

And let’s define the new class in application.css:

.other-input { display: inline-block; left: -20px; margin: 0 0 5px 0; top: -10px; width: 30px; } .other-input input { height: 24px; }

Let’s re-run:

Now the positioning is much better!

For the number of drinks per day, let’s create a separate collapsible panel like so:

Drinks Per Day

Current Habits Proposed Change

Let’s re-run:

Now we need to cleanup the bottom remaining table in _consumption-scenarios.view.html.
Let’s give the table an id of consumption-summary-table:

Let’s cleanup the obsolete table header and let’s reuse it for our weekly summary.

Weekly Summary Current Habits Proposed Change

And remove the obsolete column titles:

Type: Size: Frequency:

Let’s define styling for consumption-summary-table in application.css:

#consumption-summary-table { border-radius: 8px; background-color: white; width: 100%; } #consumption-summary-table th { border-bottom: 1px solid Grey; }

Let’s re-run:

You will notice that we’re pretty close to our goal of optimizing for the vertical height of a phone!

Adapting The Savings Forecast View For Mobile Use

First, let’s make a copy of the _savings-forecast.view.html file under assets/www/scripts/view/index and rename the copy to _savings-forecast.web.view.html and change the reference to the file in index.web.html:

Again we now have a baseline of the original web version.

Now open the _savings-forecast.view.html file in Aptana Studio. To maximize vertical space, let’s turn the current markup into a horizontal table where the labels become column headers. We’ll also shorten the column headers and the unit of measure in each data cell:

Forecast Variance Months

/m /m m

Let’s define styles for our new table in application.css:

#savings-forecast-table { width: 100%; } #savings-forecast-table tr td { text-align: center; } #savings-forecast-view input { width: 30px; }

Run the app:

Ideally we would like the forecast panel to be visible at all times. An idea is to integrate it in the footer of the page and “pin” the footer at the bottom of the screen.
So open the index.html page, and let’s move the script include for the savings-forecast-view-template and the actual savings-forecast-view-container div into the footer:

To “pin” the header, let’s add a data-position=”fixed” and data-fullscreen=”true” as attributes on the footer. And while were at it let’s specify a different jQuery Mobile theme for the footer using data-theme=”e”.

Let’s refresh:

This is much nicer!

More Visual Tweaks

In the index.html, let’s customize the jQuery Mobile theme to be used on all its widgets

Let’s increase the horizontal padding for all section elements:

section { padding: 0px 2px; }

Let’s tweak the height of the #page-home div and its data-role=”content” div:

#page-home { height: 100%; overflow: hidden; } #page-home div.ui-content { height: 88%; }

Let’s move the “Per Month” elements from the bottom of the savings goal panel to the section header:

Goal

Per Month:

And let’s add the following styles to application.css:

#savings-goal-view header h2 { display: inline-block; } #target-per-month { display: inline-block; right: -114px; } #savings-goal-view #target-per-month label { min-width: 30px; } #savings-goal-view #savings-target-per-month { font-size: 0.8em; }

Let’s remove the word “Consumption” from our collapsible panels.

Let’s re-run:

The look is now a bit more “professional”, the visual elements stand out and the vertical positioning is optimized.

UI “Feel” / Behavior Tweaks

Originally the web app depended on jQuery UI, but since we’re usin jQuery Mobile instead, we will need to tweak the mediators associated with our panels.

Two view mediators use the jQuery UI highlight effect to provide a visual indication of key changes. But now that we have sliders, the effect would take too long since it would be triggered on each mouse move. So let’s remove the effect.

Open sgs.mediator.savings-goal.js under assets\www\scripts\viewmediator and look for a call to the effect function:

viewModel.savingsTargetPerMonthFormatted.subscribe(function() { $("#savings-target-per-month") .effect('highlight', { color: 'LightGreen' }, 3000); // for 3 seconds });

and let’s remove the overall statement altogether:

viewModel.savingsTargetPerMonthFormatted.subscribe(function() { // Placeholder for future use });

Open sgs.mediator.consumption-scenarios.js and repeat the process:

viewModel.savingsPerWeekFormatted.subscribe(function() { // Placeholder for future use });

So if you had been noticing exceptions for the effect call in the browser console, now these are a thing of the past.

Adding An Other jQuery Mobile Page

Currently our application has only one jQuery Mobile “logical page“, that is, a div with a data-role=”page”. It would be nice if we could have another page to edit the coffee beverage list prices! jQuery Mobile allow the definition of multiple pages and provide associated navigation mechanisms. So let’s see how to do that.

First, in the index.html, before the end of the body tag, let’s add the shell for our new page:

Shell for our price list!

We need a button to navigate to the new page. Let’s edit _consumption-scenarios.view.html and add a button (div with data-role=”button”) in the header, after the h2 title:

Weekly Coffee Consumption
Pricing

You will notice that we specified a data-rel attribute with a value of “dialog“. This tells jQuery Mobile that we would like a pop-up transition effect and a dialog theme: dark background, rounded corners, etc.. See the Dialog documentation for more details.

If you run the app in the simulator, you should see the new Pricing button:

And clicking on it will cause the navigation to the new page to occur:

If you hit the back button, the page-home page will be displayed again (without any of our values to be lost – since the pages are just hidden/shown during the navigation process).

Like for other panels, let’s externalize the markup for our new pricing page. So let’s create a new markup folder (one for each page) under assets/www/scripts/views/named “pricing“, and then create a file named index.view.html, an cut/paste our shell message inside the following template:

Edit Pricing

Shell for our price list!

To render the externalized view we have to:

include a text/html template script reference in the main index.html file

create a container div data-bound to the template

ask KnockoutJS to render it.

So remove the “Shell for our price list!” content from the coffee-pricing-dialog div and replace it with:

This allows the inclusion of our new jQuery template in the app.
And right below let’s add our div container:

Note: the afterRender callback references a setupViewDataBindings function we have not yet created in the sgs.mediator.coffeepricing module. So if you run the app now, the content of the view will not be rendered.

Open up the sgs.mediator.coffeepricing.js module under assets/www/scripts/viewmediator and let’s create a shell for the setupViewDataBindings function:

sgs.mediator.coffeepricing.setupViewDataBindings = function(renderedNodes, boundViewModel) { }

Then let’s update the createViewMediator function to request data binding of the coffee pricing view container with the template. This will cause KnockoutJS to render the template using jQuery Template:

sgs.mediator.coffeepricing.createViewMediator = function (pageSettings) { // Create the view Pricing Editor view-specific view model var viewModel = sgs.model.coffeepricing.initializeViewModel(pageSettings); // Save the view model sgs.mediator.coffeepricing.setViewModel(viewModel); // Ask KnockoutJS to data-bind the view model to the view var viewNode = $('#coffee-pricing-view-container')[0]; var viewModel = sgs.mediator.coffeepricing.getViewModel(); ko.applyBindings(viewModel, viewNode); if (typeof(console) != 'undefined' && console) console.info("sgs.mediator.coffeepricing ready!"); }

Now we can expand the code for setupViewDataBindings to data-bind the coffee pricing view div with our KnockoutJS coffee pricing view model:

sgs.mediator.coffeepricing.setupViewDataBindings = function(renderedNodes, boundViewModel) { // Apply the bindings var viewNode = $('#coffee-pricing-view')[0]; var viewModel = sgs.mediator.coffeepricing.getViewModel(); ko.applyBindings(viewModel, viewNode); // Get jQuery Mobile to refresh/enhance the page $('#coffee-pricing-dialog').trigger('create'); }

Now if run the app and click on the pricing button we should see our new pricing shell page:

Let’s add some input fields to our pricing/index.view.html view to capture the pricing data:

Edit Pricing

Regular Coffee

Tall:

Grande:

Venti:

You can repeat the process for the beverages like caffe latte and espresso.

If you run the app you will see an empty dialog since we have not created a value models for each of the pricing options in the pricing view model, nor added the data binding for the various fields yet.

If we look at the current definition of our coffee pricing view model, we’ll see that it includes only one value model: “pricing“:

sgs.model.coffeepricing.initializeViewModel = function (pageSettings) { // ... // Lazy-initialize the price list var priceList = sgs.model.coffeepricing.getPriceList(); var viewModel = { pricing: ko.observable(priceList) } // ... return viewModel; }

If we evaluate / inspect the both the view model and the pricing value model in the browser tools console we’ll see:

But so the coffee pricing view model does not have a separate value model for each property of the pricing value model. We have two options: a) declare a value model for each property, or b) leverage the dynamic nature of Javascript to dynamically declare a new value model for each property of our pricing object. Let’s choose the latter approach.
Let’s add a new function named publishPriceList to our sgs.model.coffeepricing module.

sgs.model.coffeepricing.publishPriceList = function (viewModel) { var priceList = viewModel.pricing(); // Find all property names for the pricing object var productKeys = Object.keys(priceList); // Process all properties for ( var i = 0; i < productKeys.length; i++) { // Get product details var productKey = productKeys[i]; var productPrice = priceList[productKey]; // Create an observable name based on the property var observableName = 'pricing' + productKey.replace('-',''); // Check if we already have value model (observable) with the same name var valueModel = viewModel[observableName]; if (typeof(valueModel) == 'undefined') { // Dynamically create a value model valueModel = ko.observable(null); // Add it to the overall view model viewModel[observableName] = valueModel; } // Update the value model's actual pricing valueModel(productPrice); } }

You can test it in the browser console by evaluating:

sgs.model.coffeepricing.publishPriceList(sgs.mediator.coffeepricing.getViewModel())

You now see the new value models!
So let’s add a call to the publishPriceList function from initializeViewModel:

sgs.model.coffeepricing.initializeViewModel = function (pageSettings) { // .. var priceList = sgs.model.coffeepricing.getPriceList(); var viewModel = { pricing: ko.observable(priceList) } // Publish the pricing data as individual value models sgs.model.coffeepricing.publishPriceList(viewModel); // ... return viewModel; }

This way the new value models will be created upon initialization of the view model.

Now we can add the corresponding data bindings in the setupViewDataBindings function of the sgs.mediator.coffee-pricing.js module:

sgs.mediator.coffeepricing.setupViewDataBindings = function(renderedNodes, boundViewModel) { // Ask KnockoutJS to data-bind the view model to the view $("#pricing-regular-tall").attr("data-bind","value: pricingRegularTall"); $("#pricing-regular-grande").attr("data-bind","value: pricingRegularGrande"); $("#pricing-regular-venti").attr("data-bind","value: pricingRegularVenti"); // Apply the bindings var viewNode = $('#coffee-pricing-view')[0]; var viewModel = sgs.mediator.coffeepricing.getViewModel(); ko.applyBindings(viewModel, viewNode); // Get jQuery Mobile to refresh/enhance the page $('#coffee-pricing-dialog').trigger('create'); }

If we re-run the app we now see the pricing details:

And if you update a price, close the dialog, then reopen it the new pricing is still there. But you might notice that the calculations are not reflecting the price update. And if you closed and terminated the mobile app and relaunched it your new price would be lost.

What we need is to add logic to save the new pricing data once we’re done with our updates on the pricing dialog. First, let’s add a save button to the pricing/index.view.html view:

Save Pricing

Let’s add a click event handler for our new button in the setupViewDataBindings function of the sgs.mediator.coffee-pricing.js module.

sgs.mediator.coffeepricing.setupViewDataBindings = function(renderedNodes, boundViewModel) { // ... // Get jQuery Mobile to refresh/enhance the page $('#coffee-pricing-dialog').trigger('create'); // Add a click handler of the Save Pricing button $('#save-pricing-button') .die('click') .bind('click',sgs.mediator.coffeepricing.savePriceList); }

Le’s define the sgs.mediator.coffeepricing.savePriceList and make it call savePriceList in sgs.model.coffee-pricing.js module:

sgs.mediator.coffeepricing.savePriceList = function() { sgs.model.coffeepricing.savePriceList(); }

We just need to implement the new savePriceList function in the sgs.model.coffee-pricing.js module. For now let’s create a shell:

sgs.model.coffeepricing.savePriceList = function () { }

The requirements for the savePriceList are to:

Apply the current data of the individual price value models back to the master pricing value model

Save our pricing value model data to local storage using the jStorage library

Here is the code:

sgs.model.coffeepricing.savePriceList = function () { var viewModel = sgs.mediator.coffeepricing.getViewModel(); var priceList = viewModel.pricing(); // Find all property names for the pricing object var productKeys = Object.keys(priceList); // Process all properties for ( var i = 0; i < productKeys.length; i++) { // Get product details var productKey = productKeys[i]; // Find the corresponding observable var observableName = 'pricing' + productKey.replace('-',''); var valueModel = viewModel[observableName]; // Update the value model var productPrice = parseFloat(valueModel()); priceList[productKey] = productPrice; } // Store the updated pricing in local storage $.jStorage.set("coffee-price-list", priceList); }

If you re-run the app, you now should be able to see the impact of updating the pricing of a regular tall coffee from 1.4 to 1.5. And if you restart the app you should see that your pricing data had been saved and restored.
In the browser developer toolls, you should be able to inspect the local storage and confirm that your can see your pricing data:

At this point you have a well-rounded mobile version of the Savings Goal Simulator!

Note: as an exercise for the reader, go ahead and externalize the content of the #page-home as a separate template named index.view.html in the assets/www/views/index folder. This will keep the overall index.html main page as small as possible.

Phone And Table Versions Of The App

Currently we have an index.html which is primarily designed to fit on a phone. And although it will take the full size of the display on a tablet, the application will still work fine. But what if we want to offer a more optimized design for a tablet such as for example do away with collapsible sections, or change the layout of the app?

Well, this is where the modularity of our views and application, plus the use of HTML and CSS will pay off.

Two approaches can be considered based on your design need:

Have a separate main web page for the phone and for the tablet version and launch the appropriate page based on the device display size.

Keep a single web page, but just custom CSS stylesheets to tweak the layout as needed

The first option provide the most flexibility, so let’s look at how to implement it.

Let’s look back at the code we used in the “controller” or “launcher” (implemented as Java Activity on the Android platform):

package com.yournamespace.savingsgoalsimulator; import android.os.Bundle; import org.apache.cordova.*; public class MainActivity extends DroidGap { @Override public void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); super.loadUrl("file:///android_asset/www/index.html"); } }

At a high-level, we need to:

Rename our index.html to index.phone.html

Clone our index.phone.html into a new index.tablet.html

Change the onCreate method to detect the device size and load index.phone.html or index.tablet.html

Here is an implementation for onCreate based on a check for the width of the device:

@Override public void onCreate(Bundle savedInstanceState) { protected float TABLET_WIDTH = 768; super.onCreate(savedInstanceState); // Get actual screen size so we can determine if the device is a tablet or not Display display = ((WindowManager) getSystemService(Context.WINDOW_SERVICE)).getDefaultDisplay(); int width = display.getWidth(); int height = display.getHeight(); // Is the width is at least the minimum width of a tablet? boolean isTablet = (width >= TABLET_WIDTH); Log.v("Device size detection", "width=" + width + " height=" + height + " isTablet=" + isTablet ); // Determine the name of the corresponding main page String deviceType = isTablet ? "tablet" : "phone"; String pageUrl = "file:///android_asset/www/index." + deviceType + ".html"; super.loadUrl(pageUrl); }

Now you can customize the index.tablet.html page to your liking, such as for example:

Adding new functionality

Adding new jQuery Mobile logical pages

Adding new template views

Splitting existing views into separate phone and tablet versions

Note: we had already included a media query and conditional inclusion of device-specific CSS (see the “Adapting The Stylesheets For Mobile Use” section details) in our main html page. So now you can expand the customization to suit the appropriate device.

Prepare For Packaging

Since packaging is different for each device OS platform, I would recommend consulting the corresponding platform documentation. But the following items for consideration apply to all platforms:

Creating the application icon in several resolutions

Creating the initial screen image which is displayed while the app is loading or being re-activated

Applying code signing certificates

Hosting The Application Package On An “AppStore”

Of course, if your mobile application is for public consumption (for free or for sale) then the hosting guidelines of your platform apply (e.g. Apple AppStore, Google Play, Microsoft Windows Phone App Store).

But if your mobile application is for enterprise consumption, provided that you are enrolled in an enterprise program (e.g. iOS Developer Enterprise Program), you can create your own “custom app store” as a web application, require user authentication and authorization, tailor the app catalog based on user privileges. In that situation, each app has a link to either the package (for Android) or an application descriptor (for iOS – .plist file) which contains the location of your application package (e.g. Android .apk file, iOS .ipa file). Clicking on the link triggers an “Over The Air” installation of the application once you have approved the process.

This section was meant to just give you a sense of the possibilities, but you will need to refer the corresponding platform documentation for details.

5. Recap

Even though we touched on all the basic minimum aspects of a PhoneGap + jQuery Mobile app, in some ways we barely scratched the surface. For example, we did not cover the following topics:

leveraging device capabilities such as media, geolocation, etc. – but you easily lookup the corresponding details in the PhoneGap documentation

using PhoneGap plugins such as the mobile notifications

dynamically altering jQuery Mobile-enhanced HTML controls – in a nutshell you would create custom bindingHandlers for KnockoutJS

interfacing with web services (via AJAX)

These more advanced topics will be the subject of a separate tutorial.

Here is a quick recap of the steps we followed:

#
To Do
Area

1

Create a PhoneGap project for your mobile platform

Create a www folder structure under /assets for all types of resources:

www/css

www/css/jquery.mobile

www/scripts

www/scripts/vendor

www/scripts/view

www/scripts/viewmediator

www/scripts/viewmodel

Add external JS libraries including Cordova, jQuery, jQuery Mobile, etc. under www/scripts/vendor

Add the jQuery Mobile stylesheets and theme content under www/css/jquery.mobile

Create a shell page for each type of device:

index.phone.html

index.tablet.html

Customize the application controller (Activity in Android, AppDelegate in iOS) logic to detect the device display dimensions and launch the phone or tablet version of the index page

Under www/scripts, create an application.js module with the following function placeholders:

InitializeApplication

InitializeViewMediators

LoadApplicationViews

OnLoad

OnDeviceReady

Wire-up the onload event on the body tag of both index pages to the OnLoad function

Application

2

Customize the application style sheets under www/css

application.css

application.phone.css

application.tablet.css

Starting with the index.phone.html:

include core JS libraries,

add logic to asynchronously load other libraries via LAB.js

add a call to LoadApplicationViews (from application.js) once LAB.js has completed all loading

include stylesheets

Customize the LoadApplicationViews (from application.js) to use the jQuery View Loader to load all views and call InitializeViewMediators once done

View

3
For each “logical page” in the app:

Create a folder under www/scripts/view to group all markup templates for that page

Create an index.view.html for the page in the new folder

Add a div with data-role=’page’ in the body of both index.phone.html and index.tablet.html

Inside the new div, add a script tag referencing the index.view.html template from the page folder

Inside the new div, add a container div with data-bind=’template: { … }’ binding the div with the template

Create templates for any sub-panels of the page with the naming convention: _{panel-name}.view.html

View

4
For each view model you need (e.g one global plus one per logical page):

Create a Javascript module under www/scripts/viewmodel

Customize the namespace

Define a function named initializeViewModel to instantiate and return a view model and define value models (observables) and dependent observable functions

View Model

4
For each view mediator you need (e.g one per logical page):

Create a Javascript module under www/scripts/viewmediator

Customize the namespace

Define a function named createViewMediator to:

request a corresponding view model

save off the view model

bind the corresponding container div with its template

Define a function named setupViewDataBindings to bind each element of the page/view with their corresponding value model

If you need custom pre page rendering logic, create a function and wire it up to the pageinit event in the LAB.js post-loading code section

View Mediator

4
Customize the application initialization:

Update InitializeApplication with any custom initialization logic based on device data or features

Application

4
Update the InitializeViewMediators function of the www/scripts/application.js for each “logical page”:

Add a call to the createViewMediator of each mediator

Application

So What?

The “PhoneGap + jQuery Mobile + jQuery ViewLoader + Knockout JS” stack allows you to create portable mobile apps by leveraging your existing HTML5 and Javascript skills, while minimizing your need to master all the details of each platform.

This is a big deal because you can:

achieve a much greater portable code base (the platform-specific code base will be small)

get started quickly

use your favorite IDE

style your mobile app using CSS3 (including transitions and effects)

adopt the look of the base platform “automagically” (via jQuery Mobile rendering)

debug a great portion of the app using standard browser tools (e.g.: Google Chrome, Firefox + Firebug, …)

target one platform initially then expand to other ones over time

So if you have solid web skills it is time for you to apply them towards the creation of mobile apps!

References And Resources

PhoneGap Platform

PhoneGap / Apache Cordova mobile framework : http://www.phonegap.com/

PhoneGap Getting Started Guides : http://docs.phonegap.com/en/2.2.0/guidegetting-startedindex.md.html

PhoneGap Documentation : http://docs.phonegap.com/en/2.2.0/index.html

Android Platform

Android SDK : http://developer.android.com/sdk/installing/index.html

Aptana Studio 3 : http://www.aptana.com/products/studio3

Android Development Tools (ADT) plugin for Eclipse / Aptana Studio : http://developer.android.com/sdk/installing/installing-adt.html

Javascript Frameworks

jQuery Mobile : http://jquerymobile.com/

jQuery Mobile Documentation : http://jquerymobile.com/demos/

jQuery Template : http://api.jquery.com/category/plugins/templates/

jQuery ViewLoader : http://github.com/techarch/jquery-viewloader

jQuery ViewLoader rendering engine : https://github.com/techarch/jquery-viewloader

Knockout JS Model-View-ViewModel framework : http://knockoutjs.com/

Knock Me Out – Ryan Niemeyer’s blog : http://www.knockmeout.net/

LAB.js Parallel and Asynchronous Javascript Loader : http://labjs.com/

Miscellaneous

KnockoutJS afterRender : http://knockoutjs.com/documentation/template-binding.html#note4usingthe_option

Another Look at Custom Bindings for KnockoutJS : http://www.knockmeout.net/2011/07/another-look-at-custom-bindings-for.html

Example of KnockoutJS custom bindings for jQuery Mobile

Savings Goal Simulator : http://savings-goal-simulator.heroku.com/

Patterns

Model-View-Controller pattern : http://c2.com/cgi/wiki?ModelViewController

Controller pattern : http://c2.com/cgi/wiki?ApplicationController

Other Tutorials In The Same Series

Creating Rich Interactive Web Apps With KnockoutJS – Part 1 : Introduction to KnockoutJS

Creating Rich Interactive Web Apps With KnockoutJS – Part 2 : Using view models and view mediators

Creating Rich Interactive Web Apps With KnockoutJS – Part 3 : Modularizing view models and view mediators

Creating Rich Interactive Web Apps With KnockoutJS – Part 4 : Modularizing and extracting view components

Savings Goal Simulator

Web Savings Goal Simulator Source Code

Download the Mobile App:

If you enjoyed this post, I would love it if you could check out mySkillsMap, my skills management app.

Current Habits	Proposed Change
Regular Latte Espresso	Regular Latte Espresso

Forecast	Variance	Months
/m	/m	m

#	To Do	Area
1	Create a PhoneGap project for your mobile platform Create a www folder structure under /assets for all types of resources: www/css www/css/jquery.mobile www/scripts www/scripts/vendor www/scripts/view www/scripts/viewmediator www/scripts/viewmodel Add external JS libraries including Cordova, jQuery, jQuery Mobile, etc. under www/scripts/vendor Add the jQuery Mobile stylesheets and theme content under www/css/jquery.mobile Create a shell page for each type of device: index.phone.html index.tablet.html Customize the application controller (Activity in Android, AppDelegate in iOS) logic to detect the device display dimensions and launch the phone or tablet version of the index page Under www/scripts, create an application.js module with the following function placeholders: InitializeApplication InitializeViewMediators LoadApplicationViews OnLoad OnDeviceReady Wire-up the onload event on the body tag of both index pages to the OnLoad function	Application
2	Customize the application style sheets under www/css application.css application.phone.css application.tablet.css Starting with the index.phone.html: include core JS libraries, add logic to asynchronously load other libraries via LAB.js add a call to LoadApplicationViews (from application.js) once LAB.js has completed all loading include stylesheets Customize the LoadApplicationViews (from application.js) to use the jQuery View Loader to load all views and call InitializeViewMediators once done	View
3	For each “logical page” in the app: Create a folder under www/scripts/view to group all markup templates for that page Create an index.view.html for the page in the new folder Add a div with data-role=’page’ in the body of both index.phone.html and index.tablet.html Inside the new div, add a script tag referencing the index.view.html template from the page folder Inside the new div, add a container div with data-bind=’template: { … }’ binding the div with the template Create templates for any sub-panels of the page with the naming convention: _{panel-name}.view.html	View
4	For each view model you need (e.g one global plus one per logical page): Create a Javascript module under www/scripts/viewmodel Customize the namespace Define a function named initializeViewModel to instantiate and return a view model and define value models (observables) and dependent observable functions	View Model
4	For each view mediator you need (e.g one per logical page): Create a Javascript module under www/scripts/viewmediator Customize the namespace Define a function named createViewMediator to: request a corresponding view model save off the view model bind the corresponding container div with its template Define a function named setupViewDataBindings to bind each element of the page/view with their corresponding value model If you need custom pre page rendering logic, create a function and wire it up to the pageinit event in the LAB.js post-loading code section	View Mediator
4	Customize the application initialization: Update InitializeApplication with any custom initialization logic based on device data or features	Application
4	Update the InitializeViewMediators function of the www/scripts/application.js for each “logical page”: Add a call to the createViewMediator of each mediator	Application

Creating Rich Interactive Web Apps With KnockOut.js – Part 4

techarch — Tue, 03 Jan 2012 04:30:00 +0000

Intro

In part 3 we built a complete working version of the Savings Goal Simulator where each view model and view mediator is nicely separated in its own module and corresponding source file. But what about the view? Well the goal of part 4 is to modularize and extract each view component.

Synopsis Of The Approach

The approach will need to meet the following requirements:

The view markup needs to have its own url and be cacheable

The view markup needs an ID

The view should have an HTML element

The view HTML element should be renderable

View Markup With A URL

Just like script blocks and images can be “sourced” externally from any url, we need a similar mechanism for our views.

So since the script tag allow us to do that already, let’s use it, assign an id, but let’s use a more appropriate type like text/html.

View Markup With An ID

To make it possible to reference the “script-view-markup” later on in our page or Javascript code, we’ll just assign the script an ID like so:

View HTML Element

Now that we have a way to define how a view markup can be “included” in our page, we’ll just define our view “container” as a normal HTML element. We can use a “div” or any of the more semantically significant HTML5 elements like “section“:

What we’re missing is a mechanism to:

associate the view element and the view markup together

render the actual view

optionally: data-bind any view model to the view

Renderable View

To render the markup for a given view we need a view rendering engine. As of this writing, the most prevalent option is jQuery Template.

Note: The jQuery Template implementation is rock solid and in use in many production web sites and internal applications. However the jQuery UI core team is in the process of deprecating its use and eventually replace it with another implementation. A serious contender for this is the jsRender + jsViews library. Other options also include Mustache and Handlebars. Although this tutorial is leveraging jQuery Template as its platform, I recommend you perform some additional due diligence once you’re ready to settle on library.

KnockoutJS goes one step further by integrating the view rendering engine with data-binding capabilities.

Note: KnockoutJS will allow pluggable view rendering engines over time, making it possible to use the one you choose (as long a as a plugin exists).

So KnockoutJS can take a view element with a corresponding “view template” and a view model, and render the resulting view.

Since we introduced the notion of “view template“, let’s spend some time getting familiar with the concept before proceeding with externalized views.

Introduction To Templating

Simple String-Based Templates

An string-based template is just a string containing text plus placeholders for variables. A placeholder is the name of the variable surrounded by curly braces and a prefixed by a dollar sign. So for example a template to display a time variable would look like:

var viewTemplate = "${firstName}, the time is now ${time}"

We can group our “variables” in a Javascript object literal like so:

var viewData = { firstName: 'Chris', time: (new Date()).toLocaleTimeString() }

We can get the engine to bind the template and the data like so:

var viewContent = $.tmpl(viewTemplate, viewData);

Finally assuming a div with the id ‘my-view’, jQuery can render the view content like so:

$('#my-view').html(viewContent);

In summary here is a diagram showing the relationships between the various components used in templating:

To try this out yourself:

Create a web page named index.html

Add script references to both jQuery and jQuery Template using their content distribution network urls:

http://ajax.googleapis.com/ajax/libs/jquery/1.7.0/jquery.min.js

http://ajax.aspnetcdn.com/ajax/jquery.templates/beta1/jquery.tmpl.min.js

Add a div with the id ‘my-view’ in the body of the page

Add a Javascript script block with a jQuery ready function with our template rendering code:

You should be able to open the index.html web page in a browser and the div should now contain the rendered text with the first name and the current time.

Now we have an idea of how templating using jQuery Template is working. But in this example we are just using a string to hold our template. The library actually has a feature where you can store the template in a script tag on the same page.

Simple Inline Templates

The jQuery Template library also allow us to store the template in a script tag with a text/html type like so:

The template can then be rendered with a slightly different form of the tmpl API:

var viewContent = $('#my-view-template').tmpl(viewData);

Having the template moved out of the code is a step in the right direction, but what we need is the ability to externalize the template to an external url. We’ll tackle that subject soon I promise, but in the meantime let’s look at what KnockoutJS brings us in terms of additional templating power.

KnockoutJS Databinding Support For Inline Templates

Up to now, we have had to write the actual code to: a) render the template, and then b) insert the resulting text in an HTML element. Well, let’s see what KnockoutJS can do to simplify our task. (This will be very handy especially when your main page has many views.)

As you know, KnockoutJS provides a “data-bind” attribute where you can specify the visual or behavioral aspects (e.g. value, text, visible, enable, …) to link to a value model or dependent observable function. When we want to data-bind an HTML element to both a template and a view model, we’ll use the following syntax:

It is even possible to specify a Javascript function in an afterRender template parameter. That function will the be invoked once the HTML element has been rendered. This can be useful if you need to dynamically attach new behaviors or event handlers to the produced content. For example, you could invoke jQuery UI component configuration APIs such as applying icons for a jQuery UI button.

Our view model would then be re-written as follows:

var myViewModel = { firstName: ko.observable('Chris'), time: ko.observable((new Date()).toLocaleTimeString()) }

And our “myViewHookup” after-render function would have the following form:

function myViewHookup(renderedElements, viewModel) { // E.g. highlight the new content for 3 seconds renderedElements.effect('highlight', { color: 'LightGreen' }, 3000); }

And finally our page initialization code would ask KnockoutJS to apply the data bindings using the ko.applyBindings API:

$(document).ready(function () { var myViewModel = { firstName: ko.observable('Chris'), time: ko.observable((new Date()).toLocaleTimeString()) } ko.applyBindings(viewModel); });

So when using jQuery, jQuery Template, and KnockoutJS, we can define a template-based view and data-bind it to a view model so it can be rendered dynamically.

Now we have covered all but one requirement: the ability to externalize the view template to a specific url.

Externalized View Templates

Basic Mechanism Needed To Externalize A Template

Let’s review our simple “template script markup”:

What we really need at this point is a way to externalize this template into its own file (maybe in a sub-folder named after the parent page, itself organized under a “view” folder):

/view/mypage/my.view.html

${firstName}, the time is now ${time}

We would then just add a src tag to our script block:

If you try this out you will notice that the browser will indeed [wget] “fetch” the content of _my.view.html, and using the web developer tool of your browser you will actually see the template markup.

But if you try to access the content of the script element using jQuery using:

$("#my-view-template").text()

… you will notice that the content is empty! The browser engine has retrieved the content but did not store it in the actual DOM element for the script. This is due to the fact that a script of type text/html is not recognized as being a script to interpret.

So we need a mechanism to fetch and store the source. The approach consists of re-fetching the source using jQuery’s $.get API. Since it was fetched once, the content is stored in the browser’s cache so retrieval wil be very fast. We then store it in the DOM’s element.
Here is a simplistic example of what the code would look like:

$(document).ready(function () { $.get("/view/mypage/_my.view.html", function(data, textStatus, jqXHR) { $("#my-view-template") .text(jqXHR.responseText); } ); });

So finally we can integrate our KnockoutJS view model code in the ready function:

$(document).ready(function () { $.get("/view/mypage/_my.view.html", function(data, textStatus, jqXHR) { $("#my-view-template") .text(jqXHR.responseText); var myViewModel = { firstName: ko.observable('Chris'), time: ko.observable((new Date()).toLocaleTimeString()) } ko.applyBindings(viewModel); } ); });

You now have externalized the view template, dynamically loaded it, data-bound it to a view model using KnockoutJS, and rendered using the jQuery Template engine!

Our example was fairly basic but it illustrates the overall concept and approach.

Generic ViewLoader Plugin

The jQuery ViewLoader plugin will take us even further by providing the ability to:

Handle nested externalized templates

Parallelize the processing of each template

Provide a simple way to handle all templates on a page and synchronize their post-processing so that the page initialization logic can proceed.

Here is what the minimum syntax looks like:

$(document).viewloader({ logLevel: "debug", success: function () { ko.applyBindings(viewModel); } });

The plugin will identify all scripts of type text/html and a source url ending in “.view.html“, including nested template scripts and request their parallel loading. Once all template scripts have been succesfully processed the success function is invoked.

Behind the scenes, jQuery ViewLoader relies on the jQuery concept of “Deferred“, an action which can be launched for “deferred” (i.e. later) execution, but can trigger a callback when completed. Actions can be grouped together so that a specific callback can be triggered once all of them have completed.

Here is a diagram of the approach:

Externalizing The Views Of Our Savings Goal Simulator

Intro

We can now apply the new approach to our Savings Goal Simulator web app since it currently contains 3 views:

savings-goal-view

consumption-scenarios-view

savings-forecast-view

For each view, we will:

Create an externalized template in the /view/index folder based on the view markup

Replace the view in index.html by a template script reference and a container DIV data-bound to the template.

Finally, we’ll update the main application.js to plugin the jQuery ViewLoader.

Here is an outline of the step-by-step approach:

# To Do Area

1 Create An External Template For The savings-goal-view View

2 Refactor the savings-goal-view In Our Web Page View

3 Hookup jQuery ViewLoader In Our Main application.js Application

4 Refactor The Savings Goal Mediator View Mediator

1. Create An External Template For The savings-goal-view

Our first step will be to create a new folder named view under scripts to organize our external views. Similarly to frameworks like Ruby On Rails, or ASP.NET MVC, we’ll create a subfolder named shared, for all views reusable across pages, then we’ll create a subfolder named index for views appearing on our index.html web page.

In the scripts/view/index folder, let’s create a file named _savings-goal.view.html. I used an underscore prefix to reflect the Rails convention of “partial views” being prefixed that way.

Then we can copy the savings-goal-view markup from index.html page and paste it in our new _savings-goal.view.html file.

Savings Goal Amount:
Savings Max Duration (In Months):
Savings Target Per Month:

Now we can refactor index.html.

2. Refactor the savings-goal-view In Our Web Page

In place of our savings-goal-view markup, let’s first add a script reference to the view we just created, and give it an id of savings-goal-view-template:

Second, let’s add a div acting as a container for our external view. We’ll give it an id of savings-goal-view-container, and declare our KnockoutJS data-binding with the savings-goal-view-template:

Let’s download:

the latest version of jQuery Templates from https://github.com/jquery/jquery-tmpl

the latest version of KnockoutJS from https://github.com/SteveSanderson/knockout

the jQuery ViewLoader plugin and place it in the /scripts/vendor folder.

In the index.html page, in the LAB loader section, let’s:

Replace the call to load jQuery Template from our downloaded version (instead of the version from the CDN which is older)

Replace the call to load KnockoutJS from our downloaded version

Add a call to load the jQuery ViewLoader plugin:

Here is how all the piece parts will fit together:

Ok, now it’s time to plug in code to get the ViewLoader to load our view.

3. Hookup jQuery ViewLoader In Our Main application.js

First let’s create 2 new utility functions in application.js:

GetPageSettings – to retrieve our page settings from the DOM

SetPageSettings – to store our page settings in the DOM

function GetPageSettings() { return $(document).data("sgs.pagesettings"); } function SetPageSettings(pageSettings) { $(document).data("sgs.pagesettings", pageSettings); }

Let’s review the InitializeApplication function of our main application.js module. The core code consists of initializing a pageSettings dictionary and invoking our view mediators.

Let’s extract that part of the code into a new function named InitializeViewMediators:

function InitializeViewMediators() { if (typeof(console) != 'undefined' && console) console.info("InitializeViewMediators starting ..."); // Initialize our page-wide settings var pageSettings = { defaultSavingsGoal: 500, defaultSavingsMaxDuration: 6 } // Save the page-wide settings SetPageSettings(pageSettings); // Create / launch our view mediator(s) sgs.mediator.savingsgoal.createViewMediator(pageSettings); sgs.mediator.coffeepricing.createViewMediator(pageSettings); sgs.mediator.consumptionscenarios.createViewMediator(pageSettings); sgs.mediator.savingsforecast.createViewMediator(pageSettings); if (typeof(console) != 'undefined' && console) console.info("InitializeViewMediators done ..."); }

Let’s add the code to InitializeApplication to attach our ViewLoader plugin to the document object and invoke InitializeViewMediators upon success (i.e. once all views have been loaded):

function InitializeApplication() { if (typeof(console) != 'undefined' && console) console.info("InitializeApplication starting ..."); $(document).viewloader({ logLevel: "debug", success: function (successfulResolution) { InitializeViewMediators(); } ); if (typeof(console) != 'undefined' && console) console.info("InitializeApplication done ..."); }

And let’s add some logging code in the error function to know when the ViewLoader is failing to load a given view.

function InitializeApplication() { // ... $(document).viewloader({ // ... success: function (successfulResolution) { InitializeViewMediators(); }, error: function (failedResolution) { if (typeof(console) != 'undefined' && console) { console.error("index.html page failed to load"); } } }); // ... }

Here is the visual depiction of how application.js coordinates with the ViewLoader:

Not so fast … if we run the app, we’ll get an error. This is due to the fact that the code from the createViewMediator function of our sgs.mediator.savingsgoal module is expecting the view to be available. But at this point in the execution the view as not yet been rendered. This leads us to one more refactoring.

4. Refactor The Savings Goal Mediator

The current implementation of the createViewMediator function of our sgs.mediator.savingsgoal module assumes that our view is in the DOM, but at the moment the ViewLoader plugin kicked off the InitializeViewMediators function, KnockoutJS has not been requested to apply bindings yet nor render any view templates.

So let’s refactor the code related to setting up the various data-bindings and invoking KnockoutJS into a new function named setupViewDataBindings:

sgs.mediator.savingsgoal.setupViewDataBindings = function() { // Declare the HTML element-level data bindings $("#savings-goal-amount").attr("data-bind","value: savingsGoalAmount"); $("#savings-max-duration").attr("data-bind","value: savingsMaxDuration"); $("#savings-target-per-month").attr("data-bind","text: savingsTargetPerMonthFormatted()"); // Ask KnockoutJS to data-bind the view model to the view var viewNode = $('#savings-goal-view')[0]; var viewModel = sgs.mediator.savingsgoal.getViewModel(); ko.applyBindings(viewModel, viewNode); // Apply masking to the savings goal amount and max duration input fields viewModel.savingsGoalAmountMask.attach($("#savings-goal-amount")[0]); viewModel.savingsMaxDurationMask.attach($("#savings-max-duration")[0]); // Initialize default for value models linked to masked fields var pageSettings = GetPageSettings(); viewModel.savingsGoalAmount(pageSettings.defaultSavingsGoal || 0); viewModel.savingsMaxDuration(pageSettings.defaultSavingsMaxDuration || 0); // Subscribe to interesting value model changes viewModel.savingsTargetPerMonthFormatted.subscribe(function() { $("#savings-target-per-month") .effect('highlight', { color: 'LightGreen' }, 3000); // for 3 seconds }); if (typeof(console) != 'undefined' && console) console.info("sgs.mediator.setupViewDataBindings done!"); }

Note: We had to add a new line to access the viewModel since it is now available in the DOM and accessible using the sgs.mediator.savingsgoal.getViewModel function. We also add to add a line to get the pageSettings using our new GetPageSettings function.

After having extracted some of the code the createViewMediator function consist of the following:

sgs.mediator.savingsgoal.createViewMediator = function (pageSettings, pageViewModel) { // Create the view Savings Goal view-specific view model var viewModel = sgs.model.savingsgoal.initializeViewModel(pageSettings); // Save the view model sgs.mediator.savingsgoal.setViewModel(viewModel); if (typeof(console) != 'undefined' && console) console.info("sgs.mediator.savingsgoal ready!"); }

But since we added the savings-goal-view-container div to the page, we need to handle its data binding here. So let’s do that:

sgs.mediator.savingsgoal.createViewMediator = function (pageSettings, pageViewModel) { // Create the view Savings Goal view-specific view model var viewModel = sgs.model.savingsgoal.initializeViewModel(pageSettings); // Save the view model sgs.mediator.savingsgoal.setViewModel(viewModel); // Ask KnockoutJS to data-bind the view model to the view var viewNode = $('#savings-goal-view-container')[0]; ko.applyBindings(viewModel, viewNode); if (typeof(console) != 'undefined' && console) console.info ("sgs.mediator.savingsgoal ready!"); }

You probably noticed that there is no call yet to invoke our new setupViewDataBindings function! So where will it be invoked then? Well do you remember the comment about KnockoutJS exposing an afterRender callback function? (See back in KnockoutJS Databinding Support For Inline Templates.)

We’ll update the data-binding of savings-goal-view-container in our index.html, by assigning our new sgs.mediator.savingsgoal.setupViewDataBindings function to the afterRender attribute:

And now if we re-run our application, we’ll see in the console that setupViewDataBindings is being called while the savings-goal-view is being rendered, after the loading is successfully completed.

Here is an excerpt of the console:

InitializeApplication starting ... viewloader.loadSourceForPartialView loading source for view: id=savings-goal-view-template src=scripts/view/index/_savings-goal.view.html InitializeApplication done ... viewloader.loadSourceForPartialView saving source in savings-goal-view-template viewloader.loadAllPartialViews executing 'success' function InitializeViewMediators starting ... sgs.mediator.setupViewDataBindings done! sgs.mediator.savingsgoal ready! ... InitializeViewMediators done ...

We have successfully externalized the markup for the savings-goal-view!!!

In summary here is a diagram illustrating the page load processing flow:

5. Recap

Here is a quick recap of the steps we followed:

# To Do Area

1 Create An External Template For The savings-goal-view

Create a _your.view.html file

Cut the view markup from your .html and paste it in the .view.html

View

2 Refactor the savings-goal-view In Our Web Page

Add a script tag with an id, a text/html type and point the source to the new .view.html

Create a DIV container and add a data-bind with the template name (id)

View

3 Hookup jQuery ViewLoader In Our Main application.js

Split the view mediators initialization code into a separate InitializeViewMeditors function

Add $(document).viewloader({ // … }) to InitializeApplication

Call InitializeViewMeditors from the success callback of viewloader

Application

4 Refactor The Savings Goal Mediator

Create a new setupViewDataBindings function to create and apply data bindings inside the view

Trim down createViewMediators to focus only on initializing and storing the view model and asking KnockoutJS to apply the bindings to the view container.

Add an afterRender parameter to the template data-binding to instruct the template engine to invoke the setupViewDataBindings

View Mediator

6. Externalizing The Remaining Views

Now we just need to repeat the process on our remaining two views:

consumption-scenarios-view

savings-forecast-view

If you want to follow along with the source code changes, just get code for the tag corresponding to any particular step on the GitHub repository for the Savings Goal Simulator.

So What?

jQuery Template and jQuery ViewLoader allow you to structure and load views within a web page.

Externalizing your views makes your web pages more modular and easier to maintain, especially if you are working within a team as this allows you to assign different views (markup + code) to different individuals.

In the context of a “single page application” where you may have many views, these benefits are crucial to help you manage the complexity and allow you to grow the application organically / incrementally.

Another benefit of modularizing your views and view mediators will be that it will be easier to adapt and create different versions of the application for other channels, like a mobile web site or a mobile version of the application (using for example jQuery Mobile and PhoneGap).

References And Resources

jQuery Plugins

jQuery Template : http://api.jquery.com/category/plugins/templates/

jQuery ViewLoader : http://github.com/techarch/jquery-viewloader

jsRender + jsViews rendering engine : https://github.com/BorisMoore/jsviews

Mustache rendering engine : http://mustache.github.com/

Handlebars rendering engine : http://www.handlebarsjs.com/

jQuery ViewLoader rendering engine : https://github.com/techarch/jquery-viewloader

Miscellaneous

jQuery $.get : http://api.jquery.com/jQuery.get/

jQuery Deferred : http://api.jquery.com/category/deferred-object/

KnockoutJS afterRender : http://knockoutjs.com/documentation/template-binding.html#note4usingthe_option

Savings Goal Simulator : http://savings-goal-simulator.heroku.com/

My Other Related Posts:

Creating Rich Interactive Web Apps With KnockOut.js – Part 1

Creating Rich Interactive Web Apps With KnockOut.js – Part 2

Creating Rich Interactive Web Apps With KnockOut.js – Part 3

Full Source Of The Savings Goal Simulator (KnockoutJS Demo)

The whole application is available on Github under techarch / savings-goal-simulator.

If you enjoyed this post, I would love it if you could check out mySkillsMap, my skills management app.

Creating Rich Interactive Web Apps With KnockOut.js – Part 3

techarch — Sun, 30 Oct 2011 13:44:33 +0000

Intro

In Part 1, we introduced the key concepts and patterns including KnockoutJS. In Part 2, we started to build the first increment of our Savings Goal Simulation rich web app. The objectives of this third tutorial are:

Build up the rest of the application

Gain more practice with View Models, View Mediators, and KnockoutJS

Incorporate some basic elements of usability

Here is the overall target structure of the application:

Building Our App Step-By-Step

Here is what the app will look like at the end of this tutorial:

Here is an outline of the approach:

# To Do Area

1 Create the Consumption Scenarios View View

2 Create the Consumption Scenarios ViewModel View Model

3 Create the Consumption Scenarios View Mediator View Mediator

4 Link the Page and the View Mediator Main App

5 Create the Coffee Pricing ViewModel View Model

6 Create the Coffee Pricing ViewMediator View Mediator

7 Link the Page and the Coffee Pricing View Mediator Main App

8 Leveraging Independent View Models View Model

9 Create the Savings Forecast View View Mediator

10 Create the Savings Forecast ViewModel View Model

11 Create the Savings Forecast View Mediator View Mediator

12 Link the Page and the Savings Forecast View Mediator Main App

1. Create the Consumption Scenarios View

In our index.html page, let’s add a second section tag to represent our second panel / view: the consumption-scenarios-view.The view will let us enter current habits and see how modifying these habits can yield savings counting towards our saving goal.

This is what the view will look like:

Let’s add a table with 3 columns, one for the dimension to capture and affect (e.g. drink size), one for current habits, and one for our proposed consumption:

Weekly Coffee Consumption

Coffee Options Current Habits Proposed Change

Type:

Size:

Frequency:

Drinks per Day:

Cost Per Week:

Let’s fill the [Drink] Type row, consisting of sets of radio buttons for Regular, Latte, and Espresso, in both Current and Proposed columns:

Type:
Regular
Latte
Espresso

Regular
Latte
Espresso

Let’s fill the [Drink] Size row, consisting of sets of radio buttons for Tall, Grande, and Venti, in both Current and Proposed columns:

Size:
Tall
Grande
Venti

Tall
Grande
Venti

Let’s fill the [Drink] Frequency row, consisting of sets of radio buttons for Everyday, Monday-through-Friday, and Other (i.e. N days per week), in both Current and Proposed columns:

Frequency:
Everyday
Mon-Fri
Other:

Everyday
Mon-Fri
Other:

Let’s fill the Drinks Per Day row consisting of an simple input field, in both Current and Proposed columns:

Drinks per Day:

Let’s fill the Cost Per Week row consisting of
Cost Per Week:

Let’s fill the Savings Per Week row consisting of
Savings Per Week: &nsbsp;

2. Create the Consumption Scenarios ViewModel

In the ViewModels folder under the scripts folder, create a file named: sgs.model.consumption-scenarios.js.And let’s add a statement to load our new module in in our LAB.js section:

$LAB // ... .script("scripts/viewmodel/sgs.model.savings-goal.js").wait() .script("scripts/viewmodel/sgs.model.savings-goal.js").wait() .script("scripts/viewmediator/sgs.mediator.savings-goal.js").wait() .script("scripts/viewmodel/sgs.model.consumption-scenarios.js").wait() // ...

Let’s add the code snippet to lazy-create the namespace:

// Lazy initialize our namespace context: sgs.model.consumptionscenarios if (typeof(sgs) == 'undefined') sgs = { } if (typeof(sgs.model) == 'undefined') sgs.model = { } if (typeof(sgs.model.consumptionscenarios) == 'undefined') sgs.model.consumptionscenarios = { }

Let’s create our initializeViewModel function to initialize the view model and its three value models:

currentConsumption will track our current coffee drinking habits

proposedConsumption will allow us to experiment to see how much we could save

savingsPerWeek will show us the difference between proposed and current costs and will be implemented as a dependent observable function

savingsPerMonth(self explanatory)

For now let’s just assign currentConsumption and proposedConsumption to a ko.observable(null) for now – we’ll change that later (once we create the needed sub-view model).

sgs.model.consumptionscenarios.initializeViewModel = function (pageSettings) { // We can use properties of the pageSettings as default values for any of our ValueModels // If pageSettings are not provided we'll initialize an empty object if (typeof(pageSettings) == 'undefined') var pageSettings = { } var viewModel = { currentConsumption: ko.observable(null), proposedConsumption: ko.observable(null) }; // Stub implementation to be fully implemented later on viewModel.savingsPerWeek = ko.dependentObservable(function() { var result = 0; return result; }, viewModel); viewModel.savingsPerMonth = ko.dependentObservable(function() { var perMonth = this.savingsPerWeek() * 4; var result = Math.round(perMonth * 100) / 100; return result; }, viewModel); return viewModel; }

We need a way to model our coffee consumption.
So we’ll create a new module file named sgs.model.coffee-consumption.js under scripts/viewmodel.
And let’s add a statement to load our new module in in our LAB.js section (right before consumption-scenarios):

$LAB // ... .script("scripts/viewmodel/sgs.model.coffee-consumption.js").wait() .script("scripts/viewmodel/sgs.model.consumption-scenarios.js").wait() // ...

Let’s add the code snippet to lazy-create the namespace:

// Lazy initialize our namespace context: sgs.model.coffeeconsumption if (typeof(sgs) == 'undefined') sgs = { } if (typeof(sgs.model) == 'undefined') sgs.model = { } if (typeof(sgs.model.coffeeconsumption) == 'undefined') sgs.model.coffeeconsumption = { } if (typeof(console) != 'undefined' && console) console.info("sgs.model.coffeeconsumption loading!");

Let’s create our initializeViewModel function to initialize the view model based on the pageSettins as well as a scenario name. We’ll have the following value models:

scenarioName – will be either Current or Proposed

drinkType

drinkSize

drinkFrequency

customFrequency

drinksPerDay

sgs.model.coffeeconsumption.initializeViewModel = function (pageSettings, scenarioName) { // We can use properties of the pageSettings as default values for any of our ValueModels // If pageSettings are not provided we'll initialize an empty object if (typeof(pageSettings) == 'undefined') var pageSettings = { } var viewModel = { scenarioName: ko.observable(scenarioName), drinkType: ko.observable("Regular"), drinkSize: ko.observable("Tall"), drinkFrequency: ko.observable("Everyday"), customFrequency: ko.observable(1), drinksPerDay: ko.observable(1) } return viewModel; }

Let’s add two dependent observable functions named drinkHasStandardSize (will allow us to later restrict the drink size options based on the drink type) and drinkDaysPerWeek (will allow to calculate the cost per week):

sgs.model.coffeeconsumption.initializeViewModel = function (pageSettings, scenarioName) { // ... var viewModel = { // ... } viewModel.drinkHasStandardSize = ko.dependentObservable(function() { return this.drinkType() != 'Espresso'; }, viewModel); viewModel.drinkDaysPerWeek = ko.dependentObservable(function() { var count = 0; switch(this.drinkFrequency()) { case "Everyday": count = 7; break; case "WorkDays": count = 5; break; case "Other": count = this.customFrequency(); break; } return count; }, viewModel); return viewModel; }

I encourage you to test as you develop along , whether or not you are using a TDD or BDD approach (and framework like Jasmine). So refresh your browser and in the Firebug (or Webkit browser) console, instantiate a sgs.model.coffeeconsumption view model and invoke its drinkDaysPerWeek dependent observable like so:

var cs = sgs.model.coffeeconsumption.initializeViewModel() cs.drinkDaysPerWeek()

You can also step through the code in the debugger if you really want to check out what happens.

Now let’s move on and add a stub for a third dependent observable function named: costPerWeek

sgs.model.coffeeconsumption.initializeViewModel = function (pageSettings, scenarioName) { // ... var viewModel = { // ... } // ... // Stub implementation to be fully implemented later on viewModel.costPerWeek = ko.dependentObservable(function() { var result = 0; return result; }, viewModel); return viewModel; }

Later on we’ll come back to this view model and complete the stub implementation of the costPerWeek dependentObservable function to calculate the actual cost of the consumption model (based on pricing).

Now let’s go back to the initializeViewModel of our sgs.model.consumptionscenarios module and update the value model definitions to use custom instantiations of the sgs.model.coffeeconsumption view model so that the relationship between the two view models looks like this:

sgs.model.consumptionscenarios.initializeViewModel = function (pageSettings) { // We can use properties of the pageSettings as default values for any of our ValueModels // If pageSettings are not provided we'll initialize an empty object if (typeof(pageSettings) == 'undefined') var pageSettings = { } var current = sgs.model.coffeeconsumption.initializeViewModel (pageSettings, "Current"); var proposed = sgs.model.coffeeconsumption.initializeViewModel (pageSettings, "Proposed"); var viewModel = { currentConsumption: ko.observable(current), proposedConsumption: ko.observable(proposed) } // Stub implementation to be fully implemented later on viewModel.savingsPerWeek = ko.dependentObservable(function() { var result = 0; return result; }, viewModel); viewModel.savingsPerMonth = ko.dependentObservable(function() { var perMonth = this.savingsPerWeek() * 4; var result = Math.round(perMonth * 100) / 100; return result; }, viewModel); return viewModel; }

So now you have implemented an example of hierarchical view model! Again I invite you to test it using the browser Javascript console and debugger.

3. Create the Consumption Scenarios View Mediator

Let’s tackle the view mediator and connect the parts!
In the ViewMediator folder under the scripts folder, create a file named: sgs.mediator.consumption-scenarios.js.
This is the module where we’ll place our data-binding logic as well as any code related to mediating access between
the page, the consumption scenario view, and its view model.
And let’s add a statement to load our new module in in our LAB.js section:

$LAB // ... .script("scripts/viewmodel/sgs.model.consumption-scenarios.js").wait() .script("scripts/viewmediator/sgs.mediator.consumption-scenarios.js").wait() // ...

Let’s define our namespace:

// Lazy initialize our namespace context: sgs.mediator.consumptionscenarios if (typeof(sgs) == 'undefined') sgs = { } if (typeof(sgs.mediator) == 'undefined') sgs.mediator = { } if (typeof(sgs.mediator.consumptionscenarios) == 'undefined') sgs.mediator.consumptionscenarios = { } if (typeof(console) != 'undefined' && console) console.info("sgs.mediator.consumptionscenarios loading!");

Let’s create our createViewMediator function (per our convention) which we will eventually invoke from the InitializeApplication method in application.js. The createViewMediator function will have 4 responsibilities:

Instantiate a view model for the consumption scenarios view

Declare the data-binding between the HTML elements of the view and their corresponding value models in the view model

Ask KnockoutJS to make the bindings effective (they will be live right after that)

Save off the view model so we can access it from other parts of the app

So let’s implement the first responsibility to instantiate a view model for the consumption scenario view (using the initializeViewModel function we just created in the consumption scenario view model module).

sgs.mediator.consumptionscenarios.createViewMediator = function (pageSettings) { // Create the view Consumption Scenarios view-specific view model var viewModel = sgs.model.consumptionscenarios.initializeViewModel(pageSettings); }

Now let’s declare the data-bindings we need. For input elements we used the value attribute in our data-bind declaration, but since we have some radio buttons, it is the checked attribute of each radio button we need to target. Note that our binding will have a level of indirection via the currentConsumption value model, which is itself a view model with value models like drinkType. Here is what a snippet looks like for the radio buttons located inside the current-drink-type div:

sgs.mediator.consumptionscenarios.createViewMediator = function (pageSettings) { // Create the view Consumption Scenarios view-specific view model var viewModel = sgs.model.consumptionscenarios .initializeViewModel(pageSettings); // Declare the HTML element-level data bindings for the Current Habits column $("#current-drink-type input[type=radio]") .attr("data-bind", "checked: currentConsumption().drinkType");

Let’s finish up the rest of the bindings:

// ... // Declare the HTML element-level data bindings for the Current Habits column $("#current-drink-type input[type=radio]") .attr("data-bind","checked: currentConsumption().drinkType"); $("#current-drink-size input[type=radio]") .attr("data-bind","checked: currentConsumption().drinkSize"); $("#current-drink-frequency input[type=radio]") .attr("data-bind","checked: currentConsumption().drinkFrequency"); $("#current-custom-frequency") .attr("data-bind","value: currentConsumption().customFrequency"); $("#current-drinks-per-day") .attr("data-bind","value: currentConsumption().drinksPerDay"); $("#current-cost-per-week") .attr("data-bind","text: currentConsumption().costPerWeek"); // Declare the HTML element-level data bindings for the Proposed Change column $("#proposed-drink-type input[type=radio]") .attr("data-bind","checked: proposedConsumption().drinkType"); $("#proposed-drink-size input[type=radio]") .attr("data-bind","checked: proposedConsumption().drinkSize"); $("#proposed-drink-frequency input[type=radio]") .attr("data-bind","checked: proposedConsumption().drinkFrequency"); $("#proposed-custom-frequency") .attr("data-bind","value: proposedConsumption().customFrequency"); $("#proposed-drinks-per-day") .attr("data-bind","value: proposedConsumption().drinksPerDay"); $("#proposed-cost-per-week") .attr("data-bind","text: proposedConsumption().costPerWeek"); $("#savings-per-week") .attr("data-bind","text: savingsPerWeek"); // ...

Let’s add a new kind of binding attribute: “enable“, which allow us to control whether or not the data-bound HTML element should be enabled. This is a very useful binding as it will simplify enabling/disabling rules a lot. Here we’ll use it to control whether or not the drink size radio buttons should be enabled, since an espresso does not typically come in a Tall / Grande / Venti size! (Wow imagine the buzz on Venti!)

Reminder: The syntax of data-bind in KnockoutJS is:

databind="attribute1: valueModel1, attribute2: valueModel2, etc." // comma-separated list

This means that we will need to comma-separate and concatenate our new “attribute: valueModel” binding pair at the end of our existing declaration for the “checked” attribute like so:

// ... // Declare the HTML element-level data bindings for the Current Habits column // ... $("#current-drink-size input[type=radio]") .attr("data-bind","checked: currentConsumption().drinkSize " + ", enable: currentConsumption().drinkHasStandardSize"); // ... // Declare the HTML element-level data bindings for the Proposed Change column // ... $("#proposed-drink-size input[type=radio]") .attr("data-bind","checked: proposedConsumption().drinkSize" + ", enable: proposedConsumption().drinkHasStandardSize"); // ...

Caution: the name of the attribute is “enable” (not “enabled” – I have been bit by that many times)!

Now we’ll ask KnockoutJS to “apply”, i.e. register / enable our bindings.

sgs.mediator.consumptionscenarios.createViewMediator = function (pageSettings) { // ... // Ask KnockoutJS to data-bind the view model to the view var viewNode = $('#consumption-scenarios-view')[0]; ko.applyBindings(viewModel, viewNode); }

Now let’s add the 2 functions to store retrieve our consumption scenarios view model:

sgs.mediator.consumptionscenarios.getViewModel = function() { return $(document).data("sgs.model.consumptionscenarios.viewmodel"); } sgs.mediator.consumptionscenarios.setViewModel = function(viewModel) { $(document).data("sgs.model.consumptionscenarios.viewmodel", viewModel); }

Now we can call the setViewModel function from inside createViewMediator to save off our freshly-created view model.

sgs.mediator.consumptionscenarios.createViewMediator = function (pageSettings) { // ... // Save the view model sgs.mediator.consumptionscenarios.setViewModel(viewModel); if (typeof(console) != 'undefined' && console) console.info("sgs.mediator.coffeeconsumption ready!"); }

If you want to test the mediator, just refresh the browser, and invoke the createViewMediator in the browser Javascript console like so:

sgs.mediator.consumptionscenarios.createViewMediator({})

You will then see the radio buttons get set to their default value. And clicking on the Espresso radio button should cause the Size radio buttons to become disabled.

4. Link the Page and the Consumptions Scenarios View Mediator

To instantiate our new mediator, we just need to add a call to the overall page InitializeApplication function (located in our scripts/application.js) to our consumption scenario createViewMediator function like so:

function InitializeApplication() { if (typeof(console) != 'undefined' && console) console.info("InitializeApplication starting ..."); // Initialize our page-wide settings var pageSettings = { defaultSavingsGoal: 500 } // Create / launch our view mediator(s) sgs.mediator.savingsgoal.createViewMediator(pageSettings); sgs.mediator.consumptionscenarios.createViewMediator(pageSettings); if (typeof(console) != 'undefined' && console) console.info("InitializeApplication done ..."); }

So now you should be able to load your index.html page in Firefox with the Firebug console on and watch the debug statement and finally our new consumption scenarios view displays with our default values:

5. Create the Coffee Pricing ViewModel

Now we need a pricing engine! It needs to ake into account : the drink type and drink size. And we can apply frequency and drinks per day to calculate the cost. To keep logic encapsulated, let’s create a new module file in the scripts/viewmodel folder named sgs.model.coffee-pricing.js. The new module will be responsible for:

having a default example pricing list for the various coffee options

providing its own view model with a pricing value model

loading / saving its content to the browser local storage (using jStorage, a cross-browser HTML 5 local storage abstraction library)

Let’s add the code snippet to lazy-create the namespace:

// Lazy initialize our namespace context: sgs.model.coffeeconsumption if (typeof(sgs) == 'undefined') sgs = { } if (typeof(sgs.model) == 'undefined') sgs.model = { } if (typeof(sgs.model.coffeepricing) == 'undefined') sgs.model.coffeepricing = { } if (typeof(console) != 'undefined' && console) console.info("sgs.model.coffeepricing loading!");

Update the LAB.js section of the index.html page so we can load the new module (before sgs.model.coffee-consumption):

$LAB // ... .script("scripts/viewmodel/sgs.model.coffee-pricing.js").wait() .script("scripts/viewmodel/sgs.model.coffee-consumption.js").wait() // ...

Now we’ll create an examplePricing function which will return a hash of key-value pairs where the key will be a composite of the coffee type and size, and the value an amount.

sgs.model.coffeepricing.examplePricing = function() { var priceList = { "Regular-Tall": 1.40, "Regular-Grande": 1.60, "Regular-Venti": 1.70, "Latte-Tall": 2.55, "Latte-Grande": 3.10, "Latte-Venti": 3.40, "Espresso": 1.75, "EspressoShot": 0.25 } return priceList; }

Now let’s define our initializeViewModel function with a place holder for the price list:

sgs.model.coffeepricing.initializeViewModel = function (pageSettings) { // We can use properties of the pageSettings as default values for any of our ValueModels // If pageSettings are not provided we'll initialize an empty object if (typeof(pageSettings) == 'undefined') var pageSettings = { } var priceList = { } var viewModel = { pricing: ko.observable(priceList) } return viewModel; }

Ok, now we want to check if we have a price list in local storage and lazy-initialize it otherwise. We’ll encapsulate the logic in a function named: getPriceList. We’ll try to retrieve the “coffee-price-list” using $.jStorage.get(key) API:

sgs.model.coffeepricing.getPriceList = function () { // Check if we have ever stored the price list locally var priceList = $.jStorage.get("coffee-price-list"); if (priceList == null) { // If not create an example priceList = sgs.model.coffeepricing.examplePricing(); // Save it off $.jStorage.set("coffee-price-list", priceList); } return priceList; }

So now we can edit our in initializeViewModel function and plug in the getPriceList for the initialization of the pricing value model:

sgs.model.coffeepricing.initializeViewModel = function (pageSettings) { // We can use properties of the pageSettings as default values for any of our ValueModels // If pageSettings are not provided we'll initialize an empty object if (typeof(pageSettings) == 'undefined') var pageSettings = { } // Lazy-initialize the price list var priceList = sgs.model.coffeepricing.getPriceList(); var viewModel = { pricing: ko.observable(priceList) } return viewModel; }

To encapsulate pricing data requests, let’s add a “normal” function (i.e. not an dependent observable) named getCoffeeBeveragePrice to our view model:

sgs.model.coffeepricing.initializeViewModel = function (pageSettings) { // ... viewModel.getCoffeeBeveragePrice = function (drinkType, drinkSize) { var key = drinkType; if (drinkType != 'Espresso' && drinkSize) { key += '-' + drinkSize; } var price = viewModel.pricing()[key]; return price; } return viewModel; }

Once reloading the index.html page, you should be able to experiment with jStorage. To see all keys stored with jStorage (should be an empty array initially):

$.jStorage.index()

Now, let’s make a call to sgs.model.coffeepricing.getPriceList(). This will lazy-initialize the price list and store it. So when asking for the jStorage index a second time the console should display an array with our “coffee-price-list” key. And we can access the value for our key using:

sgs.model.coffeepricing.getPriceList() $.jStorage.index() $.jStorage.get("coffee-price-list")

6. Create the Coffee Pricing ViewMediator

In the Viewmediator folder under the scripts folder, create a file named: sgs.mediator.coffee-pricing.js. This is the module where we’ll place our data-binding logic as well as any code related to mediating access between the page, a future pricing editing view, and its view model.
And let’s add a statement to load our new module in in our LAB.js section:

$LAB // ... .script("scripts/viewmodel/sgs.model.coffee-pricing.js").wait() .script("scripts/viewmediator/sgs.mediator.coffee-pricing.js").wait() // ...

Let’s define our namespace:

// Lazy initialize our namespace context: sgs.mediator.coffeepricing if (typeof(sgs) == 'undefined') sgs = { } if (typeof(sgs.mediator) == 'undefined') sgs.mediator = { } if (typeof(sgs.mediator.coffeepricing) == 'undefined') sgs.mediator.coffeepricing = { } if (typeof(console) != 'undefined' && console) console.info("sgs.mediator.coffeepricing loading!");

Let’s create our createViewMediator function (per our convention) which we will eventually invoke from the InitializeApplication method in application.js. The createViewMediator function will have 3 responsibilities:

Instantiate a view model for the future pricing editor view

Ask KnockoutJS to make the bindings effective (they will be live right after that)

Save off the view model so we can access it from other parts of the app

Note: this mediator will not need to setup any data-bindings with the view, since we are not planning on displaying the pricing. However, the consumption scenario mediator will collaborate with it in order to access its pricing view model.

So let’s implement the first responsibility to instantiate a view model
(using the initializeViewModel function we just created in the coffee pricing view model module).

sgs.mediator.coffeepricing.createViewMediator = function (pageSettings) { // Create the view Pricing Editor view-specific view model var viewModel = sgs.model.coffeepricing.initializeViewModel(pageSettings); }

Now let’s add the 2 functions to store retrieve our coffee pricing view model:

sgs.mediator.coffeepricing.getViewModel = function() { return $(document).data("sgs.model.coffeepricing.viewmodel"); } sgs.mediator.coffeepricing.setViewModel = function(viewModel) { $(document).data("sgs.model.coffeepricing.viewmodel", viewModel); }

Now we can use the setViewModel function inside createViewMediator to save off our freshly-created view model.

sgs.mediator.coffeepricing.createViewMediator = function (pageSettings) { // ... // Save the view model sgs.mediator.coffeepricing.setViewModel(viewModel); if (typeof(console) != 'undefined' && console) console.info("sgs.mediator.coffeepricing ready!"); }

7. Link the Page and the Coffee Pricing View Mediator

To instantiate our new mediator, we just need to add a call to the overall page InitializeApplication function (located in our scripts/application.js) to our coffee pricing createViewMediator function like so:

function InitializeApplication() { if (typeof(console) != 'undefined' && console) console.info("InitializeApplication starting ..."); // Initialize our page-wide settings var pageSettings = { defaultSavingsGoal: 500 } // Create / launch our view mediator(s) sgs.mediator.savingsgoal.createViewMediator(pageSettings); sgs.mediator.coffeepricing.createViewMediator(pageSettings); sgs.mediator.consumptionscenarios.createViewMediator(pageSettings); if (typeof(console) != 'undefined' && console) console.info("InitializeApplication done ..."); }

8. Leveraging Independent View Models

At this point we have created the consumption, scenarios, and pricing view models, but we have not yet “connected” all the parts to allow for the costPerWeek value model of coffeeconsumption to work. Before we proceed let’s review a few requirements and guiding principles:

The consumptionscenarios view model knows about the current and proposed coffee consumptions

The coffeeconsumption view model has the costPerWeek dependent observable function

The coffeepricing view model has the pricing

The coffeepricing view mediator manages access to its view model

We want to keep the view models from knowing about the mediators

Over time, we may want to test different pricing models in each scenario

So to maintain isolation but yet gain some flexibility we will:

Add a pricing value model to the coffeeconsumption view model – this way costPerWeek will have access to it

Add a pricing value model to the consumptionscenarios view model – this way it can pass it on each of the current and proposed consumptions models

Add a subscription to the pricing change in the consumptionscenarios view model so we can update the pricing of the current and proposed consumptions models

Have the consumption-scenario and coffee pricing view mediators share the pricing view model

Here is what the relationship between the various mediators and model will look like:

First, let’s add a pricing value model to the coffeeconsumption view model (located in scripts/viewmodel/sgs.model.coffeeconsumption.js):

sgs.model.coffeeconsumption.initializeViewModel = function (pageSettings, scenarioName) { // ... var viewModel = { pricing: ko.observable(null), scenarioName: ko.observable(scenarioName), // ... } // ... }

Second, let’s add a pricing value model to the consumptionscenarios view model (located in scripts/viewmodel/sgs.model.consumptionscenarios.js)

sgs.model.consumptionscenarios.initializeViewModel = function (pageSettings) { // ... var viewModel = { pricing: ko.observable(null), currentConsumption: ko.observable(current), proposedConsumption: ko.observable(proposed) } // ... }

Third, let’s add a subscription to pricing value model so we can re-act to pricing model changes and pass the new pricing down to our 2 consumption models:

sgs.model.consumptionscenarios.initializeViewModel = function (pageSettings) { // ... viewModel.pricing.subscribe(function(newPricing) { viewModel.currentConsumption().pricing(newPricing); viewModel.proposedConsumption().pricing(newPricing); }); // ... }

Fourth, let’s have the consumption-scenario view mediator set the pricing based on the view model of the coffee pricing view mediator:

sgs.mediator.consumptionscenarios.createViewMediator = function (pageSettings) { // ... // Save the view model sgs.mediator.consumptionscenarios.setViewModel(viewModel); // Set the pricing based on the Coffee Pricing view model var priceList = sgs.mediator.coffeepricing.getViewModel(); viewModel.pricing(priceList); // ... }

So now we have the bits in place to fully implement the costPerWeek function of the coffeeconsumption view model. (Remember we had just put in a stub implementation returning 0 in step “2. Create the Consumption Scenarios ViewModel”). It’s a matter of performing the calculations like so:

sgs.model.coffeeconsumption.initializeViewModel = function (pageSettings, scenarioName) { // ... viewModel.costPerWeek = ko.dependentObservable(function() { // Get the base price if (this.pricing() == null) { return 0; } var basePrice = this.pricing().getCoffeeBeveragePrice(this.drinkType(), this.drinkSize()); var dailyCost = basePrice * this.drinksPerDay(); var weeklyCost = dailyCost * this.drinkDaysPerWeek(); var result = Math.round(weeklyCost * 100) / 100; return result; }, viewModel); return viewModel; }

And finally we can go back and finish the implementation of the savingsPerWeek function in the consumptionscenarios view model. (Remember we had just put in a stub implementation returning 0 in step “2. Create the Consumption Scenarios ViewModel”)

sgs.model.consumptionscenarios.initializeViewModel = function (pageSettings) { // ... viewModel.savingsPerWeek = ko.dependentObservable(function() { var costDifference = this.currentConsumption().costPerWeek() - this.proposedConsumption().costPerWeek(); var result = Math.round(costDifference * 100) / 100; return result; }, viewModel); // ... return viewModel; }

Now we’re ready to refresh the index.html page, select Grande Latte under Current Habits and Tall Regular under Proposed Changes and you should see the costs update as well as the savings. We now have a functioning Weekly Coffee Consumption panel! :-)

I will leave the following usability additions for you to do:

Formatting of the costs and saving amounts (dependent observables and Accounting.js – see Part 1 ToDo #9 – Applying Formatting Rules)

Add visual feedback (using the jQuery highlight effect) for the costs and savings fields see Part 1 ToDo #10 – Applying Visual Feedback Clues

Overall styling

9. Create the Savings Forecast View

In our index.html page, let’s add a second section tag to represent our third panel / view:
the savings-forecast-view.
The view will help us compare projected savings against our goal.

This is what the view will look like:

The view will have three pairs of labels and spans to show calculated values for:

Savings forecast per month

Forecast variance from the target monthly savings goal

Forecasted number of months to achieve the savings goal

Savings Forecast Per Month:
Forecast Variance:
Months To Savings Goal:

10. Create the Savings Forecast ViewModel

In the ViewModels folder under the scripts folder, create a file named: sgs.model.savings-forecast.js.
And let’s add a statement to load our new module in in our LAB.js section:

$LAB // ... .script("scripts/viewmodel/sgs.model.savings-forecast.js").wait() // ...

Let’s add the code snippet to lazy-create the namespace:

// Lazy initialize our namespace context: sgs.model.savingsforecast if (typeof(sgs) == 'undefined') sgs = { } if (typeof(sgs.model) == 'undefined') sgs.model = { } if (typeof(sgs.model.savingsforecast) == 'undefined') sgs.model.savingsforecast = { } if (typeof(console) != 'undefined' && console) console.info("sgs.model.savingsforecast loading!");

Let’s create our initializeViewModel function to initialize the view model.
We need two dependent observable functions:

forecastVariancePerMonth will allow us to experiment to see how much we could save

timeToGoalInMonths will show us the difference between proposed and current costs and will be implemented as a dependent observable function

sgs.model.savingsforecast.initializeViewModel = function (pageSettings) { // We can use properties of the pageSettings as default values for any of our ValueModels // If pageSettings are not provided we'll initialize an empty object if (typeof(pageSettings) == 'undefined') var pageSettings = { } var viewModel = { }; viewModel.forecastVariancePerMonth = ko.dependentObservable(function() { // TBD }, viewModel); viewModel.timeToGoalInMonths = ko.dependentObservable(function() { // TBD }, viewModel); return viewModel; }

Design Note: in this series of tutorial I have promoted the idea of decoupling all views, models, and mediators (as possible) as it makes the application more modular and it is easier to test all parts independently. So for this view model, instead of requesting the value models from other mediators namely savingsGoalAmount, savingsTargetPerMonth and savingsPerMonth, we will create dedicated value models which will later synchronize with using subscriptions in our mediators – since it is ok for the mediators to collaborate.

sgs.model.savingsforecast.initializeViewModel = function (pageSettings) { // ... var viewModel = { savingsGoalAmount: ko.observable(0), savingsTargetPerMonth: ko.observable(0), savingsPerMonth: ko.observable(0) }; // ... return viewModel; }

Let’s flesh-out our calculations:

sgs.model.savingsforecast.initializeViewModel = function (pageSettings) { // ... viewModel.forecastVariancePerMonth = ko.dependentObservable(function() { var variance = this.savingsPerMonth() - this.savingsTargetPerMonth(); var result = Math.round(variance * 100) / 100; return result; }, viewModel); viewModel.timeToGoalInMonths = ko.dependentObservable(function() { var timeToGoal = 0; var savingsPerMonth = this.savingsPerMonth(); var savingsGoalAmount = this.savingsGoalAmount(); if (savingsPerMonth != 0) { timeToGoal = savingsGoalAmount / savingsPerMonth; } }, viewModel); // ... }

11. Create the Savings Forecast View Mediator

In the Viewmediator folder under the scripts folder, create a file named: sgs.mediator.savings-forecast.js. This is the module where we’ll place our data-binding logic as well as any code related to mediating access between the page, the consumption scenario view, and its view model.
And let’s add a statement to load our new module in in our LAB.js section:

$LAB // ... .script("scripts/viewmodel/sgs.model.savings-forecast.js").wait() .script("scripts/viewmediator/sgs.mediator.savings-forecast.js").wait() // ...

Let’s define our namespace:

// Lazy initialize our namespace context: sgs.mediator.savingsforecast if (typeof(sgs) == 'undefined') sgs = { } if (typeof(sgs.mediator) == 'undefined') sgs.mediator = { } if (typeof(sgs.mediator.savingsforecast) == 'undefined') sgs.mediator.savingsforecast = { } if (typeof(console) != 'undefined' && console) console.info("sgs.mediator.savingsforecast loading!");

Let’s create our createViewMediator function (per our convention) which we will eventually invoke from the InitializeApplication method in application.js. The createViewMediator function will have 5 responsibilities:

Instantiate a view model for the savings forecast view

Establish subscriptions for various value models to keep the main view model synchronized

Declare the data-binding between the HTML elements of the view and their corresponding value models in the view model

Ask KnockoutJS to make the bindings effective (they will be live right after that)

Save off the view model so we can access it from other parts of the app

So let’s implement the first responsibility to instantiate a view model for the consumption scenario view (using the initializeViewModel function we just created in the consumption scenario view model module).

sgs.mediator.savingsforecast.createViewMediator = function (pageSettings) { // Create the view Savings Forecast view-specific view model var viewModel = sgs.model.savingsforecast.initializeViewModel(pageSettings); }

Now we need to establish 3 subscriptions so that we can keep our saving forecast view model in synch with value models from the savings goal and consumption scenarios view models. Here is a graphical depiction of what we need:

To make this happen we need the savingsforecast mediator to request specific value models from the view models of the savingsgoal and consumptionsscenarios mediators:

sgs.mediator.savingsforecast.createViewMediator = function (pageSettings) { // ... // Subscribe to changes in savingsGoalAmount and savingsTargetPerMonth // to synchronize our own equivalent value models var savingsGoalModel = sgs.mediator.savingsgoal.getViewModel(); // Initialize the current savingsGoalAmount viewModel.savingsGoalAmount(savingsGoalModel.savingsGoalAmount()); savingsGoalModel.savingsGoalAmount.subscribe(function(newValue) { viewModel.savingsGoalAmount(newValue); }); savingsGoalModel.savingsTargetPerMonth.subscribe(function(newValue) { viewModel.savingsTargetPerMonth(newValue); }); // Subscribe to changes in savingsPerMonth to synchronize our own equivalent value model var consumptionscenariosModel = sgs.mediator.consumptionscenarios.getViewModel(); consumptionscenariosModel.savingsPerMonth.subscribe(function(newValue) { viewModel.savingsPerMonth(newValue); }); // ... }

Now let’s declare the data-bindings we need.

sgs.mediator.savingsforecast.createViewMediator = function (pageSettings) { // Create the view Savings Forecast view-specific view model var viewModel = sgs.model.savingsforecast .initializeViewModel(pageSettings); // Declare the HTML element-level data bindings $("#savings-forecast-per-month") .attr("data-bind","text: savingsPerMonth"); $("#forecast-variance-per-month") .attr("data-bind","text: forecastVariancePerMonth"); $("#time-to-goal-in-months") .attr("data-bind","text: timeToGoalInMonths"); // ...

Now we’ll ask KnockoutJS to “apply”, i.e. register / enable our bindings.

sgs.mediator.savingsforecast.createViewMediator = function (pageSettings) { // ... // Ask KnockoutJS to data-bind the view model to the view var viewNode = $('#savings-forecast-view')[0]; ko.applyBindings(viewModel, viewNode); }

Now let’s add the 2 functions to store retrieve our savings forecast view model:

sgs.mediator.savingsforecast.getViewModel = function() { return $(document).data("sgs.model.savingsforecast.viewmodel"); } sgs.mediator.savingsforecast.setViewModel = function(viewModel) { $(document).data("sgs.model.savingsforecast.viewmodel", viewModel); }

Now we can use the setViewModel function inside createViewMediator to save off our freshly-created view model.

sgs.mediator.savingsforecast.createViewMediator = function (pageSettings) { // ... // Save the view model sgs.mediator.savingsforecast.setViewModel(viewModel); if (typeof(console) != 'undefined' && console) console.info("sgs.mediator.savingsforecast ready!"); }

Again you can try your new mediator using the browser console:

sgs.mediator.savingsforecast.createViewMediator({})

Playing with the simulation should now update the savings-forecast view.

12. Link the Page and the Savings Forecast View Mediator

To instantiate our new mediator, we just need to add a call to the overall page InitializeApplication function (located in our scripts/application.js) to our consumption scenario createViewMediator function like so:

function InitializeApplication() { if (typeof(console) != 'undefined' && console) console.info("InitializeApplication starting ..."); // Initialize our page-wide settings var pageSettings = { defaultSavingsGoal: 500 } // Create / launch our view mediator(s) sgs.mediator.savingsgoal.createViewMediator(pageSettings); sgs.mediator.coffeepricing.createViewMediator(pageSettings); sgs.mediator.consumptionscenarios.createViewMediator(pageSettings); sgs.mediator.savingsforecast.createViewMediator(pageSettings); if (typeof(console) != 'undefined' && console) console.info("InitializeApplication done ..."); }

Now you can refresh your page and should be able to see the new savings forecast view update as you experiment!

Overall Recap

In this part 3 of the tutorial we have added quite a bit more functionality and complexity. Hopefully the modularization, separation into different files and folders, the namespacing, and various patterns are now starting to reveal their purpose and value. ;-)
So here is a quick recap of the steps we followed:

# To Do Area (Module)

1 Create the Consumption Scenarios View View

2 Create the Consumption Scenarios ViewModel View Model

3 Create the Consumption Scenarios View Mediator View Mediator

4 Link the Page and the View Mediator Main App

5 Create the Coffee Pricing ViewModel View Model

6 Create the Coffee Pricing ViewMediator View Mediator

7 Link the Page and the Coffee Pricing View Mediator Main App

8 Leveraging Independent View Models View Model

9 Create the Savings Forecast View View Mediator

10 Create the Savings Forecast ViewModel View Model

11 Create the Savings Forecast View Mediator View Mediator

12 Link the Page and the Savings Forecast View Mediator Main App

So What?

This part 3 gave you a lot more practice with the core patterns and also showed you the following:

Create hierarchical view models

Setup custom subscriptions to keep independent view models synchronized

Configure multiple attributes inside a data-bind declaration (e.g. checked and enabled)

Leverage jStorage for local browser data caching

If we step back and look at the modularization of our application so far, we’ll notice that although our models and view mediators are modular, the actual index.html web page has become larger and is not modular at all. Wouldn’t it be nice if we could extract each of our views into external modules? Well, this is exactly what part 4 will cover!

Leveraging jQuery templates

Extracting views into templates (and in separate files)

… and more!

So stay tuned!

References and Resources

Patterns

Model View – ViewModel Pattern

MVC Xerox Parc 1978-79

MVC Pattern

Observer Pattern

Publish Subscribe Pattern

Value Model Pattern

Data Binding Pattern

Summary of Namespacing Approaches (by Elijah Manor)

Namespacing using Object Literals

Namespacing using Functions

Frameworks And Blogs

KnockoutJS

Learn KnockoutJS (Interactive Tutorial / Playground)

jQuery

jQuery UI

jQuery Template

jQuery Template API

Knock Me Out (Steve Sanderson’s Blog)

Knock Me Out (Ryan Niemeyer’s Blog)

Patterns For Large-Scale Javascript Architecture (Addy Osmani)

Javascript Loaders

HeadJS

LABjs

LazyLoad

jQuery Cookie

jQuery Plugins

jQuery BlockUI

jQuery Cookie

jQuery DataTables

jQuery HotKeys

jQuery jsTree

jQuery Validate

Other Javascript Libraries

Modernizr

BlockUI

Accounting.js

CurrencyMask JS

Masked Input

Raphael JS

gRaphael JS

jStorage

Underscore

Ajax Fixtures

Javascript Test Frameworks

Jasmine, BDD for Javascript

Jasmine Species, BDD Grammar Extensions (Given, When, Then, etc.)

My Other Related Posts:

Creating Rich Interactive Web Apps With KnockOut.js – Part 1

Creating Rich Interactive Web Apps With KnockOut.js – Part 2

Full Source Of The Savings Goal Simulator (KnockoutJS Demo)

The whole application is available on Github under techarch / savings-goal-simulator.

If you enjoyed this post, I would love it if you could check out mySkillsMap, my skills management app.

Creating Rich Interactive Web Apps With KnockOut.js – Part 2

techarch — Tue, 18 Oct 2011 03:29:18 +0000

Intro

In Part 1 of “Creating Rich Interactive Web Apps With KnockOut.js”, I reviewed some of the key patterns you need to consider such as: MVC, Model View – ViewModel, Observer, Publish Subscribe, Value Model, Data Binding.

In this second post, we will cover the following topics while creating a fun app:

Architecting our application so it can easily be extended over time

Splitting the logic according to separations of concerns

Incorporating rudimentary elements of usability

For The Price Of N Cups of Coffee …

To illustrate the various concepts, we’ll create a simulator application to figure out how we can tweak our coffee consumption habits to save a given amount of money over a period of time.

Note: You can try the app at: savings-goal-simulator.heroku.com and inspect / play with it in Firebug. The full source is also available on Github under techarch / savings-goal-simulator.

Building Our App Step-By-Step

Here is an outline of the approach:

# To Do Area

1 Create a Shell Application Main app

2 Organize our Application Code Main App

3 Create the Savings Goal View View

4 Create the Savings Goal ViewModel View Model

5 Create the Savings Goal View Mediator View Mediator

6 Link the Page and the View Mediator Main App

7 Apply Data Masking Business Rules View Mediator

8 Apply Custom Masking Rules View Mediator

9 Applying Formatting Rules View Mediator

10 Providing Visual Feedback Cues View Mediator

Thanks to Susan Potter‘s suggestion of tagging the source code on Github, you can download the source corresponding to the application as of the end of each “todo” step! You can find the list of tags here.

1. Create a Shell Application

Note: In this tutorial we will de-emphasize the server framework side and focus on browser considerations.
So let’s start:

Create a root folder for our application named savings-goal-simulator

Create a file named index.html for our main page

Create a folder for our Javascript files named scripts

Create a sub-folder under scripts for our vendor Javascript libraries named vendor

Add the basic markup for a page in index.html

Ok, now we’re ready to add our key external Javascript libraries.
Here is the basic minimum we’ll need with a quick rationale as of why they will help us:

Library Purpose / Rationale

Modernizr Detects HTML 5 support and provide IE shims

jQuery Main foundation (do I need to say more :-) ?!)

jQuery UI Prefabricated UI super-elements like tabs, accordions, sliders, etc.

jQuery Cookies Easy management of cookies

jQuery HotKeys Handling of keyboard shortcuts

jQuery Masked Input Allow creation of custom input masks

jQuery Validate Validation framework

Accounting.js Allow formatting currency amounts

CurrencyMaskJS Allow masked input of currency amounts

jStorage Wrapper for local storage APIs

If we want to start authoring HTML 5 semantic pages, Modernizr is a library which can facilitate detection of specific HTML5 and CSS3 features. But it also shines for Internet Explorer versions earlier than 9 by plugging in “shims“, i.e. fake HTML elements in the DOM, named after the new HTML5 missing elements, making it possible to use tags likeheader, footer, section, etc. and styling them too.

You will need to create your own custom version of Modernizr based on the features you need. This will ensure the smallest most effective script for your situation.
For our app, I chose to only include the “HTML5 Shim/IEPP” and the “CSS classes” – see this download configuration. I renamed the resulted file as modernizr.custom.min.js and placed it in the scripts/vendor folder.
So we’ll need to include the script for Modernizr right at the beginning our our HEAD section.

For performance reasons, we’ll use a Javascript loader (see available options further on) to ensure the Javascript libraries we’ll need can be loaded asynchronously, in parallel, and not block the execution of our page load.
For this app, I chose LABjs as it is specializes only on loading and is commonly used.
But note that you could use some of the conditional loading features of Modernizr, called yepnope.
I chose to keep things minimal for our app. ;-)

Starting from a basic HTML page, let’s add a script reference to lab.js below our modernizr script, and then let’s define the order in which we want to load our libraries.
We’ll add a call to wait() if we want the execution of the actual code to be order-dependent:

You will notice that I am assuming a specific directory structure for our locally hosted Javascript code

scripts is the root of all .js files

Vendor will host external vendor libraries not available on a CDN.
Having all external JS libraries in a dedicated folder will keep our directory structure clean.

ViewMediator will include Javascript code mediating interactions between Views and ViewModels

ViewModel will include our ViewModel-specific Javascript code

application.js will be the main application .js file with an InitializeApplication function (called from our $LAB configuration)

At this point go ahead and create the same folder structure and download the needed Javascript libraries for the Vendor folder.
You can use the links in the External Javascript Libraries table above.

And create the application.js file under the root of the scripts folder, and let’s provide a minimal implementation for now:

function InitializeApplication() { if (typeof(console) != 'undefined' && console) console.info("InitializeApplication starting ..."); }

If you run the application you should see the informational message being displayed in the console.
And in Firefox Firebug, or on a WebKit browser you should see the parallel loading of the scripts.

For our CSS, let’s create a folder named css in which we’ll extract the custom-theme folder from our jQuery UI download.
We’ll also create an application.css file for our application-specific styles.

2. Organize our Application Code

Since our application will very modular and encompass many functions or classes,
we’ll establish a namespace to provide some structure and avoid function name clashes.
You can read more about how to implement namespaces in Javascript in the following two articles:

Elegant Code – Namespaces

StackOverflow “Javascript Namespace Declaration”

For this app, we’ll use sgs (for savings goal simulator) as a prefix,
followed by either model or mediator for ViewModel and ViewMediator respectively.
To keep our markup free of Javascript logic, we’ll organize the application code in the following folders:

application.js will contain only logic to initialize / setup the views and viewmodels

ViewModel – this folder will contain several files:

sgs.model.common.js for reusable logic across all types of ViewModels

one file for the page-level view model – e.g. sgs.model.index.js

one file for each view-specific view model – e.g. sgs.model.savings-goal.js –

ViewMediator – this folder will contain several files:

sgs.mediator.common.js for reusable logic across all view mediators

one file for the page-level view mediator – e.g. sgs.mediator.index.js

one file for each view-specific view mediator – e.g. sgs.mediator.savings-goal.js –

So at this point, create the folder structure described above as well as stub content for sgs.model.common.js and sgs.model.common.js (they can remain empty for now). And let’s update the LAB.js section to load these 2 files (before application.js):

$LAB // ... .script("scripts/viewmodel/sgs.model.common.js") .script("scripts/viewmediator/sgs.mediator.common.js") .script("scripts/application.js").wait(function(){ // When ALL scripts have been loaded AND executed: InitializeApplication(); });

Here is a quick synopsis of the architecture for the first increment of our app:

3. Create the Savings Goal View

Now that we have a minimal shell in index.html,
let’s add a section tag to represent our first panel / view: the savings-goal-view.
The view will let us enter a savings goal amout and a maximum number of months.

Now we can add the two input elements (savings-goal-amount and savings-max-duration).
And we’ll have a span to display the calculated (derived) savings-target-per-month. This is what the view will look like:

Important Note: In this tutorial, instead of “inlining” the data-binding declaration with the view model inside the markup (like you will see in the KnockoutJS site or on any other simple tutorials), I am proposing a more “unobtrusive” approach consisting of keeping the markup pure and explicitly defining data-bindings separately later (in the view mediator which we’ll see soon in the next section).

Savings Goal Amount:
Savings Max Duration (In Months):
Savings Target Per Month:

At some point in the future, once the number of views increases beyond a couple, we’ll externalize our views as individual [jQuery] template files – but we’ll see the approach in detail later.

Note: as we go along in the tutorial, I will not cover the CSS styling explicitly but you can always get the CSS when downloading the source based on the tag for a given step. Example: tag: part2-todo-2.zip (also available in tar.gz form). Look under for css/application.css

4. Create the Savings Goal ViewModel

If you have not yet created the ViewModels folder under the scripts folder, do that now. And then create a file named: sgs.model.savings-goal.js.

Here is a diagram summarizing what we’re about to implement:

As we indicated earlier, we’ll use namespaces to structure our code and avoid name collisions with other libraries.
There are various approaches for namespacing code in Javascript, some uses object literals, and some use functions as containers for our functions. Elijah Manor has a great summary highlighting the pros and cons of the various approaches.

For our needs and to make it easy to extend and edit our namespace we’ll use the object literals.
To lazy initialize our namespace hierarchy let’s add the following snippet, which checks if each node in our namespace exists and creates it if it is not yet defined.

// Lazy initialize our namespace context: sgs.model.savingsgoal if (typeof(sgs) == 'undefined') sgs = { } if (typeof(sgs.model) == 'undefined') sgs.model = { } if (typeof(sgs.model.savingsgoal) == 'undefined') sgs.model.savingsgoal = { }

Now we can create functions prefixed by our namespace such as for e.g. the function to initialize the view model and its two value models:

sgs.model.savingsgoal.initializeViewModel = function (pageSettings) { // We can use properties of the pageSettings as default values for any of our ValueModels // If pageSettings are not provided we'll initialize an empty object if (typeof(pageSettings) == 'undefined') var pageSettings = { } var viewModel = { savingsGoalAmount: ko.observable(pageSettings.defaultSavingsGoal || 0), // dollars savingsMaxDuration: ko.observable(6), // months }; return viewModel; }

So our viewModel is basically an object literal (hash) where each property value is a value model,
implemented as KnockoutJS observable, essentially a function acting as an interceptor for a value. Everytime the function is acting as a setter, the interceptor notifies all observers (subscribers) of the value change.

Now let’s add a derived function (a.k.a. a dependent observable in KnockoutJS-speak) named savingsTargetPerMonth:

sgs.model.savingsgoal.initializeViewModel = function (pageSettings) { // We can use properties of the pageSettings as default values for any of our ValueModels // If pageSettings are not provided we'll initialize an empty object if (typeof(pageSettings) == 'undefined') var pageSettings = { } var viewModel = { savingsGoalAmount: ko.observable(pageSettings.defaultSavingsGoal || 0), // dollars savingsMaxDuration: ko.observable(6), // months }; viewModel.savingsTargetPerMonth = ko.dependentObservable(function() { var result = 0; if (this.savingsMaxDuration() > 0) { result = this.savingsGoalAmount() / this.savingsMaxDuration(); } return result; }, viewModel); return viewModel; }

Note that ko.dependentObservable takes a function as a parameter as you would expect, but can also take a second optional parameter used to define the meaning of this inside the derived function. Typically we always pass the variable containing our viewModel.

Over time we can add more business logic to our sgs.mode.savingsgoal module.

5. Create the Savings Goal View Mediator

If you have not yet created the ViewMediators folder under the scripts folder, do that now. And then create a file named: sgs.mediator.savings-goal.js.
This is the module where we’ll place our data-binding logic as well as any code related to mediating access between the page, the savings goal view, and its view model.

Here is a diagram summarizing what we’re about to implement:

Let’s define our namespace:

// Lazy initialize our namespace context: sgs.mediator.savingsgoal if (typeof(sgs) == 'undefined') sgs = { } if (typeof(sgs.mediator) == 'undefined') sgs.mediator = { } if (typeof(sgs.mediator.savingsgoal) == 'undefined') sgs.mediator.savingsgoal = { } if (typeof(console) != 'undefined' && console) console.info("sgs.mediator.savingsgoal loading!");

Now as a convention, let’s create a new function for our mediator named createViewMediator
which we will eventually invoke from the InitializeApplication method in application.js.
The createViewMediator function will have 3 responsibilities:

Instantiate a view model for the savings goal view

Declare the data-binding between the HTML elements of the view and their corresponding value models in the view model

Ask KnockoutJS to make the bindings effective (they will be live right after that)

Save off the view model so we can access it from other parts of the app

So let’s implement the first responsibility to instantiate a view model for the savings goal view (using the initializeViewModel function we just created in the savings goal view model module).

sgs.mediator.savingsgoal.createViewMediator = function (pageSettings) { // Create the view Savings Goal view-specific view model var viewModel = sgs.model.savingsgoal.initializeViewModel(pageSettings); }

Now let’s declare each of the 3 data-bindings we need:

sgs.mediator.savingsgoal.createViewMediator = function (pageSettings) { // Create the view Savings Goal view-specific view model var viewModel = sgs.model.savingsgoal.initializeViewModel(pageSettings); // Declare the HTML element-level data bindings $("#savings-goal-amount").attr("data-bind","value: savingsGoalAmount"); $("#savings-max-duration").attr("data-bind","value: savingsMaxDuration"); $("#savings-target-per-month").attr("data-bind","text: savingsTargetPerMonth()"); }

Now we’ll ask KnockoutJS to “apply”, i.e. register / enable our bindings.

sgs.mediator.savingsgoal.createViewMediator = function (pageSettings) { // Create the view Savings Goal view-specific view model var viewModel = sgs.model.savingsgoal.initializeViewModel(pageSettings); // Declare the HTML element-level data bindings $("#savings-goal-amount").attr("data-bind","value: savingsGoalAmount"); $("#savings-max-duration").attr("data-bind","value: savingsMaxDuration"); $("#savings-target-per-month").attr("data-bind","text: savingsTargetPerMonth()"); // Ask KnockoutJS to data-bind the view model to the view var viewNode = $('#savings-goal-view')[0]; ko.applyBindings(viewModel, viewNode); }

This is where KnockoutJS is performing some heavy lifting behind the covers such as:

Setting observers on the actual HTML elements

Connecting these observers with the value models of the view model

Getting the initial value of each value model

Initializing each HTML element with that corresponding initial value

To make it possible to store and retrieve our view model later we’ll leverage the jQuery data API.
So let’s create 2 functions in the savings goal mediator (since it is acting as an intermediate between the browser, page, view and the model:

sgs.mediator.savingsgoal.getViewModel = function() { return $(document).data("sgs.model.savingsgoal.viewmodel"); } sgs.mediator.savingsgoal.setViewModel = function(viewModel) { $(document).data("sgs.model.savingsgoal.viewmodel", viewModel); }

Now we can use the setViewModel function inside createViewMediator to save off our freshly-created view model.

sgs.mediator.savingsgoal.createViewMediator = function (pageSettings) { // Create the view Savings Goal view-specific view model var viewModel = sgs.model.savingsgoal.initializeViewModel(pageSettings); // Declare the HTML element-level data bindings $("#savings-goal-amount").attr("data-bind","value: savingsGoalAmount"); $("#savings-max-duration").attr("data-bind","value: savingsMaxDuration"); $("#savings-target-per-month").attr("data-bind","text: savingsTargetPerMonth()"); // Ask KnockoutJS to data-bind the view model to the view var viewNode = $('#savings-goal-view')[0]; ko.applyBindings(viewModel, viewNode); // Save the view model sgs.mediator.savingsgoal.setViewModel(viewModel); if (typeof(console) != 'undefined' && console) console.info("sgs.mediator.savingsgoal ready!"); }

6. Link the Page and the View Mediator

Here is a diagram summarizing how we’ll be linking our parts:

Ok now we’re at a point to start testing our first draft, we just need to add a call to the overall page InitializeApplication function (located in scripts/application.js) to our savings goal createViewMediator function like so:

function InitializeApplication() { if (typeof(console) != 'undefined' && console) console.info("InitializeApplication starting ..."); // Initialize our page-wide settings var pageSettings = { defaultSavingsGoal: 500 } // Create / launch our view mediator(s) sgs.mediator.savingsgoal.createViewMediator(pageSettings); if (typeof(console) != 'undefined' && console) console.info("InitializeApplication done ..."); }

So now you should be able to load your index.html page in Firefox with the Firebug console on and watch the debug statement and finally our view displays with our initial data as well as the initial derived data for the “Savings Target Per Month” when you tab out of the amount or max number of months input fields:

7. Apply Data Formatting / Masking Business Rules

So far we have a nice simplistic example but if you build a solid app you will want to format and ensure our amounts are correct / valid / displayed according to conventional rules.
To my knowledge (having researched these types of libraries for a while), only library from PengoWorks has currency masking capabilities and will format the amount as you type it.
Since that library stopped being maintained in 2007, I started updating it (after checking with the original author, David Switzer) to make it work with current browsers). The resulting library is called CurrencyMask JS.
So let’s download the latest version to our ./scripts/vendor folder, and add a code snippet in our LAB section:

$LAB // ... .script("scripts/vendor/currency-mask-0.5.0-min.js").wait() .script("scripts/application.js").wait(function(){ // When ALL scripts have been loaded AND executed: InitializeApplication(); });

To apply masking to a field, you instantiate a Mask object with the format you want (e.g. “$#,###” for amounts up to $9,999 without decimals) and you attach it to the targetted HTML element like so:

var savingsGoalAmountMask = new Mask("$#,###", "number"); savingsGoalAmountMask.attach($("#savings-goal-amount")[0]);

Let’s add the mask instantiation snippet to the savings goal view model (at the end of the initializeViewModel function in sgs.model.savings-goal.js). Also note that we will need to perform the initialization of savingsGoalAmount based on pageSettings later on in the mediator – so here we’ll set the default value of savingsGoalAmountFormatted to an empty string:

sgs.model.savingsgoal.initializeViewModel = function (pageSettings) { // ... var viewModel = { savingsGoalAmountFormatted: ko.observable(""), savingsGoalAmountMask: new Mask("$#,###", "number"), // ... }; // ... }

And let’s add the “attach” snippet to the savings goal view mediator in the createViewMediator function in sgs.mediator.savings-goal.js, right after the bindings declarations:

sgs.mediator.savingsgoal.createViewMediator = function (pageSettings) { // ... // Declare the HTML element-level data bindings // ... // Apply masking to the savings goal amount input field viewModel.savingsGoalAmountMask.attach($("#savings-goal-amount")[0]); // ... }

And if we refresh the page and start typing 1500 in the amount it should format as we type along and prevent any other character input, ensuring the amount is valid.

But … we just introduced an issue (see the infamous NAN displayed in the Savings Target Per Month)!
Well, once formatted the savingsGoalAmount value model will now be a string containing currency and thousands delimiter characters.
So let’s recognize that semantic change by re-naming our savingsGoalAmount value model as savingsGoalAmountFormatted value model:

sgs.model.savingsgoal.initializeViewModel = function (pageSettings) { // ... var viewModel = { savingsGoalAmountFormatted: ko.observable(pageSettings.defaultSavingsGoal || 0), // dollars // ... };

Now what we need to re-create a new savingsGoalAmount value model, and make it act as a two-way adapter to convert back and forth between formatted and unformatted values.
KnockoutJS can help us with that, using a “dependentObservable“. KnockoutJS also allows a hash to be passed to ko.dependentObservable. That hash can include the following key-value pairs:

owner – will specify the value of this

read – a function which can perform some post-processing and ultimately return the value of the observable

write – a function which can perform some pre-processing of a value and ultimately store it

So here is a skeleton of what the savingsGoalAmount value model would look like as a dependentObservable:

viewModel.savingsGoalAmount = ko.dependentObservable({ owner: viewModel, read: function () { // some post processing code }, write: function (value) { // some pre processing code } });

Let’s tackle the read function first. It will need to:

Get the current value model from savingsGoalAmountFormatted

Ask the savingsGoalAmountMask for a stripped (unformatted) value

Return a valid float value

Here is what the code looks like for the “read”:

read: function () { // Get the current formatted value model // Important Note: Even though we don't use the formatted_amt variable // in the rest of the function, we need to let KnockoutJS "know" // that this closure has a dependency on savingsGoalAmountFormatted // otherwise the closure will never be invoked on a read. var formatted_amt = this.savingsGoalAmountFormatted(); // Unformat the value var amt = this.savingsGoalAmountMask.strippedValue; // Convert the result to a float if (amt.length == 0) { amt = 0 }; return parseFloat(amt); },

Now let’s tackle the write function first. It will need to:

Ask the savingsGoalAmountMask to format the value

Set the savingsGoalAmountFormatted to the formatted value

Return the passed value

Here is what the code looks like for the “write”:

write: function (value) { // Format the passed in value using the mask var formatted_value = this.savingsGoalAmountMask.updateFormattedValue(value); // Update the savingsGoalAmountFormatted value model this.savingsGoalAmountFormatted(formatted_value); return value; }

The complete and refactored savingsGoalAmount dependentObservable will now look like this:

viewModel.savingsGoalAmount = ko.dependentObservable({ owner: viewModel, read: function () { // Get the current formatted value model var formatted_amt = this.savingsGoalAmountFormatted(); // Unformat the value var amt = this.savingsGoalAmountMask.strippedValue; // Convert the result to a float if (amt.length == 0) { amt = 0 }; return parseFloat(amt); }, write: function (value) { // Format the passed in value using the mask var formatted_value = this.savingsGoalAmountMask.updateFormattedValue(value); // Update the savingsGoalAmountFormatted value model this.savingsGoalAmountFormatted(formatted_value); return value; } });

Now refreshing the index.html page should allow you to enter amounts and see the calculated value!

Here is a diagram summarizing how we restructured the various parts using the dependent observables and the mask:

I will leave the exercise for you dear reader to follow the same pattern for the “Savings Max Duration (In Months)” input field.
In that case the mask will be a little simpler since we need at most 2 digits.

8. Apply Custom Masking Rules

For custom masking needs, such as for example a phone number, social security id, special identifier,
I strongly recommend Josh Bush‘ Masked Input Plugin.

For dates I suggest using Masked Input together with jQuery Datepicker since the calendar makes it easy to select a date but does not provide masking features.

9. Applying Formatting Rules

When using our simple view you might have noticed that the “Savings Target Per Month” may show some numbers with many decimals. This is because the element is data-bound to the savingsTargetPerMonth dependentObservable which returns a float. So we have two options:

Apply formatting to the float inside savingsTargetPerMonth

Or create another dependentObservable named savingsTargetPerMonthFormatted, in which we can apply the needed formatting logic. Then we would change the data binding for the to use our new value model.

The cleanest approach is #2 since it also allows you in the future to build other dependentObservables on top of savingsTargetPerMonth. But if you don’t think you will need that ability then #1 will work and is very simple.

Approach 1 would require us to format the calculated value using the formatMoney function of Accounting.js like so:

var result = this.savingsGoalAmount() / this.savingsMaxDuration(); var formattedResult = accounting.formatMoney(result, "$", 2, ",", "."); ; return formattedResult;

Approach 2 would require us to add a new dependentObservable named savingsTargetPerMonthFormatted in our savings goal view model:

sgs.model.savingsgoal.initializeViewModel = function (pageSettings) { // ... viewModel.savingsTargetPerMonthFormatted = ko.dependentObservable(function() { var result = 0; if (this.savingsMaxDuration() > 0) { result = this.savingsGoalAmount() / this.savingsMaxDuration(); } var formattedResult = accounting.formatMoney(result, "$", 2, ",", "."); ; return formattedResult; }, viewModel); }

And we then need to update the data-binding code in the createViewMediator function of our mediator module:

sgs.mediator.savingsgoal.createViewMediator = function (pageSettings) { // ... $("#savings-target-per-month").attr("data-bind","text: savingsTargetPerMonthFormatted()"); // ... }

Let’s refresh the index.html page and now when we enter $500 and 7 months, the max per month updates to dollar formatted two-decimal amount: $71.43!

10. Applying Visual Feedback Cues

When web pages require a round-trip to the server, the user waits and then sees the whole page refreshing, but in rich interactive apps since processing happens often very fast without a page refresh, we need to provide visual cues when changes occur. For quick feedback logic (e.g. not requiring an Ajax call or processing longer than a second) I recommend using a jQuery UI “effect”, such a temporary highlight using a soft color, like so:

$("#savings-target-per-month") .effect('highlight', { color: 'LightGreen' }, 3000); // for 3 seconds

Logically the code belongs to the mediator, so let’s subscribe to the savingsTargetPerMonthFormatted value model changes
inside our createViewMediator function.

sgs.mediator.savingsgoal.createViewMediator = function (pageSettings) { // ... // Subscribe to interesting value model changes viewModel.savingsTargetPerMonthFormatted.subscribe(function() { $("#savings-target-per-month") .effect('highlight', { color: 'LightGreen' }, 3000); // for 3 seconds }); // ... }

Let’s refresh index.html, and whenever we see the xxx recalculate, the light green highlight of the result should fade in and out during our 3-second timeframe!

Overall Recap

So at this point we have built a reasonably solid foundation for our app even though it contains only one view. The architectural steps we took to decouple view, viewmodel, view mediator and the page will yield some benefits once we add continue adding features to our app (in part 3).
So here is a quick recap of the steps we followed:

# To Do Area (Module)

1 Create a Shell Application Main app

2 Organize your Application Code Main App

3 Break down each independent panel into Views View

4 Create a ViewModel for each View View Model

5 Create a View Mediator for each View View Mediator

6 Link the Page and the View Mediator(s) Main App

7 Apply Data Formatting / Masking Business Rules View

8 Apply Custom Masking Rules View Mediator

9 Applying Formatting Rules View Mediator

10 Providing Visual Feedback Cues View Mediator

So What?

Many KnockoutJS tutorials focus on giving you the basics to run simple scenarios. My approach here although more “architected” is geared at building rich interactive apps made of multiple panels/views with solid interactions.

The modularization of our code base will also lend itself better to unit testing and even BDD testing using Javascript test frameworks like Jasmine and Jasmine-Species. They will allow us to write tests against our view models and to a certain degree some of the various Javascript modules.

We have focused on a one-view increment for the app but in Part 3 we will cover the following topics:

Adding more views, viewmodels and mediators to our basic app

Sharing data across views and mediators

Implementing masking and formatting

Incorporating rudimentary elements of usability

… and more!

So stay tuned!

References and Resources

Patterns

Model View – ViewModel Pattern

MVC Xerox Parc 1978-79

MVC Pattern

Observer Pattern

Publish Subscribe Pattern

Value Model Pattern

Data Binding Pattern

Summary of Namespacing Approaches (by Elijah Manor)

Namespacing using Object Literals

Namespacing using Functions

Frameworks And Blogs

KnockoutJS

Learn KnockoutJS (Interactive Tutorial / Playground)

jQuery

jQuery UI

jQuery Template

jQuery Template API

Knock Me Out (Steve Sanderson’s Blog)

Knock Me Out (Ryan Niemeyer’s Blog)

Patterns For Large-Scale Javascript Architecture (Addy Osmani)

Javascript Loaders

HeadJS

LABjs

LazyLoad

jQuery Cookie

jQuery Plugins

jQuery BlockUI

jQuery Cookie

jQuery DataTables

jQuery HotKeys

jQuery jsTree

jQuery Validate

Other Javascript Libraries

Modernizr

BlockUI

Accounting.js

CurrencyMask JS

Masked Input

Raphael JS

gRaphael JS

jStorage

Underscore

Ajax Fixtures

Javascript Test Frameworks

Jasmine, BDD for Javascript

Jasmine Species, BDD Grammar Extensions (Given, When, Then, etc.)

My Other Related Posts:

Creating Rich Interactive Web Apps With KnockOut.js – Part 1

Creating Rich Interactive Web Apps With KnockOut.js – Part 3

Full Source Of The Savings Goal Simulator (KnockoutJS Demo)

The whole application is available on Github under techarch / savings-goal-simulator.

Credits

Special thanks for Thibaut Barrère and Susan Potter for their feedback while I was working on drafts for this tutorial! :-)

If you enjoyed this post, I would love it if you could check out mySkillsMap, my skills management app.

Creating Rich Interactive Web Apps With KnockoutJS – Part 1

techarch — Sat, 17 Sep 2011 21:35:28 +0000

Intro

With the advent of online games, social apps, Flash/AIR apps, and rich instant-feedback sites
like Google Search and GMail, consumers are demanding more and more interactivity.

While interacting with your app customer now expect:

Browser-side processing (calculation, business rules, …)

Instant validation

Instant visual feedback: animation/effect while making changes (add/remove/update)

Dynamic clues on what to do next

More same / on page functionality (without the need to refresh or navigate to other pages)

For a while adding a sprinkling of AJAX and localized visual refresh using jQuery UI was sufficient.
But richer application interactions introduce more elaborate technical approaches:

Present more related data at the same time

Leverage graphs and other data visualization techniques

Offer more on-page functionality

Allow interactions with one panel to cause updates on other panels

Support asynchronous back-end interactions

Extending the Model View Controller Pattern

Here is a reminder of what typically happens in a traditional MVC web app (e.g. Ruby On Rails, Ruby Camping, ASP.NET MVC, Cake PHP, Django Python, etc.):

The routing engine identifies the appropriate controller

The controller retrieves the model

The view engine renders the view

The view contains HTML, CSS, and Javascript code

Rich browser-side applications typically have event handlers to allow page-level interactions to
handle validation, hide/show elements, perform some processing / calculations, executebusiness rules, invoke AJAX services, update content

Note that the last bullet represents quite a bit of logic (possibly in the 500 to several thousand lines of Javascript code).
The logic gets even more complex once you have multiple panels and sets of model elements.
If your AJAX services return complex objects you also need to keep track of these objects,
their binding to panel elements/controls, and their inter-dependencies / impact on each other when a change occurs.

Key take-away:
We need to organize our browser-side code (markup, CSS, and JS) according to their concern, i.e. model representation, business rules, display, user interaction, event handling, server interaction, etc..

This is where the notion of ViewModel and Observables come in to help us out.
Let’s break things down:

The ViewModel is a specialized browser-side Javascript model representing a group of data elements a given page or panel (View) will display or facilitate interaction with.

Benefits:

Partitioning: each page / page can have its own clean model

Testability: the View and ViewModel can be tested independently from the server logic

Modularity: ViewModels code can be namespaced and contained in their own .js file

Each attribute of a ViewModel will be mapped to an Observable so that any value change can be broadcasted (a.k.a. “published” in the publish/subscribe terminology) to any interested subscriber. (So essentially a ViewModel attribute is what is called a Value Model)

Benefits:

Fast UI: derived values or content can be produced on-the-fly based on observed attributes

Increased responsiveness: asynchronous server interactions can be triggered in the background and cause ViewModels to be updated

The scenario where a UI element subscribe to a ViewModel attribute (Value Model) is known as “Data-Binding“.
This allows a clean separation between logic related to the ViewModel (calculations, derivations, retrieval, server interaction) and UI-specific presentation logic.

Benefits:

Synchronization: HTML elements and ViewModel attributes are kept in synch

Instant visual feedback: elements on the page can update visually as you interact / update data

Introducing KnockOutJS

KnockOutJS is a Javascript framework created by Steve Sanderson to provide support for ViewModel, Observable, and Data-Binding using jQuery.
For more details, check out the KnockOutJS site as well as the Learning Playground.
Let’s dig into the basic infrastructure provided by KnockOutJS and then we’ll build up to more complex scenarios.

Basics

In KnockoutJS, a ViewModel is defined as a Javascript Object Literal. Value Models are defined using ko.observable() and an initial value as follows:
var viewModel = { savingGoalAmount: ko.observable(500), // dollars // ... more attributes ... };

The example ViewModel has one attribute: savingGoalAmount, with an initial value of 500.

You can programmatically “subscribe” to changes in a ViewModel attribute (a Value Model) like this:
// Set up the ViewModel var viewModel = { savingGoalAmount: ko.observable(500), // dollars // ... more attributes ... }; viewModel.savingGoalAmount.subscribe(function(newValue) { // Show the updated value on the FireBug's console console.info("savingGoalAmount is now " + newValue); }); // Get KnockoutJS to apply bindings / subscriptions ko.applyBindings(viewModel); // Test by changing the amount viewModel.savingGoalAmount(600); // Should display in the console

The subscribe function takes a callback function it will invoke upon any change on the value of the savingGoalAmount Value Model.
The ko.applyBindings function tells KnockoutJS to start the dependency tracking. From that point on all subscribers will be notified of any changes.

KnockoutJS makes it easy to setup data binding between any HTML element (e.g. INPUT) and a ViewModel attribute (Value Model) using the data-bind syntax and the value: keyword

KnockoutJS uses the data-bind attribute to let us specify the type of binding needed.
In this example we’re binding the value of the INPUT element to the savingGoalAmount Value Model.
We’ll see later on that there are other types of data-binding such as specific attributes, visibility, styling, etc. although you can see the full reference in the documentation.

Note that the data-bind syntax is just “syntactic sugar” for use in our markup. If you prefer a clean separation between markup and Javascript, you can declare your data-bindings like so:

$("#saving-goal-amount") .attr("data-bind","value: savingGoalAmount");

You just need to make sure these declarations are performed before you get KnockoutJS to apply the bindings (using ko.applyBindings).

You can play and run the examples above on this jsFiddle.net page.

Building Up

Now that we have a basic understanding of KnockoutJS, let’s add a few more building blocks:

If a ViewModel attribute needs to store an array, KnockoutJS provides a specialized type of Observable called an ko.observableArray:
var viewModel = { savingGoalObjectives: ko.observableArray([ 'Discretionary', 'Expensive Purchase', 'Investment']), // ... more attributes ... };

Adding / removing items in the array will cause KnockoutJS to trigger an update to all observers of this Value Model.

In addition to attributes (Value Models), ViewModels can expose “behaviors” such as:

Derived attributes, resulting from a calculation, or a business rule.
KnockoutJS refers to them as dependentObservables:

var viewModel = { savingGoalAmount: ko.observable(500), // dollars savingMaxDuration: ko.observable(6), // dollars // ... more attributes ... }; // Derived data viewModel.savingTargetPerMonth = ko.dependentObservable(function() { return this.savingGoalAmount() / this.savingMaxDuration(); }, viewModel)

Whenever either savingGoalAmount or savingMaxDuration change, the derived savingTargetPerMonth function will be re-evaluated.
If savingTargetPerMonth is data-bound to the UI, the corresponding element will redisplay.
Note that you can create dependentObservable functions on top of dependent observables or plain observables!

Formatted version of the data
var viewModel = { savingGoalAmount: ko.observable(500), // dollars // ... more attributes ... }; // Derived formatted display data viewModel.savingGoalAmountAsCurrency = ko.dependentObservable(function() { return accounting.formatMoney(this.savingGoalAmount(), "$", 2, ",", "."); ; }, viewModel)

Above is an example using the Accounting.js library to format our savingGoalAmount Value Model within our dependent observable so that we can display a nicely formatted currency representation on the UI.

Add / remove logic on arrays
var viewModel = { myItems: ko.observableArray(), // ... more attributes ... }; // Add / remove behaviors viewModel.addItem = function (newItem) { var valid = validateItem(newItem); // custom logic if (valid) { this.myItems.push(newItem); } }

In this example, addItem is a custom behavior attached to the ViewModel which can be invoked to add new valid items.

Any other business logic related to an overall ViewModel
var viewModel = { savingGoalAmount: ko.observable(500), // dollars // ... more attributes ... }; viewModel.reset = function() { this.savingGoalAmount(500); }

To allow other parts of our browser-side logic to access our ViewModels, we need to have a way to access them.
We can save ViewModels in the DOM, either at the document level or at a panel level using the jQuery.data API:

var viewModel1 = { } var viewModel2 = { } ko.applyBindings(viewModel1); ko.applyBindings(viewModel2); $(document).data("MyDocumentViewModel", viewModel1); $("#my-panel").data("MyPanelViewModel", viewModel2);

This allows us to access a specific ViewModel later, outside data-binding logic (e.g. in an event handler) like so:

var viewModel1 = $(document).data("MyDocumentViewModel"); var viewModel2 = $("#my-panel").data("MyPanelViewModel");

To keep our code organized we’ll want to create accessor functions such as for example:

MyApp.Model.GetMyDocumentViewModel = function() { return $(document).data("MyDocumentViewModel"); } MyApp.Model.SetMyDocumentViewModel = function(viewModel) { $(document).data("MyDocumentViewModel", viewModel); }

So that we can just access our ViewModel from other modules:

// Initialization var viewModel = { } ko.applyBindings(viewModel); MyApp.Model.SetMyDocumentViewModel(viewModel); // Later on in a different module: MyApp.Model.GetMyDocumentViewModel() .savingGoalAmount.subscribe(myCallBackFunction);

The attributes (Value Models) of the ViewModel can be updated using data returned by an AJAX call to a controller
$.getJSON('ajax/myapi.json', parms, function(data) { // Assumption: we have saved the original viewModel var viewModel = $(document).data("MyViewModel"); viewModel.savingGoalAmount(data.amount); });

The ViewModel can also aggregate a subset of attributes from one or even several server-side [MVC] Models

Arbitrary Javascript functions can also subscribe to Value Model changes:
// Set up the ViewModel var viewModel = { savingGoalAmount: ko.observable(500), // dollars // ... more attributes ... }; function GraphSavingScenario(newValue) { // some graphing logic } viewModel.savingGoalAmount.subscribe(GraphSavingScenario);

So What?

KnockoutJS can help organize browser-side logic by facilitating the creation of panels (Views),
each logically data-bound to ViewModels built on top of a local publish/subscribe mechanism using Observables.
Data-binding, combined with derived data / behaviors, and AJAX will boost the interactivity level of the application.

Part 2 of the series on “Creating Rich Interactive Web Apps” will be a tutorial on how to build a moderate complexity application with KnockoutJS.
We will cover the following topics:

Enabling / disabling rules

Condition display

Leveraging jQuery templates

Extracting views into templates

… and more!

So stay tuned!

References and Resources

Patterns

Model View – ViewModel Pattern

MVC Xerox Parc 1978-79

MVC Pattern

Observer Pattern

Publish Subscribe Pattern

Value Model Pattern

Data Binding Pattern

Frameworks And Blogs

KnockoutJS

Learn KnockoutJS (Interactive Tutorial / Playground)

jQuery

jQuery UI

jQuery Template

jQuery Template API

Knock Me Out (Steve Sanderson’s Blog)

Knock Me Out (Ryan Niemeyer’s Blog)

Patterns For Large-Scale Javascript Architecture (Addy Osmani)

Source Of The KnockoutJS Examples

You can find the examples on jsFiddle.net here:

Basics – Example 1

Building Up – Example 1

Leverage Twitter Features In Your Ruby Application With Twitter4R

techarch — Fri, 18 Mar 2011 03:24:08 +0000

Intro

A few years ago I integrated Twitter with a Ruby application, mainly to display a subset of my timeline.
Later I added the ability to post tweets. All this became possible using Susan Potter‘s “most-excellent” Twitter4R gem.

Back in late 2010, Twitter upgraded its API from simple id/password authentication to OAuth authentication. The Twitter4R gem was then also enhanced to leverage the OAuth-Ruby library. I had created a to-do item to go back and upgrade my apps so this past week I decided it was time to document the process in a quick tutorial!

Twitter4R Approach

When you register your client application with Twitter, you are assigned an App OAuth Token consisting of a consumer key and consumer secret pair. Your app will configure Twitter4R to use this app token during all API calls with Twitter.

Your app will also need to keep track of User OAuth Tokens and pass a specific user token through the API.
Behind the scene Twitter4R will perform REST calls to the actual Twitter API using JSON data.

If you only want your app to access your own account, you will create an Access Token for your Twitter account on your newly-registered app

Playing With Twitter4R In The Console

Installing Twitter4R

From a command window / shell, just run:

gem install oauth

Notice that both the Twitter4R and the OAuth gems are installed.

Registering Our App With Twitter

To obtain a consumer key and secret pair, we’ll need to register our application with Twitter at https://dev.twitter.com/apps. We will need to provide the following:

The name of our app (which must be unique within Twitter’s app registry)

A description

The base url of our app

The url to redirect authenticated users to in our app

The type of access needed: read or read/write (if we want to be able to update our status)

Example:

Obtaining Your Own User OAuth Access Token

Once you have registered the app, if you click on the “My Access Token” button, Twitter will give your OAuth user key and secret token.
Example:

In another section we’ll see how to authorize a user and get its access token programmatically.

Testing Twitter4R In IRB

Let’s start a Ruby console using IRB and load Twitter4R:

gem 'twitter4r' require 'twitter' require 'twitter/console'

Now we can configure the Twitter4R client using the Twitter::Client.configure class method.
The block allows us to customize the application and its app OAuth token. Evaluate the following code snippet:

Twitter::Client.configure do |conf| # App configuration conf.application_name = 'BeaconPulse)))' conf.application_version = '1.0' conf.application_url = 'http://beaconpulse.heroku.com/' # App OAuth token key/secret pair conf.oauth_consumer_token = "***YourAppConsumerKeyFromYourTwitterAppRegistration***" conf.oauth_consumer_secret = "***YourAppConsumerSecretFromYourTwitterAppRegistration***" end

We can then inspect the resulting configuration using:

cfg = Twitter::Client.config

Instantiating A Twitter4RClient

We’ll use the user key/secret pair we looked up on the Twitter Access Token page earlier:

client = Twitter::Client.new(:oauth_access => { :key => "***YourUserOAuthAccessTokenKey***", :secret => "***YourUserOAuthAccessTokenPassword***" })

Taking Twitter Features For A Spin

Now that we have a client instance, we can exercise its various methods (see rdoc for details) such as:

user information about a given account:
i = client.user 'techarch'

my info / friends / followers:
fr = client.my :friends fo = client.my :followers

timeline_for me / user / public / friends / :
tm = client.timeline_for :me tm1 = client.timeline_for :me, :count => 1 # my last tweet tu = client.timeline_for :user, :id => 'susanpotter' tp = client.timeline_for :public tf = client.timeline_for :friends

post a status:
t = client.status :post, 'Posting tweets from IRB using the Twitter4R gem rocks!'

As you can see you can have a lot of fun with the client!

Authorizing A User And Getting Its Access Token

In an earlier section, we just looked up our own access token on the Twitter page for our app registration.
But to allow any user to access our app we would need to:

Instantiate an OAuth Consumer (like Twitter4R does behind the scenes) with our app consumer key/secret pair:
# we reuse the cfg variable we set earlier since it contains our app configuration k = cfg.oauth_consumer_token s = cfg.oauth_consumer_secret u = "#{(cfg.protocol == :ssl ? :https : cfg.protocol).to_s}://#{cfg.host}:#{cfg.port}" oc = OAuth::Consumer.new(k ,s, :site=> u)

Ask the OAuth consumer to:

create an OAuth RequestToken (a temporary credential token used to authenticate our consumer app on Twitter)

and give us an authorization url:

rt = oc.get_request_token auth_url = rt.authorize_url

We can actually paste this url in a browser.

Redirect the user to the authorization url so that Twitter can prompt for authorization to access our app

Once authorized, get the OAuth Verifier (a verification code which will be passed back to Twitter in subsequent requests)

User the Request Token to retrieve an OAuth AccessToken (the actual authorized user token needed for all future API calls to Twitter) for the user based on the OAuth Verifier:
at = rt.get_access_token(:oauth_verifier=>'***ThePINnumberReturnedByTwitter***') user_key = at.token user_secret = at.secret

Optionally store the user OAuth key/secret pair so we can instantiate a Twitter4R Client to invoke APIs on the user’s behalf:
client = Twitter::Client.new(:oauth_access => { :key => user_key, :secret => user_secret }) info = client.user 'techarch'

Approach For Integrating Twitter4R In Your App

Now that you have a handle on the basics using the Interactive Ruby Console, you can check out the full RDoc
and add Twitter support to your favorite Ruby app. In a future blog post I’ll cover the integration approach for a Ruby Camping web app.

Here is what the Twitter4R ecosystem looks like from 50,000 feet:

So What?

Since Twitter has moved to OAuth you need a robust and efficient library like Twitter4R to integrate Twitter in your application.
Twitter4R leverages the Twitter REST API using the JSON format to limit bandwith consumption.
The gem is “framework-neutral”, so it can be used in pure Ruby apps, as well as on top of frameworks such as Rails, Ruby-Camping, and Sinatra.
If you have not experimented with Twitter4R, hopefully this tutorial will get you started.

References and Resources

Twitter4R

Twitter4R on GitHub

Susan Potter’s blog

“Configuring Your Twitter4R App With OAuth” by Susan Potter – on SlideShare

OAuth And My Other Related Posts:

OAuth.net site

OAuth Universe site

OAuth Ruby on GitHub

Transform Your Ruby Camping Web App Into An OAuth Provider (explains the OAuth “dance”!)

Ruby Camping Framework

If you enjoyed this post, I would love it if you could check out mySkillsMap, my skills management app.

Improving Web Conversions In 3 Key Steps

techarch — Sun, 09 Jan 2011 15:00:05 +0000

Intro

I am a huge fan of the TechZing podcast, a show focused on bootstrapped web entrepreneur.
In the last couple months Jason Roberts and Justin Vincent
have had a series of interviews focused on improving usability, web analytics.
The latest show (#98) includes Lance Jones as a guest and focuses on Conversion Optimization.

After listening to the show while driving I decided to replay it once more and take notes as I think it brings a lot of value for any web entrepreneur!
And since I could not fit all the contents and links in the comments I decided to create this short post. Enjoy!

The 3-Step Process

Before starting any A/B test or optimization it is important to really think through the goals and key performance indicators you want to optimize for.
Otherwise you will waste a lot of time or may not get meaningful information and probably not achieve your target goals.
To optimize the conversion process you need to:

Track and analyze conversions

Analyze and understand user behavior

Optimize the user experience, the copy (key content), and affect user behavior

It is critical to have enough traffic to get statistically meaningful data from the tests.
You need probably about 100 conversions per bucket or test option.
So assuming different conversion rates you need quite a lot of users entering the funnel:

a 2% conversion rate requires 5000 users

a 5% conversion rate requires 2000 users

etc.

Supporting Tools

Product Comments

Tools to tracking and analyze conversions

Clicky

Google web site optimizer

Crazyegg Includes heatmap

Mixpanel Great for tracking business/user events

Performable Full customer experience and revenue tracking, reverse funnel analysis

Omniture The Cadillac option for large enterprises

Tools to survey and understand user behavior

iperceptions Define quick short surveys to understand user motivations and success

KissInsights Prompt users for one quick simple question

4Q Survey Prompts users for the 4 essential questions about their experience

ForeseeResults Focuses on complete web effectiveness

Opinionlab More sophisticated option with survey modules, reports,

Getting input from real testers

UserTesting Testers narrate their test using video

FeedbackArmy You submit 4-6 questions about your site and you receive 10 answers

5secondtest Testers have 5 seconds to get an impression of your landing page

Tools to optimize the site

Google web site optimizer

SumoOptimize Recent entrant

Optimizely Great wysiwyg editing of your own pages

Unbounce Great for testing different landing pages and starting A/B tests

Visual website optimizer Rich functionality with a great wysiwyg interface

Note: the list above and associated comments are just based on the show, not on an exhaustive analysis of all vendors and products.

So What?

So if you put all the concepts together you get the following approach synopsis:

Web conversion optimization is not “black magic”, try to follow the process highlighted above as well as the tools.
Providing you can generate enough traffic to your site to run multiple iterations, over time you will most likely see a positive change in your conversions.

References and Resources

A/B Testing

A/B Testing Definition on Wikipedia

Effective A/B Testing Basics (by Ben Tilly)

TechZing

TechZing Podcast for web startup entrepreneurs

Jason Robert’s blog

Justin Vincent’s blog

TechZing 98: TZ Interview – Lance Jones / Conversion Optimization

TechZing 92: TZ Interview – Ilya Lichtenstein / insight.io

TechZing 89: TZ Interview – David Cancel / Performable

TechZing 87: TZ Interview – Luke Wroblewski / The User Interface Is The Product

TechZing 79: Patrick McKenzie / The Long Tail of Optimization

My Other Related Posts:

Visualize Application Metrics on NewRelic for your Ruby Camping Application

A/B Test Your Ruby Camping Web App Using ABingo

If you enjoyed this post, I would love it if you could check out mySkillsMap, my skills management app.

A/B Test Your Ruby Camping Web App Using ABingo (Part 2)

techarch — Tue, 14 Dec 2010 07:00:16 +0000

Intro

In “A/B Test Your Ruby Camping Web App Using ABingo (Part 1)”, I introduced the ABingo A/B testing framework and the new Camping ABingo plugin. In this article I will cover the following topics:

Look under the ABingo Hood to understand its API, object model, and underlying database tables

Create a draft of the ABingo Test Application

Integrate ABingo into our test app

Run and analyze experiments

Under The ABingo Hood

Before we can dive in the integration of the Camping ABingo plugin with our prototype application, here is a quick overview of the basics of the ABingo framework.

ABingo API

The two most important APIs are ab_test and bingo!:

API Parameters Context Purpose/Usage

ab_test

test name

optional: array of alternatives

optional: conversion name

View or Controller Select an alternative for the current user based on the alternatives specified for this test. If no alternatives are specified a boolean value is returned. Tracks the execution using the conversion name if provided otherwise use the test name.

bingo!

conversion name (or test name)

Controller Tracks a conversion for the current user and the conversion specified. The test name is the fallback option.

Note: these 2 main APIs are implemented in Camping in a helper module being included in both controllers and views. The ab_test is syntactic sugar over the test method provided by the core Abingo class.

Model

The basic object model for the ABingo framework looks like this:

Model Responsibilities

User The user account on the prototype app

Abingo ABingo’s main API class

Experiment Represents a specific test based on multiple alternatives

Alternative Tracks participants and conversions for a given alternative

ABingo Database Tables

ABingo will need to track executions of your Experiments and their corresponding Alternatives in the database associated with your application. So the ABingo Camping plugin will include the needed migration to add 2 tables to your schema. We’ll see this in more details later.

Create An ABingo Test Application

Install Camping-ABingo

First let’s install the gem. (If you don’t have Camping or any of its dependent gem they will be installed)

gem install camping-abingo

Note: You will find the fully functional test application under the examples/camping-abingo-test folder in the camping-abingo gem folder. If you want to start using it right away, skip the next sections and go straight to Setting Up Our First A/B Test. Otherwise follow along.

Running the Skeleton pre-ABingo Test Application

In the next sections I will show you how to integrate ABingo with the skeleton test app. But before let’s get the skeleton application up and running.

Locate the examples/camping-abingo-test folder under your camping-abingo gem folder.

There are two versions of the test app:

the skeleton (without ABingo support)

the fully implemented version

Open camping-abingo-test-skeleton.rb in an editor.

Then let’s start the Camping server with our skeleton:
camping camping-abingo-test-skeleton.rb

Open a browser and access the skeleton from the browser at the following url:
http://localhost:3001/

Camping will run the first migration to create the table for our User model:

And the basic test app should now come up:

You can now test the basic flow of the application. When viewing the landing page, the sign-up button should always be labeled “Sign-Up Now!”. Once ABingo is integrated we will be experimenting with different alternatives.

Adding ABingo Support To The Skeleton Test App

The ABingo plugin is composed of several modules mirroring the standard modules a typical Camping application would contain.
Integrating the plugin will consist of linking the various modules using a combination of include and/or extend statements where appropriate. Here is a high-level diagram of the integration approach:

Here are the steps we will be following:

# To Do

A Reference and require the needed gems

B Customize the main module

C Plugging in the ABingo common helpers module

D Plugging in the ABingo Experience and Alternative models

E Plugging in the ABingo Dashboard controllers

F Plugging in the ABingo Dashboard views

G Add code to manage the ABingo user identity in our controllers

A. Reference and require the needed gems

We will need to reference 2 gems: filtering_camping and camping-abingo. Also we will require the corresponding files we need: filtering_camping and camping-abingo.So now the top of the source should look like this:

gem 'camping' , '>= 2.0' gem 'filtering_camping' , '>= 1.0' gem 'camping-abingo' %w(rubygems active_record erb fileutils json markaby md5 redcloth camping camping/session filtering_camping camping-abingo ).each { |lib| require lib } Camping.goes :CampingABingoTest

B.Customizing the main module

Ok, so now we’re ready to enhance the main app module. First we’ll make sure to include the Camping::Session and CampingFilters modules, and to extend the app module with ABingoCampingPlugin and its Filters submodule, like so:

module CampingABingoTest include Camping::Session include CampingFilters extend ABingoCampingPlugin include ABingoCampingPlugin::Filters # ... end

We can also associate the logger with our camping-abingo plugin.

Camping::Models::Base.logger = app_logger ABingoCampingPlugin.logger = app_logger

Now let’s customize the create method by adding a call to ABingoCampingPlugin.create, so we can get the plugin to run any needed initialization.

def CampingABingoTest.create ABingoCampingPlugin.create end

We need to more things: let’s link our logger to the ABingo cache logger (to make it easier to debug issues), and let’s define which User id represent the administrator who will have access to the ABingo Dashboard. Now the final version of the create method looks like this:

def CampingABingoTest.create dbconfig = YAML.load(File.read('config/database.yml')) environment = ENV['DATABASE_URL'] ? 'production' : 'development' Camping::Models::Base.establish_connection dbconfig[environment] ABingoCampingPlugin.create Abingo.cache.logger = Camping::Models::Base.logger Abingo.options[:abingo_administrator_user_id] = 1 CampingABingoTest::Models.create_schema :assume => (CampingABingoTest::Models::User.table_exists? ? 1.1 : 0.0) end

Ok, at this point we have a minimally configured application module.

C.Plugging in the ABingo common helpers module

The Helpers module is used in Camping to provide common utilities to both the Controllers and Views modules. Enhancing our Helpers module is very easy, we need to add both an extend and an include of the ABingoCampingPlugin::Helpers module so we can enhance both instance and class sides:

module CampingABingoTest::Helpers extend ABingoCampingPlugin::Helpers include ABingoCampingPlugin::Helpers end

D.Plugging in the ABingo Experience and Alternative models

First, we’ll include the include ABingoCampingPlugin::Models module so we can get all the ABingo-specific models. Our model will look like this:

module CampingABingoTest::Models include ABingoCampingPlugin::Models # ... end

Now we’ll enhance the CreateUserSchema migration class to plug in our ABingo model migration.

We’ll bump up the migration version number of the CreateUserSchema class to 1.1

In the up method we will add a call to ABingoCampingPlugin::Models.up so that the Experience, Alternative tables can be created.

In the down method we will add a call to ABingoCampingPlugin::Models.down to drop the ABingo tables.

class CreateUserSchema < V 1.1 def self.up create_table :CampingABingoTest_users, :force => true do |t| # ... end # ... ABingoCampingPlugin::Models.up end def self.down ABingoCampingPlugin::Models.down drop_table :CampingABingoTest_users end end

Now if we restart the application, our version 1.1 migration should be executed:

E.Plugging in the ABingo Dashboard controllers

We will need to extend our app Controllers module with the ABingoCampingPlugin::Controllers module using the extend statement. Then just before the end of the Controllers module, we’ll add a call to the include_abingo_controllers method. This is how camping-abingo will inject and plugin the ABingo Dashboard controllers and helpers. It is important that this call always remaining the last statement of the module, even when you add new controller classes. So the module should look like so:

module CampingABingoTest::Controllers extend ABingoCampingPlugin::Controllers # ... include_abingo_controllers end #Controllers

F.Plugging in the ABingo Dashboard views

We will need to extend our app Views module with the ABingoCampingPlugin::Views module using the extend statement. Then just before the end of the Views module, we’ll add a call to the include_abingo_views method. This is how camping-abingo will inject and plugin the ABingo Dashboard views. It is important that this call always remaining the last statement of the module, even when you add new view methods. So the module should look like so:

module CampingABingoTest::Views extend ABingoCampingPlugin::Views # ... include_abingo_views end

G.Add code to manage the ABingo user identity in our controllers

ABingo tracks the selected experiment alternatives and potential conversions for a given user using a property named identity. Currently the ABingoCampingPlugin::Filters we included in our main module provides a filter that executes before all controllers. That filter is responsible for ensuring the Abingo.identity is set using either a large random integer if the user is anonymous, or the actual id of an existing user. Here is what the filter looks like:

before :all do set_abingo_identity end

To handle non-anonymous users and for our integration with our controllers to be complete we will need to:

Set the identity to the new user’s id once signup is complete.
So in the post action of our SignUp controller, let’s set the @state.abingo_identity to our user’s id before rendering the Welcome view – see line 14:

class SignUp < R '/signup' # get ... def post @user = User.find_by_username(input.username) if @user @info = 'A user account already exist for this username.' else @user = User.new :username => input.username, :password => input.password @user.save if @user @state.user_id = @user.id @state.abingo_identity = @user.id redirect R(Welcome) else @info = @user.errors.full_messages unless @user.errors.empty? end end render :signup end end

Replace the abingo_identity with the user’s id (@user.id) when someone signs-in. See line 9:
class SignIn < R '/signin' # ... def post @user = User.find_by_username_and_password(input.username, input.password) if @user @state.user_id = @user.id @state.abingo_identity = @user.id if @state.return_to.nil? redirect R(Welcome) else return_to = @state.return_to @state.return_to = nil redirect(return_to) end else @info = 'Wrong username or password.' end render :signin end end

Generate a new random identity when the current user has signed-out.
So let's set the @state.abingo_identity to another large random integer in the get action of our SignOut controller. See line 4:

class SignOut < R '/signout' def get @state.user_id = nil @state.abingo_identity = Abingo.identity = rand(10 ** 10).to_i render :index end end

Now our integration steps are complete. We're now ready to do some A/B testing!

Setting Up Our First A/B Test

Selecting A Random Alternative For a Given Experience

For our first experiment named call_to_action we'll vary the text for our signup_btn button by selecting one of 3 alternatives based on the user.

So let's modify the landing view of our test application. We'll change the assignment of the signup_text variable to the result of the ab_test call. So our code will look like the following (with the ab_test call on line 9):

def landing div.xyz do h1 'XYZ SAAS Application' div.marketing! do # benefits ... div.actnow! do signup_text = ab_test("call_to_action", [ "Sign-Up Now!", "Try It For Free Now!", "Start Your Free Trial Now!", ]) a :href=>"/signup" do div.signup_btn! signup_text end end end end end

Recording A User Conversion

If we ran the application now ABingo would choose an alternative and keep track of it in terms of user participation.
So now we just need to record an actual conversion for the call_to_action test when the user clicks on the signup_btn button.

To do that, we'll enhance the get action of our SignUp controller by calling the bingo! API with call_to_action as the name of the test. See line 3 below:

At this stage, we have a basic Camping ABingo-enabled application, now let's test it!

Running Our First A/B Test

So let's refresh the browser - if you stopped the Camping server then restart it (as a note Camping automatically reloads your changes). You have two in three chances to get a different alternatives than our original hard-coded text:

Let's look at the content of our camping-abingo-test.db SQLite database (preferably with Lita, an AIR-based SQLite administration tool):

Note that the number of participants for the displayed alternative is 1.

If you are using FireBug with FireCookie, delete the campingabingotest.state and refresh the page. You should notice that the abingo_identity should change as well as the button text. Repeat the process several times. And occasionally click on the button to cause a conversion to occur.
Let's refresh our table contents in Lita:

Note that the number of participants and conversions have increased across alternatives.

Viewing A/B Test Results With The ABingo Dashboard

Checking the database for our results is quite tedious (even with Lita!), luckily ABingo has a built-in Dashboard. Our Camping ABingo plugin has already defined a couple controllers and routes. We just need to expose the main /abingo/dashboard route.

So let's go to the layout method of our ABingo Test app. Right below the link for Sign-Out let's add a code fragment to only show a link to if the id of the current signed-in user is the id of the allowed ABingo Administrator (using the abingo_administrator_user_id ABingo helper method). See lines 7-10:

def layout html do # ... a "Sign-Out", :href=>'/signout' if @state.user_id == abingo_administrator_user_id span " | " a "ABingo Dashboard", :href=>"/abingo/dashboard" end # ... end end

Now let's sign-in as the default administrator for our app. Use admin for the id and camping as the password. You should now see a "ABingo Dashboard" link in the top right of the navigation bar. Click on it. The dashboard should now show you the results:

Now it is easy to see the results and even terminate a given alternative if we want to.
Note: each experiment you have defined will be listed with its corresponding details.

Choosing Your Caching Mechanism

By default the ABingo Plugin initialize its cache based on a :memory_store. This is fine and easy to troubleshoot our simple test app. But for your application you should consider a more advanced caching mechanisms - see the ActiveSupport Cache documentation. One suggestion is to use Memcached if possible (e.g. on Heroku).

So What?

Patrick McKenzie's ABingo is a powerful A/B testing framework for Ruby apps.

ABingo makes it easy to define and execute experiments with multiple alternatives.

The ABingo Dashboard makes interpreting test results a breeze!

So hopefully this second post on ABingo (see here for the first post of the serie) will have given you a feel for how easy it is to A/B test-enable a Ruby Camping-based web application using the Camping ABingo plugin.

Happy ABingo A/B experiments!!!

Note: You can try the demo app yourself at: camping-abingo.heroku.com (including the ABingo Dashboard if you sign in as admin / camping).

In a subsequent post I will cover some advanced topics (caching, troubleshooting, multi-variates, etc.) for Camping ABingo. Stay tuned!

References and Resources

A/B Testing

A/B Testing Definition on Wikipedia

Effective A/B Testing Basics (by Ben Tilly)

Google Website Optmizer

ABingo A/B Testing Framework (by Patrick McKenzie)

Patrick McKenzie's Blog

Patrick McKenzie Interview On TechZing Podcast

Camping

Ruby Camping Framework

Camping-ABingo repository on GitHub

Camping-ABingo Demo On Heroku

Miscellaneous

TechZing Podcast for web startup entrepreneurs

Lita, a SQLite administration tool

My Other Related Posts:

A/B Test Your Ruby Camping Web App Using ABingo (Part 1)

Visualize Application Metrics on NewRelic for your Ruby Camping Application

Source Code

All source is available on GitHub:

Camping ABingo Plugin library
Camping ABingo Test Example

If you enjoyed this post, I would love it if you could check out mySkillsMap, my skills management app.

A/B Test Your Ruby Camping Web App Using ABingo (Part 1)

techarch — Thu, 02 Dec 2010 05:13:31 +0000

Intro

Over the past few months, while listening to TechZing, a fantastic podcast for web startup entrepreneurs, the concept of A/B Testing keeps coming up as key technique to track and measure conversion of site visitors into potential or true customers. Performing A/B testing implies:

Selecting content variations or use case variations to test

Identifying a couple alternatives for each test (a.k.a. experiments)
Example of an experiment on the wording of a call to action button:

Trigger a test on a given page by selecting an alternative for a given user

Track any resulting conversion for a given user on a targetted page

Measure the participation in our tests

Measure the conversion in our tests

Click here if you want to skip straight to the ABingo Camping Plugin source code

A/B Test Solutions

Google provides very basic A/B Testing capabilities as part of the Google Analytics Website Optimizer. The downsides of that approach are:

The tests (experiments), their alternatives, and corresponding urls have to be defined on the Google site

The resulting “test tracking Javascript snippets” have to be copy/pasted inside your own site

All the data remains locked in Google’s databases (although you can export it)

If your web application is built on Ruby on Rails, you are in luck, as Patrick McKenzie has created ABingo, an excellent A/B testing framework plugin. ABingo even includes a dashboard to view the test participations and conversions.

Since I am a big fan of the lightweight Ruby Camping Micro-Framework, what I needed was an ABingo Camping plugin. Since none existed I emailed Patrick McKenzie to get his blessing and started to adapt his plugin!

Starting With The End In Mind

ABingo Test Application

To illustrate the usage of ABingo, we’ll use a simple tester representing a fictitious SAAS Application. From the home page we’ll be able to access the landing and corresponding sign-up pages that we want to experiment with.

We’ll also provide sign-in/sign-out options and a link to the ABingo dashboard if the signed in user is the administrator.

Objective: Increasing Our Sign-Ups

To increase our sign-ups we will be experimenting first with different calls to action in our sign-up button.
Our experiment named call_to_action will randomly vary the text of the button. We track the selected option and track the conversion on our sign-up page. After running our experiment for a while we will be able to see on the dashboard which option generated the most conversion!

The Conversion Funnel

The path taken by a group of customers from the various options (A/B/C) of the landing page to our sign-up page is called a conversion funnel:

High-Level Implementation Synopsis

Once ABingo is integrated in your application, tracking and measuring the conversion funnel will consist of 2 basic steps:

Selecting an alternative for a given experiment

In the landing view code we will invoke the ABingo ab_test API to choose an alternative for the call_to_action experiment based on an array of text options:

def landing # ... signup_text = ab_test("call_to_action", [ "Sign-Up Now!", "Try It For Free Now!", "Start Your Free Trial Now!", ]) a :href=>"/signup" do div.signup_btn! signup_text end # ... end

It’s that easy! And as a side note an experiment alternative can be a simple boolean, an array of arbitrary values, or even a hash of options.

Tracking the conversion for our experiment

In the SignUp controller, before rendering the signup view we will invoke the abingo! API to indicate that a conversion just occurred on our call_to_action experiment:

class SignUp < R '/signup' def get bingo! "call_to_action" render :signup end end

Fun With Experiments!

Now that you have seen how ridiculously simple it is to setup and track an experiment you'll want to try to run different types of experiments such as for example:

different styles (size, color) for the sign-up button

special offers

different ways to present pricing options

etc.

Example of a landing page with a special_promo experiment:

Reviewing A/B Test Results With The ABingo Dashboard

The dashboard consists of a couple routes built using Camping controllers and views. Although we will walk through the setup of such a dashboard in our prototype app in a later article, here is a teaser screenshot:

The conclusions we can draw from these experiments are:

For the special_promo experiment, the "true" alternative results in the most conversions (%)

For the call_to_action experiment, the "Start Your Free Trial Now!" alternative results in the most conversions (%)

You can try the demo app yourself at: http://camping-abingo.heroku.com/.

So What?

A/B testing is a key practice to improve usability as well as user conversion on a web application.

Patrick McKenzie's ABingo is a powerful A/B testing framework for Ruby apps.

ABingo makes it easy to define and execute experiments with multiple alternatives.

This introduction to ABingo should have given you a feel for how easy it is to add A/B testing capabilities to a Ruby Camping web application using the ABingo Camping plugin.
In a subsequent post I will cover the specific implementation steps to add ABingo to our test application. Stay tuned!

Source Code

All source is available on GitHub:

Camping ABingo Plugin library
Camping ABingo Test Example

References and Resources

A/B Testing

A/B Testing Definition on Wikipedia

Effective A/B Testing Basics (by Ben Tilly)

Google Website Optmizer

ABingo A/B Testing Framework (by Patrick McKenzie)

Patrick McKenzie's Blog

Patrick McKenzie Interview On TechZing Podcast

Camping

Ruby Camping Framework

Camping-ABingo repository on GitHub

Miscellaneous

TechZing Podcast for web startup entrepreneurs

Lita, a SQLite administration tool

My Other Related Posts:

Visualize Application Metrics on NewRelic for your Ruby Camping Application

If you enjoyed this post, I would love it if you could check out mySkillsMap, my skills management app.

Implementing Ruby Camping REST Services With RESTstop

techarch — Wed, 23 Jun 2010 04:50:47 +0000

Intro

It is pretty common nowadays for web applications and sites to expose a developer API to allow consumers to integrate their data with other application. Examples: Twitter, LinkedIn, Bit.ly, etc.

Although there are various options for implementing web services, as of 2010, the REST protocol seems to have achieved a comfortable lead over other approaches for Internet-based resource-oriented services.

RESTstop is a Ruby library making it easy to implement REST services
on top of the Camping framework.

Web Services Implementation Options

Before jumping to RESTstop (if you insist click here), let’s do a brief review of the few options,
developers have historically leveraged to build web services:

SOAP services: the API is formally defined using the WSDL format. API messages use a specific XML representation.
Additional services can be composed on top of the basic protocol to provide authentication, authorization, etc.
Although powerful, SOAP has proven too complex and too heavy for web developer APIs .
Also they require a full SOAP-compatible client stack for making them more difficult to call especially in the case of AJAX applications.
As a consequence, SOAP services tend to have been relegated to intra-enterprise cross-application services.

XML services: the API is not formally defined but end-points and their inputs and outputs are usually documented on a developer site.
Each service has a given url and uses XML to represent messages. As such an XML parser is required to provide robust processing
especially if the data structures are complex and rely on namespaces.

JSON services: similarly to the XML services the API is also not formally defined.
Messages are represented as JSON structures.
JSON services lend themselves very well to AJAX calls from browser applications since
JSON structures can be easily processed using basic Javascript.

APIs for web sites mostly need to expose “resources” as opposed to behaviors (e.g. : CRUD operations on Posts)

Camping for Web Services

Since Camping is a generic Ruby web application framework, you can define service endpoints as url routes,
each mapped to a given controller.
An HTML-based view is not necessary obviously, so instead one option is to render the model
using the desired format: XML or JSON.
Example:

gem 'camping' , '>= 2.0' %w(rubygems active_support active_support/json active_record camping camping/session markaby erb ).each { | lib | require lib } Camping.goes :CampingJsonServices module CampingJsonServices include Camping::Session def CampingJsonServices.create end module CampingJsonServices::Controllers class APIDateToday < R '/datetoday' def get @result = {:today=>Date.today.to_s} @headers['Content-Type'] = "application/json" @result.to_xml(:root=>'response') end end class APITimeNow < R '/timenow' def get @result = {:now=>Time.now.utc.to_s} @headers['Content-Type'] = "application/json" @result.to_json end end end end

Such as an approach is fine for function-oriented APIs but if we want to provide CRUD access to resources,
then a REST approach provides more structure. You can of course implement a REST-style API on your own
by overriding the route dispatch mechanism and mapping the HTTP verbs such as PUT and DELETE
to the appropriate route controller methods.

RESTstop, a REST plugin for Camping

Matt Zukowski wrote the RESTstop library to easily provide access to REST resources using the underlying Camping route engine and controllers.
The idea was powerful yet simple, as a developer you would create a controller per resource
and specify the REST nature of the route like so:

module Blog::Controllers extend Reststop::Controllers class Posts < REST 'posts' end end

Then similarly to the standard get and post methods of Camping controllers, you would create CRUD-style action methods
such as: create, read, update, delete, and list:

class Posts < REST 'posts' # POST /posts def create end # GET /posts/1 # GET /posts/1.xml def read(post_id) end # PUT /posts/1 def update(post_id) end # DELETE /posts/1 def delete(post_id) end # GET /posts # GET /posts.xml def list end end

Then once you had a controller, you would implement a special type of view appropriate for the format of the data you wanted to expose.
For example you could create views to render the data as XML or JSON or any other format you liked.

module Blog::Views extend Reststop::Views module HTML include Blog::Controllers include Blog::Views def index if @posts.empty? p 'No posts found.' else for post in @posts _post(post) end end p { a 'Add', :href => R(Posts, 'new') } end end module XML include Blog::Controllers include Blog::Views def index @posts.to_xml(:root => 'blog') end end module JSON include Blog::Controllers include Blog::Views def index @posts.to_json end end

The Inner Plumbing Of RESTstop

RESTstop is an interesting plugin to dissect as it is a good illustration of meta-programming in Ruby.
Matt took the following approach:

Alias and override the base service method to save off the HTTP verb

Add a new route creation method called REST to replace the base r route creation method.
The new method will register all the expected REST resource routes and wire them up to the controller.

Default or decode the rendering format specified in the url (e.g. /posts.xml vs. /posts.json)

Structure the Views module according to the various formats to specify: HTML vs. XML vs. JSON

Render the controller output using the specified format

I would definitely recommend that your read the plugin's source. At 449 lines with many comments
it is pretty easy to see how it actually works. This will also make it easier for you to troubleshoot your code when needed.

Let's Create The REST Version Of The Blog Sample

Here is an outline of the approach:

# To Do Area (Module)

1 Plug in RESTstop into the app Main app

2 Plug in RESTstop into the Base Base

3 Plug in RESTstop into the Controllers Controllers

4 Create the REST Sessions controller Controllers

5 Plug in RESTstop into the Helpers Helpers

6 Plug in RESTstop into the Views Views

7 Finish the REST Sessions controller Controllers

8 Add JSON support Views

9 Create the REST Posts controller Controllers

10 Add an HTML view module for Posts Views

11 Add an XML view module for Posts Views

12 Add a JSON view module for Posts Views

1. Plug In RESTstop

Our first step is to install the gem and add a require for RESTstop:

gem install reststop

Now let's create a new Ruby source file and name it camping-svcs.rb.
Then let's require RESTstop and include its main module in the blog's main module.

require 'reststop' Camping.goes :Blog module Blog include Camping::Session include Reststop end

2.Plug in RESTstop into the Base

Now we need to enhance the Base module, so let's specify it.
This is the place where we'll add most of the extensions code taking care of:

Aliasing 3 methods: render, lookup, and service so RESTstop can "insert" its magic

Including Reststop::Base in the Base

Adapt the Camping lookup method to look for view methods inside the RESTstop-specific Views::HTML module

So add the following code:

module Blog::Base alias camping_render render alias camping_lookup lookup # @techarch: required if camping > 2.0 alias camping_service service include Reststop::Base alias service reststop_service alias render reststop_render # Overrides the new Tilt-centric lookup method In camping # RESTstop needs to have a first try at looking up the view # located in the Views::HTML module. def lookup(n) T.fetch(n.to_sym) do |k| t = Blog::Views::HTML.method_defined?(k) || camping_lookup(n) end end end

3. Plug in RESTstop into the Controllers

Here we'll add an extend for the Reststop::Controllers.

module Blog::Controllers extend Reststop::Controllers end

This will add 2 new methods

determine_format : will extract the service data format from the request url - e.g json from /posts.json

REST : will allow definition of REST resources in our controller declarations - e.g. class Posts < REST 'posts'

4. Create the REST Sessions controller

The Camping Blog example has a simple login system built on top of the Camping session.
For our REST blog, we'll want to support both an interactive web app login (like in the original blog)
as well as a service-based login so that only authenticated applications can call our services.

So we'll expose a new REST resource called Session. Applications will be able to create and delete sessions -
to mirror the login and logout behavior. So let's create our first REST controller and name it Sessions:

class Sessions < REST 'sessions' end

Now we just need to declare only a subset of the standard CRUD REST methods: create, and delete.
For now, let's just create the shell:

# POST /sessions def create end # DELETE /sessions def delete end

For the create method, we will lookup the user based on the user id and password.
If not found we'll return a 401 (unauthorized) error with a message.
If found, we'll create a Camping session and render a view we'll create in a bit called user.
Here is the code:

# POST /sessions def create @user = User.find_by_username_and_password(input.username, input.password) if @user @state.user_id = @user.id render :user else r(401, 'Wrong username or password.') end end

Let's test the error scenario. For that we'll use the following 2 tools:

The restr gem. This is another nice library created by Matt.
gem install restr

We'll use the library from IRB as a simple REST client.

Pocket Soap's TcpTrace, a tool to inspect the contents of Tcp messages.
This will really help us troubleshoot the various interactions between client and service.

Ok so let's start our camping app on the default 3301 port:

camping camping-svcs.rb

Now let's run TcpTrace and start a new trace listening on port 8080 and forwarding to port 3301.
Note: we'll set our IRB-based client to post to port 8080).

Then start IRB and run the following statements to invoke create on the Sessions resource:

gem 'xml-simple' gem 'restr' require 'restr' # Set the url of our resource (via port 8080 for TcpTrace) u0 = "http://localhost:8080/sessions.xml" # Set the user name and incorrect password o = { :username=>'admin', :password=>'wrong'} # Post to the Sessions resource p0 = Restr.post(u0,o)

In TcpTrace you should see the request and the response:

In IRB you should also see the 401 error:

So now we have successfully tested the error scenario!
Let's go back to our code and continue setting up our RESTstop code so we can then define our user view.

5. Plug in RESTstop into the Helpers

We'll explicitly define our Helpers module so we can:

alias the R method since RESTstop will need to intercept it to provide a way to create routes to resources (e.g. R(Posts/1)

include the Reststop::Helpers module

module CampingRestServices::Helpers alias_method :_R, :R remove_method :R include Reststop::Helpers end

6. Plug in RESTstop into the Views

In the Views module, we'll first add an extend for the RESTstop Views module

module CampingRestServices::Views extend Reststop::Views end

Then we'll create 3 sub-modules, one for each type of format we'll support: HTML, XML, and JSON.
We'll also indicate that HTML is the default format.
For the moment we'll just create shells:

module CampingRestServices::Views extend Reststop::Views module HTML end module XML end module JSON end default_format :HTML end

Since we needed to create a user view when successfully creating a Session resource,
let's create a user view method in the XML submodule. The code will just serialize the @user object to XML.

module XML def user @user.to_xml(:root => 'user') end end

We're now ready to test the happy path!
So go back to your IRB session and evaluate the following statements:

# Set the user name and correct password o = { :username=>'admin', :password=>'camping'} # Post to the Sessions resource p0 = Restr.post(u0,o)

In TcpTrace you should see the request and the response containing the serialized user:

In IRB you should also see the returned user instance, deserialized from XML

7. Finish the REST Sessions controller

The remaining part of our Sessions controller is the delete method.
Delete will terminate the session and return a 200 message to that effect:

class Sessions < REST 'sessions' # ... # DELETE /sessions def delete @state.user_id = nil r(200, 'Session terminated') end end

Let's test this out from IRB by evaluating the following statement to DELETE the current session:

p0=Restr.delete(u0,{})

In TcpTrace you should see the request and the response containing the session termination message:

In IRB you should also see the same message:

So here is a recap for what we have accomplished so far:

We have plugged in RESTstop in the following modules:

Main app

Base

Controllers

Helpers

Views

We have created our first REST controller: Sessions implementing the create and delete methods

We have created an XML submodule in our Views module to render the user XML view

We have monitored the message protocol using TcpTrace

We tested the API using the restr client library

8. Add JSON Support

Our Session resource can currently only be accessed via an XML REST interface.
So let's add JSON support by adding a user view to the JSON submodule (within our Views module):

module JSON def user @user.to_json end end

Let's go back to your IRB session and evaluate the following statements:

# Set the url for the JSON Resource format u0b = "http://localhost:8080/sessions.json" # Post to the Sessions resource p0=Restr.post(u0b,o)

In TcpTrace you should see the request and the response containing the serialized user in JSON format:

In IRB you should also see the returned user instance, deserialized from JSON:

At this stage, our service can provide authentication via the Sessions resource using either an XML or JSON protocol.
I will leave the HTML implementation for the reader. The approach would include re-using the existing Login controller,
but the login view would be moved to the HTML submodule and could be modified to POST to the Sessions resource.

So we now have the basic building authentication block for the rest of the functionality for our service.
Although this would work fine, this approach is not very robust for industrial-strength services.
I would recommend using OAuth as it provides more features such as:

per-user consumer app registration

token-based authorization

explicit user-based authorization of tokens

I recently created an OAuth plugin for Camping so check out the details on this post here.

9. Create the REST Posts controller

We will model the Posts REST controller after the Sessions controller, with a few new twists such as the
read, update and list methods.

Currently, in the Camping Blog example, there are several controllers responsible for managing posts: Index, PostNew, PostN, and Edit.
We will combine them into a brand new REST controller called Posts. So let's define a Posts controller with a REST route of 'posts':

class Posts < R 'posts' end

Now we just need to declare the standard CRUD REST methods: create, read, update, delete, and list.
For now, let's just create the shell:

class Posts < R 'posts' # POST /posts def create end # GET /posts/1 or # GET /posts/1.xml or # GET /posts/1.json def read(post_id) end # PUT /posts/1 def update(post_id) end # DELETE /posts/1 def delete(post_id) end # GET /posts or # GET /posts.xml or # GET /posts.json def list end end

Let's start with the simplest method: list.
We will just take the code from the old Index controller's get method
(and later we'll move the index view method into the HTML submodule).

# GET /posts # GET /posts.xml def list @posts = Post.all(:order => 'updated_at DESC') render :index end

Now for the create method, we will start with the code from the old PostNew controller's post method.
But we will tweak the Post.create parameters list to accept either input.post_title (when coming from an HTML form)
or input.title (when coming from a REST service call). We'll do the same for the body input parameter.
Then we will adjust the redirect call to use the RESTstop-enhanced R route creation method as opposed
to redirecting to the old PostN controller.
So all in all the code will now look like this:

# POST /posts def create require_login! @post = Post.create :title => (input.post_title || input.title), :body => (input.post_body || input.body), :user_id => @state.user_id redirect R(@post) end

The read method is easy as it is a straight copy paste from the old PostN controller's get method
(and later we'll move the view view method into the HTML submodule).

# GET /posts/1 # GET /posts/1.xml def read(post_id) @post = Post.find(post_id) render :view end

For the update method, we'll use the same technique as for the create method:
we'll start with the code from the old Edit controller's post method and allow for the
variations in the input parameters (depending on whether we come from an HTML post or a REST post).
We'll also adapt the redirect to use the new R method. So the code should look like this:

# PUT /posts/1 def update(post_id) require_login! @post = Post.find(post_id) @post.update_attributes :title => (input.post_title || input.title), :body => (input.post_body || input.body) redirect R(@post) end

The original Camping blog does not have code to delete a post, but the code for our delete method
is pretty straightforward:

# DELETE /posts/1 def delete(post_id) require_login! @post = Post.find post_id if @post.destroy redirect R(Posts) else _error("Unable to delete post #{@post.id}", 500) end end

We will need a route to create new blog entries via HTML, so let's add a new action method
to instantiate a new Post and render the add view method:

# GET /posts/new def new require_login! @user = User.find @state.user_id @post = Post.new render :add end

Then finally we will need a route to edit an existing blog entry via HTML, so let's add an edit action method
to lookup an existing Post by id and render it using the edit view method:

# GET /posts/1/edit def edit(post_id) require_login! @user = User.find @state.user_id @post = Post.find(post_id) render :edit end

To finish up the application, there a few more "utility" controllers we'll need such as:

an Index controller for the "home"/"index" page

a Login controller

a Logout controller

So first let's copy but change the original Index controller so that it just redirects to the /posts route
since the logic is now in the list method of the new Posts REST controller.

class Index def get redirect '/posts' end end

Then, we need a Login controller to render the login HTML view:

class Login < R '/login' def get render :login end end

And we also need a Logout controller to render the logout HTML view:

class Logout < R '/logout' def get render :logout end end

You can also migrate the original Styles controller, as well as the CSS declarations (located at the end of the original Camping blog source).

Before we start working on the views, let's define a couple login-related helper methods in our CampingRestServices::Helpers module:

logged_in? : to test if we have a logged in user

require_login! : to force a redirect to the login page if we don't have a valid user session

module CampingRestServices::Helpers # ... def logged_in? !!@state.user_id end def require_login! unless logged_in? redirect(R(CampingRestServices::Controllers::Login)) throw :halt end end end

We're now officially done with our Controllers module! :-)

10. Add an HTML view module for Posts

OK now that we have a functional Posts REST controller, we need to create the corresponding views
in the appropriate Views submodule (HTML vs. XML vs. JSON).

Let's start by migrating the old HTML views by copying the contents of the old Views module into
the new HTML submodule

module CampingRestServices::Views extend Reststop::Views module HTML # PLACE THE OLD Views CODE HERE end # ... default_format :HTML end

We will leave the layout view method unchanged.

Our first edit will be in the index method where we'll change the code to
create a route for the "add one" link to route to the '"new" action of our new Posts REST resource
as opposed to routing to the old PostNew controller.

def index if @posts.empty? h2 'No posts' p do text 'Could not find any posts. Feel free to ' a 'add one', :href => R(Posts, 'new') text ' yourself. ' end else @posts.each do |post| _post(post) end end end

The next view method to change is login. In the original Camping version the form will post to the Login controller.
We now need it to post to the new Sessions REST resource. So let's adapt the code as follows:

def login h2 'Login' p.info @info if @info form :action => R(Sessions), :method => 'post' do input :name => 'to', :type => 'hidden', :value => @to if @to label 'Username', :for => 'username' input :name => 'username', :id => 'username', :type => 'text' label 'Password', :for => 'password' input :name => 'password', :id => 'password', :type => 'password' input :type => 'submit', :class => 'submit', :value => 'Login' end end

Once the user has logged in we need to render the user HTML view
(if you remember we created an XML and JSON version but not an HTML one).
So let's add a quick view to greet the user and provide a link to the Posts page:

def user h2 "Welcome #{@user.username}!" a 'View Posts', :href => '/posts' end

And we need to create a logout view too, with a form which once submitted
would invoke the DELETE HTTP verb on the Sessions REST controller:

def logout h2 'Logout' form :action => R(Sessions), :method => 'delete' do input :type => 'submit', :class => 'submit', :value => 'Logout' end end

For the add view, we'll only adjust the posting route
from the old PostNew controller to the new Posts REST controller:

def add _form(@post, :action => R(Posts)) end

For the edit view, we'll also adjust the posting route
from the old Edit controller to an item-specific action (using the post id) on the
new Posts REST controller using the PUT HTTP verb:

def edit _form(@post, :action => R(@post), :method => :put) end

We will copy the view view as-is:

def view _post(@post) end

For the _post partial view, we'll adjust the h2 title link
from the old PostN controller to an item-specific action (using the post id) on the
new Posts REST controller. And we'll add a statement to display the post's body:

def _post(post) h2 { a post.title, :href => R(Posts, post.id) } p { post.body } p.info do text "Written by #{post.user.username} " text post.updated_at.strftime('%B %M, %Y @ %H:%M ') _post_menu(post) end text post.html_body end

The next partial view to update is _admin_menu, where we'll adjust the link
from the old PostNew controller to the new action of the new Posts REST controller:

def _admin_menu text [['Log out', R(Logout)], ['New', R(Posts, 'new')]].map { |name, to| capture { a name, :href => to} }.join(' – ') end

The last partial view to update is _post_menu, where we'll adjust the edit link
from the old Edit controller to an item-specific edit action (using the post id) on the
new Posts REST controller. And we'll also add a link to delete the blog post using
an item-specific delete action.

def _post_menu(post) if logged_in? a '(edit)', :href => R(Posts, post.id, 'edit') span ' | ' a '(delete)', :href => R(Posts, post.id, 'delete') end end

The _form partial view will most remain the same, except for a few visual tweaks:

def _form(post, opts) form({:method => 'post'}.merge(opts)) do label 'Title:', :for => 'post_title' input :name => 'post_title', :id => 'post_title', :type => 'text', :value => post.title br label 'Body:', :for => 'post_body' textarea post.body, :name => 'post_body', :id => 'post_body' br input :type => 'hidden', :name => 'post_id', :value => post.id input :type => 'submit', :class => 'submit', :value => 'Submit' end end

We're now officially done with our Views::HTML module!
So we should be able to test it out: start the Camping server and navigate to the app.
You should get the home/index page.

At this point you should be able to "exercise" all aspects of the app, from login to add, edit, delete, and logout.

11. Add REST XML and JSON view modules for Posts

The HTML submodule was the most complicated believe it or not! Adding the XML view support is very straightforward and consists of:

a layout method whose only job is to yield the content

a user view which we already created earlier when testing the Sessions controller

an index view to return the list of posts formatted as XML

a view view to return the details of a given posts formatted as XML

The submodule will look like this:

module CampingRestServices::Views extend Reststop::Views # ... module XML def layout yield end def user @user.to_xml(:root => 'user') end def index @posts.to_xml(:root => 'blog') end def view @post.to_xml(:root => 'post') end end # ... end

To test the API you can either:

Navigate to:
http://localhost:3301/posts.xml

Or use IRB and the RESTR client, by evaluating the following statements:
u1="http://localhost:8080/posts.xml" # Get all Posts resources p1 = Restr.get(u1,o)

Here are a few other examples to try out from IRB to test the create, read, update, delete methods:

p2={ :title=>'Brand new REST-issued post', :body=>'RESTstop makes it happen!!!'} # Create a new resource p2b=Restr.post(u1,p2) # ----------------------------------------------------- u3 = "http://localhost:8080/posts/1.xml" p3 = Restr.get(u3,o) # Modify the title p3['title']='UPDATED: ' + p3['title'] # Update the resource p3b = Restr.put(u2,p3,o) # ----------------------------------------------------- # Delete a resource p4=Restr.delete(u3)

You have now successfully implemented the XML rendering!

12. Add a JSON view module for Posts

The JSON submodule will be as simple as the XML submodule and will look near identical except for the JSON serialization code:

module CampingRestServices::Views extend Reststop::Views # ... module JSON def layout yield end def user @user.to_json end def index @posts.to_json end def view @post.to_json end end # ... end

Again, to test the JSON API you can either:

Navigate to the JSON version of the url:
http://localhost:3301/posts.json

Or use IRB and the RESTR client, by evaluating the following statements:
u1="http://localhost:8080/posts.json" # Get all Posts resources p1 = Restr.get(u1,o)

You have now successfully implemented the JSON rendering!

Overall Recap

So when you need to implement your own REST Camping app, here are the basic steps to remember:

# To Do Area (Module)

1 Plug in RESTstop into the app Main app

2 Plug in RESTstop into the Base Base

3 Plug in RESTstop into the Controllers Controllers

4 Plug in RESTstop into the Helpers Helpers

5 Plug in RESTstop into the Views Views

6 Create your REST resource controller Controllers

7 Add an HTML view module for your controller Views

8 Add an XML view module for your controller Views

9 Add a JSON view module for your controller Views

10 Either create a REST Sessions controller or implement OAuth Controllers

So What?

Although you can create REST services "by hand" using either basic Ruby web server or using the Camping framework,
RESTstop brings you the following benefits:

makes it easy to define REST controllers using minimal syntax like:
class Posts < REST 'posts' end

provides a simple convention for CRUD resource operations

delegates the API output format to the appropriate format-specific view submodule

fits nicely within the overall Camping framework architecture

So if you have been hesitant to provide a REST api in your Camping web application due to the anticipated complexity,
or if you want to create REST API separate from your web app, RESTstop is the right solution for you!

The only additional suggestion I would have is to consider using OAuth authorization framework
in conjunction with your REST API. This will increase the robustness and security of your service.

References and Resources

REST

REST Definition on Wikipedia

REST resource

Roy Fielding's dissertation on REST

Ryan Tomayko's "How I explained REST to my wife"

JSON

Camping

Ruby Camping Framework

Original Camping Blog example

Camping controller routes

JSON

RESTstop library on GitHub

Camping-OAuth repository on GitHub

Tools

JSON Viewer plugin for FireFox

JSON Viewer client

Matt's RESTr client

TCP Trace

Contributors/Ruby-ists

Magnus Holm (@judofyr) - Camping, ...

Matt Zukowski - RESTstop, RESTr, ...

Metaprogramming

Include vs. Extend in Ruby (by John Nunemaker)

[Module] Mixins (in Programming Ruby)

Extending Objects (in Programming Ruby)

Adding module behavior with module_eval (in Programming Ruby)

Fun with Ruby’s instance_eval and class_eval (by Brian Morearty)

My Other Related Posts:

Easily Transform Your Ruby Camping App Into An OAuth Provider

Camping light (nosql) with MongoDB

Visualize Application Metrics on NewRelic for your Ruby Camping Application

Running the Camping Microframework on IronRuby

Full Source Of The RESTstop Camping REST Services App

Here is the full source (you can also download it from GitHub here)

#	To Do	Area
1	Create An External Template For The savings-goal-view	View
2	Refactor the savings-goal-view In Our Web Page	View
3	Hookup jQuery ViewLoader In Our Main application.js	Application
4	Refactor The Savings Goal Mediator	View Mediator

#	To Do	Area
1	Create the Consumption Scenarios View	View
2	Create the Consumption Scenarios ViewModel	View Model
3	Create the Consumption Scenarios View Mediator	View Mediator
4	Link the Page and the View Mediator	Main App
5	Create the Coffee Pricing ViewModel	View Model
6	Create the Coffee Pricing ViewMediator	View Mediator
7	Link the Page and the Coffee Pricing View Mediator	Main App
8	Leveraging Independent View Models	View Model
9	Create the Savings Forecast View	View Mediator
10	Create the Savings Forecast ViewModel	View Model
11	Create the Savings Forecast View Mediator	View Mediator
12	Link the Page and the Savings Forecast View Mediator	Main App

#	To Do	Area
1	Create a Shell Application	Main app
2	Organize our Application Code	Main App
3	Create the Savings Goal View	View
4	Create the Savings Goal ViewModel	View Model
5	Create the Savings Goal View Mediator	View Mediator
6	Link the Page and the View Mediator	Main App
7	Apply Data Masking Business Rules	View Mediator
8	Apply Custom Masking Rules	View Mediator
9	Applying Formatting Rules	View Mediator
10	Providing Visual Feedback Cues	View Mediator

Library	Purpose / Rationale
Modernizr	Detects HTML 5 support and provide IE shims
jQuery	Main foundation (do I need to say more :-) ?!)
jQuery UI	Prefabricated UI super-elements like tabs, accordions, sliders, etc.
jQuery Cookies	Easy management of cookies
jQuery HotKeys	Handling of keyboard shortcuts
jQuery Masked Input	Allow creation of custom input masks
jQuery Validate	Validation framework
Accounting.js	Allow formatting currency amounts
CurrencyMaskJS	Allow masked input of currency amounts
jStorage	Wrapper for local storage APIs

#	To Do	Area (Module)
1	Create a Shell Application	Main app
2	Organize your Application Code	Main App
3	Break down each independent panel into Views	View
4	Create a ViewModel for each View	View Model
5	Create a View Mediator for each View	View Mediator
6	Link the Page and the View Mediator(s)	Main App
7	Apply Data Formatting / Masking Business Rules	View
8	Apply Custom Masking Rules	View Mediator
9	Applying Formatting Rules	View Mediator
10	Providing Visual Feedback Cues	View Mediator

Product	Comments
Tools to tracking and analyze conversions
Clicky
Google web site optimizer
Crazyegg	Includes heatmap
Mixpanel	Great for tracking business/user events
Performable	Full customer experience and revenue tracking, reverse funnel analysis
Omniture	The Cadillac option for large enterprises
Tools to survey and understand user behavior
iperceptions	Define quick short surveys to understand user motivations and success
KissInsights	Prompt users for one quick simple question
4Q Survey	Prompts users for the 4 essential questions about their experience
ForeseeResults	Focuses on complete web effectiveness
Opinionlab	More sophisticated option with survey modules, reports,
Getting input from real testers
UserTesting	Testers narrate their test using video
FeedbackArmy	You submit 4-6 questions about your site and you receive 10 answers
5secondtest	Testers have 5 seconds to get an impression of your landing page
Tools to optimize the site
Google web site optimizer
SumoOptimize	Recent entrant
Optimizely	Great wysiwyg editing of your own pages
Unbounce	Great for testing different landing pages and starting A/B tests
Visual website optimizer	Rich functionality with a great wysiwyg interface

API	Parameters	Context	Purpose/Usage
ab_test	test name optional: array of alternatives optional: conversion name	View or Controller	Select an alternative for the current user based on the alternatives specified for this test. If no alternatives are specified a boolean value is returned. Tracks the execution using the conversion name if provided otherwise use the test name.
bingo!	conversion name (or test name)	Controller	Tracks a conversion for the current user and the conversion specified. The test name is the fallback option.

Model	Responsibilities
User	The user account on the prototype app
Abingo	ABingo’s main API class
Experiment	Represents a specific test based on multiple alternatives
Alternative	Tracks participants and conversions for a given alternative

#	To Do
A	Reference and require the needed gems
B	Customize the main module
C	Plugging in the ABingo common helpers module
D	Plugging in the ABingo Experience and Alternative models
E	Plugging in the ABingo Dashboard controllers
F	Plugging in the ABingo Dashboard views
G	Add code to manage the ABingo user identity in our controllers

#	To Do	Area (Module)
1	Plug in RESTstop into the app	Main app
2	Plug in RESTstop into the Base	Base
3	Plug in RESTstop into the Controllers	Controllers
4	Create the REST Sessions controller	Controllers
5	Plug in RESTstop into the Helpers	Helpers
6	Plug in RESTstop into the Views	Views
7	Finish the REST Sessions controller	Controllers
8	Add JSON support	Views
9	Create the REST Posts controller	Controllers
10	Add an HTML view module for Posts	Views
11	Add an XML view module for Posts	Views
12	Add a JSON view module for Posts	Views