Developing Custom VersionOne Apps 101 Series GuideAs we just saw, in How To Build a Backbone/Fortified User Story Editor for the VersionOne REST Data API, Backbone Forms is an open source library for Backbone.js that makes creating model/bound HTML forms dead simple. We're going to dig deeper into Backbone Forms and how it interacts with the standard Backbone.Model class.

In this article

Instead of explaining the Backbone/Fortified example line/by/line in more depth, we're going to peek inside of the VersionOne Feature Requestor Sample Custom App that we looked at way back in the beginning of the series. We'll see how Backbone Forms is used to make the Request editor and to simplify, using Backbone models, the request / response interaction we just demonstrated.Note: this app does not yet use Backbone.Sync for ajax, so we won't discuss that yet.

What you'll need

• Google Chrome, as always :)

Simple Backbone Forms example

For a quick overview of what Backbone Forms does, take a look at this example from the project's documentation.

HTML

[gist id=4689117 file=gistfile1.html]

CSS

[gist id=4689117 file=gistfile4.css]

JavaScript

[gist id=4689117 file=gistfile5.js]See it action here on JSFiddleFor a better understanding of the library, take a look at Backbone Forms on Github.

Feature Requestor App configuration for Backbone Forms

So, how do we use Backbone Forms in the Requestor?

Form specification in the fields.coffee file

The file fields.coffee contains the set of fields and their HTML form element type, plus a few other attributes. For scalar types, it's very simple. By default, a project will use the fields specified in the defuault property.Note: To override that set for a specific project, simply add another property, at the same level as default, with the scope id, like Scope:173519. We'll cover this in a later section. Here's how the form we saw way back in the beginning demo article gets specified: [gist id=4689117 file=gistfile6.coffee]

• The left/most property name must match an asset's attribute name
• title // will be used as the description label on the form
• type // specifies what kind of form element to use, defaulting to simple text box
• assetName // specifies the VersionOne asset type for relations on an asset
• autofocus // specifies that a field should be automatically focused on load
• optional // when true, allows an empty value for the field

See the Backbone Forms documentation for possible values of the type attribute for form element types.Note: If you do visit the Backbone Forms documentation, you'll notice that autofocus, optional, and, of course assetName are not part of its API. That's because we pre/process these properties before passing this into Backbone Forms. We'll go into that in more detail in another section.

Task 1: Generate a simple JSON object from the Backbone Form instance

This step demonstrates how Backbone Forms produces simple, clean JSON objects (POJSOs?) from its fields.

• Open Chrome's Developer Tools by hitting F12 and select the Console tab
• Load the Feature Requestor app in the browser (from http://eval.versionone.net/platformtest/v1requestor)
• Type system and hit enter to search
• Select the project
• Click List then pick an existing Request
• Now, in the Chrome Console tab, type: JSON.stringify( vRequestForm.getValue() ) and hit enter

You should see something like this in your console:

[gist id=4689117 file=gistfile7.json]Note: vRequestForm, along with v1AssetEditor, are variables set into the global window object in scripts/main.js in a Backbone.Events based event handler, which we'll cover at the end of this exercise.

Task 2: Modify the Form using the Model

Given you have just completed the first step above, do this:

• In the Console, type: v1RequestForm.setValue('RequestedBy', 'Your Name')
• Look at the RequestedBy field of the form. It should now say Your Name!
• If you now type v1RequestForm.getValue('RequestedBy'), you'll see Your Name

Task 3: Generate a VersionOne API/compatible JSON DTO using the Editor

Finally, given you've at least done step one above:

• In the Console, type JSON.stringify( v1AssetEditor.createDto() ). You should see something like:

[gist id=4689117 file=gistfile8.json] This contains the _links property, which specifies the relation items necessary for the VersionOne API to properly process the request. Here's what createDto actually does: [gist id=4689117 file=gistfile9.coffee] The most important part to note here is the iteration over the select items. This jQuery selector is getting all the INPUT elements of type SELECT, and then creating relation references in the special _links property of the DTO. Then, it simply removes the prpoerty from the JSON object that was magically created by Backbone Forms. If you compare the output from the previous step, you'll notice that Priority was part of the top/level JSON object, whereas now it is inside the _links object. That's really all that's needed to transform Backbone Forms' output into a VersionOne/compliant JSON DTO!

Task 4: Create a new event handler to stringify the asset "on update"

If you change the RequestedBy or Name (Title on screen) fields, then click the List button, you'll notice that these changes are already reflected in the list. But, you don't see any additional traffic on the Network tab when you do this. That's because we're using Backbone.Events to create our own event handler, which subscribes to a custom event called assetUpdated. Here's how we do that way back inside of VersionOneAssetEditor.constructor: [gist id=4689117 file=gistfile10.coffee] And, here's how the event is triggered from inside of the saveAsset method. The same pathway is used for both create and update, but different event names are passed in for publication. This section also ties together a lot of important architectural concepts, but we'll cover them in detail in the next section. [gist id=4689117 file=gistfil11.coffee] Now, do you remember the JSON response body from part one in step 4, the one with the moments in it? If not, here's a snippet from that: [gist id=4689117 file=gistfile2.json] The normalize functions simply remove the moment number from the id and href values in the _links.self object. This is important because we need to load the latest, momentless version of the asset on click. Now, add your own, additional event handler like this:

• Complete step one above, then:
• From the Console, type: v1AssetEditor.on('assetUpdated', function(assetEditor, asset){ console.log(JSON.stringify(asset)); }) and hit enter
• Change the Description field on the form to Backbone.Events is Awesome! and hit Save

You should see something like this in the Console:

[gist id=4689117 file=gistfile3.json]

Next up

Now we're going to spice it up even more. VersionOne has more APIs, APIs I have not even talked about yet. One is called Meta, and the other is called Localization. Head over to The VersionOne MetaMorformizr App // Using the VersionOne REST Meta and Localization APIs to GET Serious to learn about them and use them to make the app even more flexible and maintainable. I know, music to a developer's ears. That's why it's bold. Whatever.