Loading Data

The most important part of this whole scenario is your data. First, Jaffa is going to need to know how to get it from the server, although that's pretty easy, we just tell it where to go with our configuration:

var jaffa = jaffaFactory({
        urlDataSource: "/server/path/formData.json"
    });

This could be either a relative or absolute URL; it makes no difference (XSS considerations aside). Eventually it will make its way down into a jQuery.ajax() call, exactly as you have provided it, so it simply needs to be resolvable from the current page/domain.

Managed Data

On the next tab you'll find information about how Jaffa finds and manages your form's GUI elements. Every field that Jaffa is aware of in this way is considered 'managed', and (in a perfect world) every managed field will be paired up with some of your server provided data. When one changes, so should the other, and ultimately, when the form is 'submitted' we are going to send the resulting JSON data back to the server for storage.

Because this demonstration page does not need to submit any data to the server, we can override the JSON submission method and route the output into the page itself. The below field has been modified so that after any edits it manually forces a form submission and you should see the form data in the area below that update (Note: Tab swapping through the demo also causes an 'auto-save' that triggers this submission as well). This is the JSON that would be normally sent to the server from the form elements spread across all tabs of this demonstration.

Edit this field: and the JSON below will change.

Apologies to IE users, but after patching prettify.js to support webkit browsers I gave up on getting prettyPrintOne() to preserve newlines under IE.

Unmanaged Data

But what about a non-perfect world? Perhaps the server sends Jaffa some data that your form has no controls for and no knowledge of... what should we do? Well the answer is (as always) configurable, but by default Jaffa considers 'unmanaged' data to be important enough to halt functioning. Form submission is disabled so data is never sent back to the server.

In this context unmanaged data is considered to be an error where your form and data do not match, and the potential for corrupting your data is held to be the most important thing to avoid.

It is worth noting that the reverse scenario (no server data for a managed field exists) is not significant. This is what a brand new record would probably look like since no data is stored for it yet.

Give it to me anyway

So you know what you are doing, you want the form to keep working and you'll handle the unmanaged data yourself; either on the server, or in the client (our demo below)? Ok, here's how you can do it.

What we would like to do as a trivial demonstration is give Jaffa a callback function to execute whenever it comes across some unmanaged data. The configuration has a really imaginative property name: callbackUnmanagedServerData.

function unmanagedData(fieldName) {
    $("#unmanagedDataAlerts").append("... Unmanaged field '" + fieldName + "' in server data! ...");
}

var jaffa = jaffaFactory({
        callbackUnmanagedServerData: unmanagedData
    });

There's some HTML wrapping snipped out of there, but really all we are doing is pushing our notifications into the alert box setup below:

Now's a good time to show how we achieved some of the demo content above, namely how we forced the submission process to proceed, even though there was unmanaged data, and also how we redirected the submission process to display our JSON:

// Look for a change event on that control and start a submit().
// You can target specific fields in other ways, this is a more global callback
function onDataChanged(fieldName) {
    if (fieldName == "aaaFirstFieldDemo") {
        jaffa.form.submit();
    }
}

// Returning 'true' from this (optional) callback forces a submission. We are
//  provided the 'invalidData' flag and all the data to let us make a decision
function preSubmission(invalidData, serverData) {
    return true;
}

// This overrides Jaffa's internal submission process
function submissionOverride(invalidData, serverData) {
    var jsonString = JSON.stringify(serverData, null, 4);
    // <snip> ... some prettifying of the JSON + add some headings
    $("#showMeTheJson").append(jsonString);
}

// How our config gets into Jaffa
jaffa = jaffaFactory({
        // Callbacks
        callbackOnDataChanged: onDataChanged,
        callbackPreSubmission: preSubmission,
        // Overide an internal function
        functionSubmitData: submissionOverride
    });

Advanced Usage

This section will make more sense if you've looked at the some of other tabs, so you may want to come back to it later.

We can go a step further and 'solve' the problem of unmanaged data by adding additional form fields after the data loads; first the code, then below you can see it in action:

// Config during Jaffa's startup
function newmanagedData(fieldName) {
    $("#unmanagedDataAlerts #unmanaged-" + fieldName).remove();
    $("#managedDataAlerts").append("<p><i class=\"icon-info-sign\"></i> Field '" + fieldName + "' is now managed.</p>");
}

function unmanagedData(fieldName) {
    $("#unmanagedDataAlerts").append("<p id=\"unmanaged-" + fieldName + "\"><i class=\"icon-warning-sign\"></i> Unmanaged field '" + fieldName + "' in server data!</p>");
}

var jaffa = jaffaFactory($, {
        callbackUnmanagedServerData: unmanagedData,
        callbackNewManagedServerData: newmanagedData
    });

// Click events
$("#data-manage-text").click(function() {
    var newInput = $("<input type=\"text\" id=\"formText\" />");
    $("#data-manage-text-span").html(newInput);
    jaffa.form.addField("formText");
});
$("#data-manage-date").click(function() {
    var newInput = $("<input type=\"text\" id=\"formDate\" />");
    $("#data-manage-date-span").html(newInput);
    jaffa.form.addField("formDate");
    newInput.datepicker({dateFormat: 'yy-mm-dd' });
});

And this setup results in the behaviour you'll see below: