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.
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 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>
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":
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:
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.children().css("background-color", "yellow");
This is the same as using the jQuery selector function:
$("#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).
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.
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:
getFieldByAttribute(attr, value)
The getFieldByAttribute() method searches for controls whose attribute matches a specified 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: {...}
}
]
$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.
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.
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:
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
}
Note: The el.onsubmit function does not work in ProcessMaker Mobile. This function just works in ProcessMaker Web. To work in both ProcessMaker platforms, review the setOnSubmit() helper example.
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:
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:
