Backbone Objects for Controls and Forms

Backbone.js is a library that provides the model for Dynaforms and their controls. ProcessMaker offers three custom functions, getFieldById(), getFieldByName() and getFieldByAttribute(), which are used to obtain the Backbone objects for Dynaform controls. The getFormById() function is used to obtain the Backbone object for the Dynaform.

The Backbone object supports most of the custom methods for manipulating controls, such as control.getValue(), link.setHref(), grid.getNumberRows(), plus it offers the setFocus() method, which is not provided by the jQuery object.

Functions to Obtain Backbone Objects

getFieldById('id')

The getFieldById() method returns an object that is generated by Backbone to manipulate the controls in a Dynaform. Its properties can be used to access the outer DIV of a control, which is used to resize controls when a form's width changes.

window.getFieldById("id")

Parameter:
id: The control's ID.

Return Value:
Returns a Backbone object whose properties may vary according to the type of control and whether the control has a variable assigned to it. All input controls should have the cid, $el, el, model, parent and project properties. A textbox that has a variable assigned to it has the following content:

{
    cid:                    "xxxxx", //client ID automatically assigned to the form by BackboneJS
    $el:                    {...},   //Access to the jQuery object for the control's outer DIV
    el:                     {...},   //Access to the DOM object for the control's outer DIV
    dependenciesField:      [...],
    dependentFieldsData:    [...],
    formulaFieldsAssociated:[...],
    model:                  {...},
    parent:                 {...}
    previousValue:          "xxxxx",
    project:                {...},
    __proto__:              {...}
}

Inside the returned Backbone object, the $el property is the jQuery object of the <div> that encompasses the outer <div> of a Dynaform control. Likewise, the el property is the DOM object of the <div> that encompasses the outer <div> of a Dynaform control.

For example, here is the HTML structure of the "company" textbox control that uses the companyName variable:

<div>
    <div class="pmdynaform-field-text pmdynaform-edit-text  form-group col-sm-12 col-md-12 col-lg-12 pmdynaform-field"
   name="field-companyName" id="company">
        <label class="col-md-2 col-lg-2 control-label pmdynaform-label" for="companyName">
            <span class="textlabel" title="" data-placement="bottom" data-toggle="tooltip">Company Name</span>
        </label>
        <div class="col-md-10 col-lg-10 pmdynaform-field-control">
            <input type="text" autocomplete="off" value="" placeholder="" class="pmdynaform-control-text form-control" mask="" name="" id="form[company]">
            <input type="hidden" value="" name="" id="form[company_label]">
        </div>
    </div>
</div>
Calling getFieldById("company").$el returns the jQuery object for the outermost <div> without a class name, whereas calling $("#company") returns the jQuery object of the outer <div class="...pmdynaform-field" ...>. To get to that same outer <div> with the Backbone object, use: getFieldById("company").$el.children()

Examples:

Set the value of the "totalAmount" field to "499.99":

getFieldById("totalAmount").setValue("499.99")

This example sets the width of the "totalAmount" control's outermost DIV to 500 pixels. It accesses its jQuery object, which is located in its $el property, and then uses jQuery's css() function to set the width:

getFieldById("totalAmount").$el.css("width", "500px")

The following code does the same thing through the DOM object of the outermost DIV that is located in its el property:

getFieldById("totalAmount").el.style.width = "500px"
Note: Most of the style properties of the control's area should be set in the outer DIV with the "pmdynaform-field" class name, which is the child node. For example, to set the border color of a control's area to red and its background color to yellow:

getFieldById("totalAmount").$el.children().css("border", "1px solid red");
getFieldById("totalAmount").$el.children().css("background-color", "yellow");

This is the same as using the jQuery selector function:

$("#totalAmount").css("border", "1px solid red");
$("#totalAmount").css("background-color", "yellow");

getFieldByName('name')

getFieldByName() searches for control(s) using the name of the variable used by the control and returns an array of matching Backbone object(s).

window.getFieldByName("name")

Parameter:
name: The name of the variable used by a DynaForm control. Set to "" (an empty string) to search for all the controls that do not have an assigned variable.

Return Value:
Returns an array of the Backbone object(s) for the control(s):
[
    {
        cid:                    "xxxxx", //client ID automatically assigned to the form by Backbone
        $el:                    {...},   //Access to the jQuery object for the control's outermost DIV
        el:                     {...},   //Access to the DOM object for the control's outermost DIV
        dependenciesField:      [...],
        dependentFieldsData:    [...],
        formulaFieldsAssociated:[...],
        model:                  {...},
        parent:                 {...}
        previousValue:          "xxxxx",
        project:                {...},
        __proto__:              {...}
    }
]

