Developing Custom VersionOne Apps 101 Series GuideHaving punted explanation of the last article, How To Build a Barebones User Story Editor in JSFiddle with jQuery, JSON, and the VersionOne REST Data API, to this article because of how lengthy the code was, let’s now study the code and understand what’s going on in it.

In this article, you will

• Study the code from the last article to understand all the jQuery function calls

What you’ll need

• Google Chrome. While it should work, I have not tested this in other browsers, so if you run into any snags, please let me know in the comments

Open up a trusty old JSFiddle

Open the Barebones User Story Editor JSFiddle in a new browser or tab.

jQuery document ready handler shortcut

Let’s start with what’s known as a jQuery document ready handler:
[gist id=4685074 file=gistfile9.js]
The first bit of code, the weird $(function() { ... uses jQuery’s shortcut for the ‘document ready handler’. This instructs jQuery to execute the function passed to it when the Document Object Model (DOM) is ready. To read more about this, visit the jQuery web site.

jQuery selectors shortcuts

After that, we use another jQuery shortcut for selecting an element out of the DOM: $("#storyGet"). This is a shortcut for calling document.getElementById("#storyGet"), which selects the button from our HTML form. Having that form element selected, we call the click function, which fill bind the passed function to the click event of the element (or elements) selected by the selector.

Simple access to form data with jQuery’s val() function

From there, we try to pull out the value of the text box element named #StoryId using the jQuery val() function, and return if it’s empty.

Create the resource URL

If it’s not empty, we build up the URL for where to load the story from.
Let’s remember the initial configuration variables we had in the beginning of the script:
[gist id=4685074 file=gistfile2.js]
Now, supposing we type 1154 into the StoryId textbox, then the following line:var storyUrl = url + storyId + select;will evaluate to:http://eval.versionone.net/platformtest/rest/1.v1/Data/Story/1154/?sel=Name,Description,Estimate

Ajax cleans up remote data access

The remainder of the function’s code uses jQuery’s handy ajax function:
[gist id=4685074 file=gistfile3.js]
The parameters object, or “hash”, options are:

• url the url we just built, providing the resource location that we want to load from the API
• type the HTTP method to use for the request. We are simply fetching data, so we use HTTP GET
• dataType this tells jQuery to expect the data coming back to be json, no matter what the content/type header says
• headers we pass along the headers object to Authorize with the specificied credentials, and what data format we will Accept

Understand jQuery Deferred Objects for asynchronous operations

The next part looks a little weird. .done(...) and then .fail(...). jQuery 1.5 introduced the Deferred Object.
Here’s a summary of what it’s for from the documentation link above:

Most of the functions on a Deferred Object accept a function parameter that will get called in response to certain events. In our case, the ajax() call creates a Deferred object that wraps an underlying XMLHttpRequest used to communicate with the VersionOne REST Data API. As you probably know, this object makes calls asynchronously, so we cannot expect the request to complete before the next line of code runs!

Handle successful HTTP requests with a done() callback

Because of this, we supply the done() function with a callback function) that jQuery itself will invoke when the request successfully returns data from the remote web server hosting the API.
The callback itself will accept a parameter with the content returned by the server. In our case, we name it data and then we pass it off to the bindDtoToForm() function, which we’ll explain in a moment. After that, we simply call $("#editor").show(), which finds the #editor DIV element, and invokes jQuery’s show() function to cause the DIV to become visible in the UI.

Handle failed HTTP requests with a fail() callback

Now, if you thought that the fail() function accepts a function to call when the request fails, then you’d be correct. In that case, jQuery returns to us its jqXHR object that made the call to the server. This is an instance of the jqXHR object. This topic is a bit out of scope, and quite low/level, for this article, but you can read more about it here.

Populate the HTML form with bindDtoToForm()

This is one of the easiest parts of the whole app! Yet, so many people fail to recognize how easy it is to do this:
[gist id=4685074 file=gistfile4.js]

All that this does is:

• Iterate over each key in the JSON DTO that we got from the server, then:
• Use jQuery’s selector shortcut we just examined to find the corresponding HTML form element, and:
• Use the val() function we already examined to set the value in the form element.

The JSON DTO will look something like this:

[gist id=4685074 file=gistfile5.json]
So, if we were to write all the code we needed by hand to achive the same thing, it would look like this:
[gist id=4685074 file=gistfile6.js]
So, while in this case we only save 1 line of code, you can probably imagine how tedious it would be to write all that code by hand if we had 10 fields, or 100 fields. The first version, with the for loop, will handle 3 fields or 300 fields with no additional code. Don’t let me catch you putting 300 fields on a form, however!

Create the DTO from the form to send as a representation to the API

At long last, we get to what happens when we save changes to story. The createDtoFromForm() function is barely more complex than the bindDtoForm() function.

First the save story click handler:

This is pretty much the same code that we saw a couple of articles ago when we used HTTP POST to update a story. The difference here is that we manufacture the DTO by calling another function.
[gist id=4685074 file=gistfile7.js]

And, createDtoFromForm:

And, here is that function. Notice above how we passed “#editorForm input, #editorForm textarea” into this function. We then use this as a jQuery selector to select all input and all textarea elements under the #editorForm parent element.From there, we simply rely on the attr() and val() jQuery functions to populate a new object with the right values. This object, stringified, is what we send over the wire to the API as a representation.
[gist id=4685074 file=gistfile8.js]

You did it!

That’s it! You now have a complete Barebones Story Editor, and you’ve read about all the functions we used in jQuery to make it happen! Did you notice how easy it was to build up the DTO using the createDtoFromForm function?
Well, just when you thought you’ve built something to stand the test of time, I’m going to yank that tool out of your hands next time, because it’s still too much code! It will be even easier than that when we add some Backbone to this and use Backbone Forms in the next episode.
Remember, you can try the live JSFiddle here.

Next up

Programming is nothing if it’s not about raising the bar of abstraction. We’re going to introduce three awesome tools for our work: Backbone.js, its counterpart Underscore.js, and Backbone Forms. See you in How To Build a Backbone/Fortified User Story Editor for the VersionOne REST Data API.