Obtaining jQuery Objects
A jQuery object can be obtained for each control in a Dynaform. This object contains the standard jQuery methods, such as hide() and show(), but it also contains custom methods added by ProcessMaker. It is recommended to use these custom methods, which are listed below, when manipulating Dynaform controls.
$("#id") or jQuery("#id")
All the controls in a Dynaform, including textboxes, titles, labels, links, images, etc., have an ID that can be used to obtain the jQuery object that ProcessMaker uses to manipulate a control. To obtain this object, use jQuery's selector method to access the control using its ID. $ is an alias for jQuery, so the selector method can be called either way:
This selector will return an object that has methods to manipulate Dynaform controls, such as getValue(), setValue(), getLabel(), etc. These methods can be called once the control object is obtained.
Example:
This code example obtains the object for a field with the ID "companyName" and then calls the object's setLabel() method to change the label to "NGO Name":
The # is used to find an element in the current frame with the specified ID. A control's ID identifies the outer <div> that holds the control, so calling $("#control-id") will return a jQuery object for that div that contains some custom methods to manipulate the control. See the sections below to access the input field or label of a control.
To use a jQuery selector to search for a style class, use a . (dot) followed by the class name. For example, to search for all elements that use the "textLabel" class:
Likewise, it is possible to search for a tag. For example, to search for all the <span>s tags in the Dynaform:
To search for the elements containing a particular attribute, use "[attributeName=value]". For example, to search for the name of "clientId":
All of these searches can be combined. For example, to search for a <label> using the "control-label" class whose for attribute is set to "clientId":
The DOM objects for all the elements that were found by a selector are placed in an array in the jQuery object. To find out how many elements were found by the selector, check the length property of the jQuery object that is returned. For example, to make the text the color green in the first and last <span>s found by a selector:
var lastIndex = oSpans.length - 1; //subtract 1 because array starts counting from 0.
oSpans[0].style.fontColor = "green";
oSpans[lastIndex].style.fontColor = "green";
Many jQuery methods, such as show(), hide() and css(), will operate on all the elements returned by the selector. These methods return an array of all the elements they operated on. A few jQuery methods, such as attr(), will only operate on the first element returned by the selector.
The jQuery selector $(DOMobject) can also be used to convert a DOM object into its jQuery object.
Example:
This code first obtains the DOM object for the "AccountNo" control, which is in the outer DIV, and sets its border to the color red. Then, it uses $() to convert it from a DOM object to a jQuery object, so that it can call its setValue() method to change its value to "ARB-501".
oAccount.style.borderColor = "red";
$(oAccount).setValue("ARB-501");
value property, because doing that will not set the value in the hidden field of each control, nor will it change the value in the control's Backbone object; therefore, it will not be saved correctly when the Dynaform is submitted.NEVER do this:
Accessing Forms
The jQuery object of a Dynaform's <form> can be accessed by specifying the 32 hexadecimal character unique ID that ProcessMaker automatically generates for it.
Example:
Set the background color of the Dynaform with the ID "315000439561bfbb2880516004635450" to a light grey color:
Another way to access the Dynaform that doesn't require knowing its unique ID is to search for a <form>:
<form> in the current frame, but if other forms were
added to a panel control, then select the Dynaform with $("form.pmdynaform-form") or $("form").first() .
Accessing Controls in Subforms
The controls in subforms can be accessed just like normal controls, as long as their IDs are unique. If a control in a subform has the same ID as a control in the master form, then first obtain the subform's jQuery object using its 32 hexadecimal character unique ID that was automatically generated by ProcessMaker. Then, use jQuery's find() method to search for the control's ID inside the subform.
Example:
Set the value of the "companyName" textbox, which is found inside a subform with the ID "92799481456210d2fc9f249076819716":
Accessing Buttons
Buttons can be accessed just like normal controls with the find() method.
It is possible to attach events, like the click event, in the following way:
Example:
To show an alert message when the user clicks the "getDiscount" button.
alert("Button was clicked");
} );
Standard jQuery Methods
In addition to the custom ProcessMaker methods added to the jQuery objects of the controls, jQuery also provides a library of standard methods that can be used to manipulate the controls. Listed below are listed some of the more useful ones frequently used in the examples on this page.
.attr()
.attr() is a standard jQuery method that gets and sets the value of attributes in elements. If the jQuery selector returns more than one element, it gets or sets the attribute of the first element.
To get the value of an attribute:
To set the value of an attribute:
Attributes are the values of an element that are usually defined in its HTML definition and are usually set before it is rendered on the screen. In contrast, properties are the values of an element that are usually set when it is added to the DOM and rendered on the screen. Unlike attributes, which usually do not change and are fixed in the initial definition, properties often can be changed by the user. Attributes should be accessed with .attr(), whereas properties should be accessed with .prop().
In the above example, id, type and value are attributes defined in the HTML code, but align, autofocus, and baseURI are properties set when the element is rendered. For most values, it doesn't matter whether they are accessed with .attr() or .prop(), but it can make a difference in some situations.
For example, if the user changes the value of this textbox from "Acme, Inc." to "Wiley Enterprises", calling:
This code will return "Acme, Inc.", which was the initial value and is now fixed. However, calling:
This will return "Wiley Enterprises", which is the current property and can be changed.
Examples:
Set the target attribute to "_self" in a link control with the ID "companyLogo" to open the link in the frame where the Dynaform is located. Remember that the <a> element of a link control has an "a" element that needs to be found with the JQuery method .find().
Disable a dropdown box with the ID "selectContractor" when the user marks the "noContractor" checkbox.
if (newVal = '"["1"]"') {
$("#selectContractor").getControl().attr('disabled', true);
}
} );
.show()
show() is a standard jQuery method that can be used to show a control and its label in a Dynaform. Other controls will be moved down or to the right. It does this action by setting style.display="" in the outer DIV, which holds the control and its label.
Return Value:
Returns an object that holds information about the control. For example, a textbox with the ID "lastName":
"0": {
"jQuery111101537927321029987": 101
},
"length": 1,
"context": {
"location": {
"constructor": {}
},
"image0000000001": {},
"jQuery111101537927321029987": 1,
"_html5shiv": 1
},
"selector": "#lastName"
}
Example:
A button with the ID "showHideAddress" will toggle between showing and hiding the "address" field when the button is clicked:
.hide()
hide() is a standard jQuery method that can be used to make a control and its label disappear in a Dynaform. Other controls will be moved up or to the left to take its place. It does this by setting style.display="none" in the outer DIV, which holds the control and its label.
Return Value:
Returns an object that holds information about the control. For example, a textbox with the ID "lastName":
"0": {
"jQuery111101537927321029987": 101
},
"length": 1,
"context": {
"location": {
"constructor": {}
},
"image0000000001": {},
"jQuery111101537927321029987": 1,
"_html5shiv": 1
},
"selector": "#lastName"
}
Example:
This example hides the field with the ID "productDescription" when the checkbox "noProduct" is marked. Otherwise, the field is shown.
if (newVal === '["1"]') {
$("#productDescription").hide();
} else {
$("#productDescription").show();
}
}
$('#addProduct').setOnchange(showOrHideDescription); //execute when checkbox is changed
.css()
css() is a standard jQuery method that can be used to either read or change one of the style properties of a control.
To read a style property:
To change a style property:
Note: Style properties in JavaScript and DOM use camel case, whereas CSS uses lowercase with words separated by hyphens (-), but .css() can understand both styles, so .css("background-color") and .css("backgroundColor") are the same.
Example:
Get the width of a dropdown box with the ID "billingMethod" and then add 200 pixels to it, as long as the new total is less than the width of the screen:
Searching for Elements
jQuery provides a number of methods to search for elements, similar to the jQuery selector function $(), but they start their search based on where the element is in the Document Object Model (DOM) tree. Some of the more useful methods include:
- .find() searches within all the descendant nodes in the DOM.
Ex: Get the label of the "companyName" field:$("#companyName").find("span.textLabel") - .children() searches just within the child nodes.
Ex: Get all the rows in a Dynaform with the ID "3088873965642528e4073a7021293108":$("#3088873965642528e4073a7021293108").children("div.row") - .siblings() searches within the sibling nodes in the DOM.
Ex: Get all the controls in the same row as the "companyName" field:$("#companyName").siblings() - .closest() searches for the closest matching element in the DOM.
Ex: Get the form for the "companyName" field:$("#companyName").closest("form") - .first() gets the first element returned by the initial selector.
Ex: Get the first textbox in the form:$("div.pmdynaform-field-text").first() - .eq(index) gets a specific element from the array of elements returned by a selector. The index starts counting elements from the number
0.
Ex: Get the fourth textbox in the form:$("div.pmdynaform-field-text").eq(3)