getFieldByName("name")[0] returns the same object as getFieldById("id"), so its $el, el, and other properties can be accessed in the same way.

Example:

Get the ID of the control that uses the "clientType" variable:

var id = getFieldByName("clientType")[0].model.id;

getFieldByAttribute(attr, value)

The getFieldByAttribute() method searches for controls whose attribute matches a specified value.

window.getFieldByAttribute(attr, value)

Parameters:
attr: The name of an attribute. See the object below for all the available attributes.
value: The value of the attribute to search for.

The attributes of a control can be found in the getFieldById("id").model.attributes object, which can vary depending on the type of control. See this list of the available attributes for controls.

Return Value:
Returns an array of all the Backbone control objects that match the search attribute. The properties of each object vary according to the type of control.

[
    {         //properties for a textbox control:
        cid:                    "xxx",  //client ID automatically assigned to the control by Backbone
        $el:                    {...},  //The jQuery object for the control's outer DIV
        el:                     {...},  //The DOM object for the control's outer DIV
        dependenciesField:      [...],
        dependentFieldsData:    [...],
        formulaFieldsAssociated:[...],
        previousValue:          "xxx",
        model:                  {...},
        parent:                 {...},
        project:                {...}
    },
    {          //properties for a radio control:
        cid:                    "xxx",  //client ID automatically assigned to the control by Backbone
        $el:                    {...},  //The jQuery object for the control's outer DIV
        el:                     {...},  //The DOM object for the control's outer DIV
        clicked:                false,
        previousValue:          "xxx",
        model:                  {...},
        parent:                 {...},
        project:                {...}
    }
]
Remember that the $el and el properties are for the outer DIV. To access the inner DIV, use getFieldByAttribute(attr, value)[i].el.childNodes[1]. To access the input field of a control, use: getFieldByAttribute(attr,value)[i].$el.find("input"), however the hidden input fields will need to be ignored. To find only textboxes and textareas use: getFieldByAttribute(attr,value)[i].$el.find(".form-control")

Example:

Return all the controls that occupy 6 columns and set the background color of their inner DIVs to blue.

var aFields = getFieldByAttribute("colSpan", 6);
for (i=0; i < aFields.length; i++) {
    aFields[i].el.childNodes[1].style.backgroundColor="blue";
}

getFormById('id')

The getFormById() method returns the Backbone object of a Dynaform.

window.getFormById("id")

Parameter:
id: The Dynaform's unique ID, which is 32 hexadecimal characters. It can be obtained by clicking on the border of the Dynaform and viewing its id property.

Return Value:
Returns a Dynaform object, with content such as:

{
    cid:       "view4", //client ID automatically assigned to the form by Backbone
    $el:       {...},   //The jQuery object for form
    el:        {...},   //The DOM object for form
    factory:   {...},
    items:     {...},
    model:     {...},
    Project:   {...},
    viewsBuild:{...}
}

The object that is returned contains the $el object, which allows access to the form's jQuery methods and properties. Use the el object to access the form as a normal form object. For example, getFormById("id").el.submit() can be used to submit the form. getFormById("id").el.reset() can be used to reset the form back to its original values. getFormById("id").el.length is the number of inputs in the form and getFormById("id").el.elements is an array of those inputs.

Example 1:

When the Dynaform is submitted, check whether the "amount" and "tax" fields add up to less than 500. If greater, then display an alert telling the user to enter a smaller amount into those fields and resubmit the form. In the event handler of the submit event, return false to prevent the submit action from taking place.

getFormById("256626355556e105e388481009169452").el.onsubmit = function() {
    var total = parseFloat($("#amount").getValue()) + parseFloat($("#tax").getValue());
    if (total >= 500) {
        alert("Error: The amount plus tax must be less than 500. Please enter a new amount.");
        return false; //stop submit
    }
    return true;  //allow submit
}

Methods and Properties in Backbone Objects

Apart from the custom methods used to manipulate a control, the Backbone object also holds the control's model information at:

getFieldById("id").model

The control.model.attributes is an object with all the attribute properties of the control and the control.model.keys() method can be used to obtain an array of the attribute names used by a control.

The .$() method in the Backbone object is a jQuery selector that searches for elements inside the control. For example, to obtain the "companyName" control's label:

var label = getFieldById("companyName").$("span.textlabel").html();