3.2 - 3.8 - JavaScript Functions and Methods - Controls

Methods for Controls

The following are custom methods provided by ProcessMaker to manipulate controls. All of these methods, except for setHintHtml(), are available in both the jQuery and Backbone objects of the control, so they can either be called with $("#id").method() or getFieldById("id").method(), or one of the other 3 functions that can can be used to obtain Backbone objects.

control.disableValidation()

The disableValidation() method deactivates the validation of a field. If its required property is marked, then the Dynaform will not check whether the field has a value when it is submitted. Likewise, if its validate property has a regular expression, it will not check whether the field's value complies with the regular expression.

$("#id").disableValidation()

Note: This method doesn't change the field's required or validate properties. If the field doesn't have required marked and doesn't have a regular expression for its validate property, then disableValidation() will not have any effect, because the field doesn't require any validation.

Example:

control.enableValidation()

The enableValidation() method activates the validation of a field. If its required property is marked, then the Dynaform is submitted, and it will check whether there is a value in the field. Likewise, if its validate property is a regular expression, it will check whether the field's value complies with the regular expression. If not, the submit will be halted and and a red error message will be displayed under the field.

$("#id").enableValidation()

Note: To use this method, the required property or the regular expression validation must be set. If the field doesn't have required marked or doesn't have a regular expression for its validate property, then enableValidation() will not have any effect.

Example:

control.getControl()

The getControl() method returns the jQuery object of a control's input field. For grids, please check this section.

$("#id").getControl()

Return Value:
This method returns the jQuery object of the control's input field.

Note: This method does not work with Titles, Subtitles, Labels, Panels, Images, Links, Files, Submits, Buttons and Subforms or with any field set to View mode. This method also does not work with Mobile controls.

Example with a textbox:

If getControl() is called for a radio button or a checkgroup, then it will return an array of the options. For example, the third option can be accessed as: $("#id").getControl()[2]
The length of this array be found with the $("#id").getControl().length property.

Example with a checkbox:

control.getHintHtml()

The getHintHtml() method returns the jQuery object for the <span> that holds a control's hint. Note that getHintHtml() returns an empty object {} for controls whose hint property is blank.

$("#id").getHintHtml()

Note: This method does not work with Backbone objects.

Examples:

To get the text in the hint, access the span's data-original-title, which is a custom data attribute that can be accessed using jQuery's attr() method.

Example:

control.getInfo()

The getInfo() method returns the model information about a control in a Dynaform.

$("#id").getInfo()

Return Value:
An object containing the attributes of a control. The properties depend upon the type of control. See the list of available attributes.

For a textbox:

Example:

The getInfo() method does not work with Dynaforms, subforms or fields inside grids. The model information for subforms can not be obtained, although getInfo() works with the controls inside subforms. To get the model information about the controls inside grids, use the columns attribute. For example, to get the label for the third control inside a grid with the ID "clientsGrid":

control.getLabel()

The getLabel() method returns the label of a control in a Dynaform.

$("#id").getLabel()

Note: This function does not work with panel controls since they do not have labels.

Example:

control.getText()

The getText() method returns the text of a control, depending on the type of control.

$("#id").getText() or getFieldById("id").getText()

Return Value:
The value returned by this function depends upon the type of control.

Control	Return Value
Dropdown boxes and Radio buttons	It returns the displayed text of the field's selected option.
Checkgroups	It returns a JSON string containing an array of the labels of the selected options. For example, a field to select countries might return '["United States", "Mexico", "Brazil"]'
Checkboxes	It returns the text label of the marked or unmarked option. If this text label hasn't been configured, then by default, a marked checkbox is "true" and an unmarked checkbox is "false".
Textboxes, Textareas, Suggest and Hidden fields	It returns the value of the field.
Datetimes	It returns the datetime in the control's configured format. For example, if the format is "MM/DD/YYYY" and the date is April 25, 2015, then it returns "04/25/2015"
Links	It returns the displayed text of the hyperlink.
Images	It returns the URL of the image file.
Grids	See: grid.getText().
File control	It returns the filename of the selected file, whether the file was uploaded in a previous step or just picked from the file system.

The getText() function does NOT work for other types of controls, such as buttons, titles, etc.

Example:

control.getValue()

The getValue() method returns the value of an input field in a Dynaform.

$("#id").getValue()

Return Value
The value returned by this function depends upon the type of control:

Control	Return Value
Textboxes, Textareas and Suggest boxes	This function returns the text entered into the field.
Dropdown boxes and Radio buttons	For input fields that have selectable options, it returns the internal value (key) of the selected option.
Checkboxes/Checkgroups	See Getting values in checkboxes/checkgroups below.
Datetime	It returns the entered datetime in standard YYYY-MM-DD HH:MM:SS format.
File control	It returns the filename of the selected file. If there is no selected file, then getValue() returns [] (an empty array). Note: If File controls are in grids, the getValue() method returns an empty array since files are not preserved in grids even if a file has been uploaded. Only for mobile version returns the file UID of uploaded files. Warning: The file control's value is not consistent, it might return an empty array, empty string, array of UIDs, file name or fake path. This is a known issue that will be fixed in future releases. As of ProcessMaker 3.2.2, getValue() returns the document UID after a file is selected and the case is routed.
Links	It returns the URL of the hyperlink.
Images	It returns the URL of the image file.
Titles, Subtitles, and Labels	It returns their text
Submit and Generic buttons	It returns the text displayed in the button.
Grids	It returns an array of arrays where the outer array holds the rows in the grid and the inner arrays hold the values of the fields in each row. See Getting values in grids below.
Panels	This method does NOT work with panels.

Example 1 - Searching in a textarea:

Example 2 - Checking for a selected value in a dropbox:

Example 3 - Checking for a selected value in a dropbox:

Checkboxes/Checkgroups

A checkbox contains a single checkable box. getValue() returns "1" if the checkbox is marked and "0" if unmarked. Its text label can be set in its options when creating its variable, but if not set, then by default it will be set to "true" if marked and to "false" in not marked.

Example 1:

Example 2:

control.setFocus()

Note: The control.setFocus() function is not supported on ProcessMaker Mobile for iOS. If working with ProcessMaker Mobile on Android, the focus is set in the control but the view does not scroll to the control that gained focus.

The control.setFocus() method sets the focus in a control's input field, meaning that the cursor is moved to that field. Note that this method is only available in the Backbone object of a control, but not in its jQuery object.

getFieldById("control-id").setFocus()

Example 1:

Example 2:

control.setLabel()

The setLabel() method sets the label of a control in a Dynaform.

$("#id").setLabel("newLabel")

Note: This function does not work with panel controls since they do not have labels.

Note: Calling setLabel() for a title, subtitle, button or submit control will reset its properties and remove any custom properties set by JavaScript. After calling setLabel(), these properties will need to be reset.

Example:

Note: The text of the new label may contain HTML entities such as > for < and € for €, but HTML tags, such as <em> and <br>, will be treated as normal text. To format a control's label, first use use jQuery's .find() method to search for the <span> with the "textlabel" class inside the control. Then, use its .html() method to add HTML code to the label.

Example:

control.setOnchange()

The control.setOnchange() method sets the onchange event handler for a single input field in the Dynaform, and is executed when the value of that field changes. Input fields inside grids are not supported by this method.

$("#control-id").setOnchange(function(newValue, oldValue) {...})

Another way to set the onchange event handler is to use a named function:

$("#control-id").setOnchange(func); function func(newValue, oldValue) { ... }

Parameter:
func: The function that is executed when the value of the field changes. It can either be an anonymous function defined on the spot or a named function that is defined in another place.

Example using a radiobutton:

Example using a File control:

Note: It is highly recommended to use the 'setOnchange' instead of the 'change' function. If it is absolutely neccesary to use the 'change' function then it is advisable to add an 'eventListener' to the Javascript code. This option is not recommended since the 'listener' will be executed every time the mouse is moved and it will take longer than simply using the 'setOnchange' function.

control.setText()

The setText() method sets the text of a control.

Note: As of ProcessMaker 3.5.0, the dependency query in a Suggest control that has configured the setText ProcessMaker Script method does not work when the Memory Cache is enabled.

$("#id").setText("text")

Parameter:
The "text" depends on the type of control:

Control	Parameter
Dropdown	Set the 'selected option'. This parameter must be one of the options already defined in the control. If the parameter does not exist in the dropdown's options, the dropdown will be displayed with its first option selected.
Radio button	Set to "" to select no option or to select the displayed text of one option.
Checkgroup	Set to an array of the labels of the selected options: ["option1", "option2", ...]
Checkboxes	Set to the text label of the marked or unmarked option. Alternatively, to mark or unmark a checkbox, set its text as same as its text label in the "options" property. If this text label hasn't been configured, then by default, a marked checkbox is "true" and an unmarked checkbox is "false".
Textboxes, textareas, suggest boxes and hidden controls	Set the new value of the field.
Datetimes	Set the displayed datetime according the control's format. For example, a datetime with the format "MM/DD/YYYY" can set the date to April 25, 2015 with the code: $("#id").setText("04/25/2015")
Links	Set the displayed text in the hyperlink.
Images	Set the URL that is the image's src.
Grid fields	See grid.setText().

Note that setText() does not work with other types of controls.

Note 1: setText is not available in file control because the text is a reference to a file in ProcessMaker.

Note 2: Calling setText() for a title, subtitle, button or submit control will reset its properties and remove any custom properties set by JavaScript. After calling setText(), these properties will need to be reset.

Example with a checkgroup:

Example with a checkbox:

Example with a dropdown:

control.setTextAsync()

Available Version: As of ProcessMaker 3.5.0.

The setTextAsync() method sets the text asynchronously in a control.

This asynchronous helper must always be used in PM Mobile and the web application only if there is a direct dependency that is asynchronous. For indirect dependencies, this method can not be used with nested async helpers: only use setOnchange() helper structure with the async helpers. If there is a static dependency that is not SQL, as a best practice use setValue() and setText() helpers instead.

$("#id").setTextAsync("text", function(){ ... })

Parameters:

• The "text" depends on the type of control:

  Control	Parameter
  Dropdown	Set the 'selected option'. This parameter must be one of the options already defined in the control. If the parameter does not exist in the dropdown's options, the dropdown will be displayed with its first option selected.
  Radio button	Set to "" to select no option or to select the displayed text of one option.
  Checkgroup	Set to an array of the labels of the selected options: ["option1", "option2", ...]
  Textboxes, textareas, and suggest boxes	Set the new value of the field.
  Grid fields	See grid.setTextAsync().

  Note: setTextAsync is not supported in other controls that do not have the SQL property. This method only works with dependencies, therefore they must have SQL settings.

• function(){}: Anonymous funtion that executes other asynchonous helpers.

Example

This example shows how to use setTextAsync() with a text control and a checkgroup control. Consider the following tables COUNTRIES, SUBDIVISION and LOCATION:

As seen in the SQL querys used, the LOCATION table has a double direct dependency with COUNTRIES and SUBDIVISION tables.

This is the code to set asynchronously LOCATION text control and LOCATION_CG checkgroup control values that depend directly from SUBDIVISION and COUNTRIES fields:

control.setValue()

The setValue() method sets the value of an input field, sets the source URL of an image, or sets the displayed text of other types of controls in a Dynaform. How to set a field's value depends on its type of field. In HTML, all numbers are treated as strings, so numbers automatically convert to strings when they are set as the value of a field.

Note: As of ProcessMaker 3.5.0, the dependency query in a Suggest control that has configured the setValue ProcessMaker Script methods does not work when the Memory Cache is enabled.

Control	Code example
Textbox, textarea, suggest, dropdown box, radio button, datetime, hidden. The src in an image. The displayed text in a title, subtitle, label, button. The URL used in a link.	$("#id").setValue("value")
Checkgroups	$("#checkgroup-id").setValue(["value1", "value2", ...])
Grids	$("#gridId").setValue("value", row, col)
Panels, Subforms and Files	This function does NOT work. Instead, use code such as: $("#mypanel").find(".panel-body").html("<em>New content!</em>")

Note: setValue is not available in file control because the value is a reference to a file in ProcessMaker.

Warning: Calling setValue() for a title, subtitle, button or submit control will reset its properties and remove any custom properties set by JavaScript. After calling setValue(), these properties will need to be reset.

Textboxes and textareas:

For textboxes and textareas, enter a new value that will be set in the field.

$("#id").setValue("value")

For example, to set the value of a field with the ID "contractDescription":

Use \n to insert a new line and \t to insert a tab in a textarea. For example:

