Skip to main content
Enterprise Agile Planning icon with arrows

This post is from the CollabNet VersionOne blog and has not been updated since the original publish date.

Last Updated Feb 07, 2013 — Enterprise Agile Planning expert

How To Build a Barebones User Story Editor in JSFiddle with jQuery, JSON, and the VersionOne REST Data API

Enterprise Agile Planning
Developing Custom VersionOne Apps 101 Series GuideAfter the last article, How To Use jQuery to GET a User Story in JSON Format from the VersionOne REST Data API and Render it as HTML, we've now explored all the major client/server interactions that take place over HTTP GET and HTTP POST. Now, let's build the "simplest thing that could possibly work", as they say in agile shops, to edit the User Story with HTML forms.

In this article, you will

  • Use the JSFiddle online editor
  • Create a simple HTML form that lets you edit a VersionOne User Story asset
  • Build a simple, but fully features, DTO (Data Transfer Object) binding function to populate the form from a JSON DTO fetched via HTTP GET from the VersionOne REST Data API
  • Build a simple, still fully featured, JSON DTO creator function that plucks values from the HTML form and packages them up to send back the API via HTTP POST

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

Fire up a new JSFiddle

  • Open a brand new window or tab in Chrome and navigate to
  • From the left side, under Choose Framework. It should have onLoad preselected (leave it this way)
  • Select the most recent version of jQuery
  • Type the following code into the HTML panel:
[gist id=4685001 file=gistfile1.html]
  • Add this to the CSS panel:
[gist id=4685001 file=gistfile2.css]
  • And, to wrap it up, add this to the JavaScript panel:
[gist id=4685001 file=gistfile3.js]Try live JSFiddle

Whoah, that was a lot of code! Slow down and explain some of it?

I agree with you, but this was a lot of code for me and for you to type. So, let's dig into the code in the next post. For now, though, let's start to think more abstractly about what is happening here, and tie it back to what we learned earlier about REST. Remember that REST stands for REpresentational State Transfer. In this code, we can think about representations this way:
  • The URL provides the address of some resource.
  • When we navigate to that URL, or use $.ajax() to GET it for us, the server sends back a representation of that resource. The representation of a resource can differ depending upon parameters, whether they be HTTP headers, such as the Accept types, or query string parameters that the server understands. In the case of the VersionOne REST Data API, we get a different representation if we navigate to,Description,Estimate. Precisely, we get a representation that contains only three attributes of the remote resource.
  • When we're modifying data inside the HTML form, we aren't really dealing with a representation at this point. It's just data.
  • But, when we click the save button, and call upon the createDtoFromForm function, we are building a Data Transfer Object (DTO), that will serve as a representation when we POST it back to the API.
  • At that point, the server interprets the representation and behaves accordingly.

VersionOne's API needs some improvements here

To be fair, the VersionOne REST Data API needs some updating. Why? Well, the REST community has some pretty good understanding now of a somewhat lesser known, but increasingly important HTTP method called PATCH. Here's what the RFC for PATCH says:
The PATCH method requests that a set of changes described in the request entity be applied to the resource identified by the Request/URI. The set of changes is represented in a format called a "patch document" identified by a media type.  If the Request/URI does not point to an existing resource, the server MAY create a new resource, depending on the patch document type (whether it can logically modify a null resource) and permissions, etc. The difference between the PUT and PATCH requests is reflected in the way the server processes the enclosed entity to modify the resource identified by the Request/URI. In a PUT request, the enclosed entity is considered to be a modified version of the resource stored on the origin server, and the client is requesting that the stored version be replaced. With PATCH, however, the enclosed entity contains a set of instructions describing how a resource currently residing on the origin server should be modified to produce a new version. The PATCH method affects the resource identified by the Request/URI, and it also MAY have side effects on other resources; i.e., new resources may be created, or existing ones modified, by the application of a PATCH.
If you are wondering why we have not talked about PUT before, then you caught me. That's another area where the API needs improvements. Right now, everything gets "tunneled through POST".We're taking a strong look at the open source ServiceStack project. What do  you think?

Next up

Let's slow down and examine jQuery's secrets in more depth in Understand jQuery's Magic in the Barebones User Story Editor. Stay agile, not fragile.

More from the Blog

View more Government Cloud
Apr 12, 2022 Government Cloud receives FedRAMP Authorization through sponsorship from the United States Department of Veterans Affairs

Enterprise Agile Planning
Flagship Agility solutions can effectively scale agile deve ...
Read More
Nov 22, 2021

What are the qualities of highly effective agile teams?

Enterprise Agile Planning
A team is the core unit of productivity in an agile organization. Wher ...
Read More
Nov 15, 2021

How an open-first attitude revolutionized government tech development

Enterprise Agile Planning
Public perception of government is often that it is slow-moving, reluc ...
Read More
cross functional
Nov 08, 2021

6 best practices for building resilient cross-functional teams

Enterprise Agile Planning
Agile frameworks prize the quality of resilience within every facet of ...
Read More
Contact Us