Example:

Suggest, dropdown boxes and radio buttons:

Checkboxes:

Checkboxes can only be based upon boolean variables and only have one checkable box. To mark (select) a checkbox, set its value to "1". To unmark (deselect) a checkbox, set its value to "0".

Example:

Checkgroups:

A checkgroup is a group of checkable boxes and it is based upon an array variable. It contains as many checkboxes as the number of its options, and multiple options can be selected at once. The setValue() method sets which checkboxes are marked (selected) by passing the checkgroup an array of values (keys) to be marked. Remember that the value(s) are the key(s) for the selected option(s), not the label(s), which are the text displayed to the user:

$("#id").setValue(["value1", "value2", ...])

Example:

Datetimes:

To set the value of datetime fields, enter the datetime in ISO-8601 format, such as "YYYY-MM-DD" for dates or "YYYY-MM-DD hh:mm:ss" for datetimes, where YYYY is the year, MM is the month between 01 and 12, DD is the day between 01 and 31, hh is the hour between 00 and 23, mm is the minute between 00 and 59, and ss is the second between 00 and 59. Remember that months, days, hours, minutes and seconds must be expressed with two digits, so the first second of the year 2016 is "2016-01-01 00:00:00".

To clear the datetime field's value, use an empty string as the value.

Example:

Links:

Link fields contain both the URL and the text displayed to the user. Use the control.setValue() or link.setHref() method to set the URL of a link field and the control.setText() method to set the text of the link, which is displayed to the user.

Example:

Submit and generic buttons:

The setValue() method can be used to change the text displayed inside buttons.

Example:

Grids:

For grids, please check out the following documentation: grid.setValue()

control.setValueAsync()

Available Version: As of ProcessMaker 3.5.0.

The setValueAsync() method sets the value asynchronously in a control.

This asynchronous helper must always be used in PM Mobile and the web application only if there is a direct dependency that is asynchronous. For indirect dependencies, this method can not be used with nested async helpers: only use setOnchange() helper structure with the async helpers. If there is a static dependency that is not SQL, as a best practice use setValue() and setText() helpers instead.

$("#id").setValueAsync("value", function(){ ... })

Parameters:

• The "value" depends on the type of control:

  Control	Parameter
  Dropdown	Set the 'selected option'. This parameter must be one of the options already defined in the control. If the parameter does not exist in the dropdown's options, the dropdown will be displayed with its first option selected.
  Radio button	Set to "" to select no option or to select the displayed value of one option.
  Checkgroup	Set to an array of the labels of the selected options: ["option1", "option2", ...]
  Textboxes, textareas, and suggest boxes	Set the new value of the field.
  Grid fields	See grid.setValueAsync().

  Note: setValueAsync is not supported in other controls that do not have the SQL property. This method only works with dependencies, therefore they must have SQL settings.

• function(){}: Anonymous funtion that executes other asynchonous helpers.

Examples

1. This example shows how to use setValueAsync() with a text control and a checkgroup control. Consider the following tables COUNTRIES, SUBDIVISION and LOCATION:

   

   As seen in the SQL querys used, the LOCATION table has a double direct dependency with COUNTRIES and SUBDIVISION tables.

   This is the code to set asynchronously LOCATION text control and LOCATION_CG checkgroup control values that depend directly from SUBDIVISION and COUNTRIES fields:

   $("#COUNTRIES").setValueAsync("BO",function(){
       $("#SUBDIVISION").setValueAsync("L",function(){
           $("#LOCATION").setValueAsync("GUQ");
           $("#LOCATION_CG").setValueAsync(["LPB"]);
       });
   });

2. As a use case the setValueAsync() function in a Subform can be used when you are copying Dropdown values through a Radio control that allow select you copy or not the Dropdown value as in the following script:

   $(document).ready(function() {
       $("#TST_COPY").setOnchange(function(newValue, oldValue) {
           if (newValue == 1) {
               $("#TST_NAME_COPY").setValueAsync($("#TST_NAME").getValue());
               $("#TST_CITY_COPY").setValueAsync($("#TST_STATE").getValue());
           } else {
               $("#TST_NAME_COPY").setValueAsync("");
               $("#TST_CITY_COPY").setValueAsync("");
           }
       });
   });