Note: This function does not work with just the field names of checkgroups, radiogroups, and checkgroups. For example, this won't work:

This function, however, can be used to show/hide individual options in checkgroups and radiogroups and individual fields in grids. To show/hide an option in a checkgroup or radiogroup:

To show/hide a field in a grid:

hideRow()

This function is the same as hideRowById().

hideRowById()

hideRowById() hides the complete row of a DynaForm field. The row includes not only the field, but also its label and its surrounding cells.

Parameters:

• string fieldName: The name of the field that will be hidden and its complete row.

Return value:

• void: It does not return any value.

Example:
Hide the row of a field named "myField" when a button named "myButton" is clicked:

showRow()

This function is the same as showRowById().

showRowById()

showRowById() shows the complete row of a DynaForm field by specifying its field name.

Parameters:

• string fieldName: The name of the field, whose complete row will be shown.

Return value:

• void: It does not return any value.

Example:
Show the row containing a field named "myField" when a button named "myButton" is clicked:

hideRowById()

hideRowById() hides the rows of the DynaForm fields specified in an array of field names.

Parameters:

• array afieldNames: An array of the names of fields whose rows will be hidden. To hide checkgroups and radiogroups, specify one of the options within the group. Examples: "MyCheckGroup][OptionX" or "MyRadioGroup][OptionY"

Return value:
None.

Note: Grids can not hidden by this function due to this bug. For a workaround, see Hiding a grid.

Example:
Display the rows of the fields "price", "tax", "quantity", when the user marks the "PriceDetails" checkbox:

showRowById()

showRowById() shows the rows of the DynaForm fields specified in an array of field names.

Parameters:

• string afieldNames: An array of the names of fields whose rows will be shown.

Return value:

• void: It does not return any value.

Example:
Display the rows of the fields "price", "tax", "quantity", when the user marks the "PriceDetails" checkbox:

contractSubtitle()

contractSubtitle() contracts all the fields under a specified subtitle (until the next subtitle in the DynaForm), so they are hidden from view. Available from version 1.2-2467 on. Fields which have been hidden with this function will not be automatically validated, even if they have been defined as required="1" in the XML.

Parameters:

• string fieldName: The name of a subtitle field.

Return value:

None.

Note: This function cannot hide grids. To hide grids, see Hiding a Grid.

Example:

If a checkbox named "hideClientInfo" is marked, hide the fields under a subtitle named "clientInfoSection". If unmarked, then expand the subtitle:

expandSubtitle()

expandSubtitle() shows a subtitle field and all rows under it until the next subtitle in the DynaForm. This function is available from version 1.2-2467 on. If a field has been displayed with this function, then it will automatically be validated if it have been defined as required="1" in the XML.

Parameters:

• string subtitleField: The subtitle field object to expand.

Return value:

• void: The function does not return any value.

Example:

contractExpandSubtitle()

contractExpandSubtitle() shows or hides a subtitle field and all the rows beneath it until the next subtitle in the DynaForm. It works as a toggle switch, so if the subtitle is shown, then it will be hidden and if the subtitle is hidden, it will be shown. This function is useful for using with clickable images or buttons to contract/expand sections of a form.

Parameters:

• string subtitleField: The subtitle field object, which can be obtained with the getField() function.

Return value:

• void: The function does not return any value.

Example:

Saving DynaForms

submitForm()

submitForm() submits the DynaForm, so the form will be closed and the values in the fields are saved to the database. This is the same action as when a user clicks on a submit button.

Parameters:
None.

Return value:
None.

Example:
The following code automatically submits the DynaForm when a user selects the "no_details" option from the "selectDetails" dropdown box:

saveForm()

saveForm() saves the data in a DynaForm to the database (i.e., case variables are created for each field in the form). This function basically does the same thing as saveAndRefreshForm(), but it is faster since the form is not reloaded after sending the data to the ProcessMaker server with an AJAX call. Note that this function does not work in the Preview mode of the DynaForm Editor (since there is no case), but it does work when running a case. Available in version 2.0 and later.

Parameters:

• object oObject: A field object, whose parent form will be saved. Set to null or "" (an empty string) to save all forms in the current DynaForm.

Return value:
None.

Examples:
Save the DynaForm's data when clicking on the custom "save" button:

Save the DynaForm's data when clicking on the custom "save" button, then redirect the browser window to the address "http://example.com/externalfeedbackForm.php":

Automatically save the DynaForm data every 5 minutes, using the setInterval() and clearInterval() methods:

Time is expressed in milliseconds, it means that 60000 milliseconds is equivalent to 1 minute

saveAndRefreshForm()

saveAndRefreshForm() saves and refreshes the data in a form at the same time. Note that this function does not work in the Preview mode of the DynaForm Editor (since there is no case data to be saved), but it does work when running a case. Available in version 1.2-2425 and later.

Parameters:

• object objectName: A field object, whose parent form will be saved. Set to null or "" (an empty string) to save the first form found in the browser window, which in most cases will be the current DynaForm. However, using null might cause problems if running ProcessMaker inside an <iform> in a web page which has other forms.

Return value:

• void: The function does not return any value.

Example:

Note: It can take a while to save DynaForm data to a remote server. If redirecting the web page to a new location it may be a good idea to delay subsequent javascript commands to give saveAndRefreshForm() enough time to execute. For example, here a three second delay is added before redirecting the web browser to the cases list:

saveAndRedirectForm()

saveAndRedirectForm() saves the data in a DynaForm to the database just like the saveForm() function, then redirects the web browser to a specified URL. Note that this function does not save any data in the Preview mode of the DynaForm Editor (since there is no case), but it does save data when running a case. Available in version 2.0 and later.

Parameters:

• object oObject: A field object, whose parent form will be saved. Set to null or "" (an empty string) to save all forms in the current DynaForm.
• string sLocation: A URL where the web browser will be redirected after saving the form. If set to "" (an empty string) or a direction which is not regarded as valid by the validateURL() function, then it will not redirect the web browser.

Return value:
None.

Example:
When clicking on the custom "save" button, save the current DynaForm and redirect back to the cases list:

Requiring Fields

removeRequiredById()

removeRequiredById() disables the automatic validation of a specified field which is required by DynaForms. This function allows fields which were defined as required in the XML of a DynaForm to be omitted from validation (i.e., the user will be allowed to submit the form if this field is blank). Available in version 1.2-2467 and later.

Parameters:

• string fieldName: The name of the field. If using a grid field, then use a field name like "grid-name][row-number][field-name". For example: "MyGrid][2][MyField"

Return value:

• void: The function does not return any value.

Note 1: This function only works on fields which were marked as Required in their definition.

Note 2: This function does not remove the red asterisk * next to the field label, indicating that it is required. JavaScript can be used to remove the asterisk. See the example below.

Examples:
Remove the required property from the "validationCode" field when the "noValidate" checkbox is marked. When not marked, the required property is enabled. In addition, the red asterisk to the left of the field label is also removed or added:

When a submit button named "submitNoValidate" is clicked, the form is submitted but none of the fields in the form are validated:

Examples with Grid Fields:
The removeRequiredById() function can only be called on a single grid field in a specified row, not for the grid fields in all rows.

For example, to remove the required property from a grid field named "clientName" in the second row of a grid named "clientList":

Removing the required property from all grid fields in every row is more difficult because the removeRequiredById() function has to be called for the field in every row in the grid. If the grid allows rows to be added or deleted, then it is recommended to remove the required property from the grid fields in an event handler for the form's submit action.

For example:

If needing to determine whether to remove or not remove the required property at a point before the submit action, then set a variable which is read by the submit event handler.

For example, if a checkbox named "requireNameCheckbox" is marked, it sets the "removeRequiredName" variable which is used by the submit event handler:

enableRequiredById()

enableRequiredById() enables the automatic validation of a specified field which is required (i.e., the user will not be allowed to submit the form if this field is blank). This function can be used to reactivate the validation of required fields which were previously disabled with removeRequiredById(). Available in version 1.2-2467 and later.

Parameters:

• string fieldName: The name of the field to be required.

Return value:

• void: The function does not return any value.

Note: This function only works on fields which were marked as Required in their definition. If needing to require fields which weren't marked as Required in their definition, then add custom code to submit which checks if the field is blank. See this example.

Example:

Where:

• repSubject: The name of the field that is required by the Dynaform.
• mybutton: The button that will disable the automatic validation.
• enaRequired: The name of the function.

form.verifyRequiredFields()

form.verifyRequiredFields() method highlights all the required fields in a form that are blank.

Parameters:
None.

Return value:
None.

Note: The form object in version 1.2, has a variable name like:

object_12565951048b858ca883c57091712352_40681270548d66e46554829029416532

The form object in version 2.0, has a variable name like:

form_WkpabW8yaWxhbU9rcUphaHFtbWFxR3FnWmNaaW4ybWphMm1pcDJxa3BXcG9wbXFtWnBob29XQ3FhSldrcVdYT3EyNXNxSktsWTVkZ29HaW9aMmFucldMTTZhS3BvbMKwbG9NOA______

Since the form variable name can change, it is best to concatenate the variable name with JavaScript and dynamically execute it with the eval() function. See the examples below.

Example in ProcessMaker version 1.2:

Example in ProcessMaker version 2.0:

validateForm()

validateForm() checks whether any required fields in the current DynaForm are blank. If they are blank, a message appears informing the user to fill in the blank fields and they are highlighted in pink.

Parameters:

• string sRequiredFields: An array of objects with information about the writable fields in the form which has been serialized as a JSON string. The contents of the DynaformRequiredFields hidden field can be used for this parameter.

Return value:

• boolean: Returns true if there are no blank required fields. Returns false if there are any required fields which are blank.

Example:
Validate the fields when clicking on the "saveIt" button. If there are not blank required fields, then submit the form:

Disabling and Enabling Fields

disable()

disable() greys out a DynaForm field, so its value can not be changed by the user (or clicked in the case of a button). After being disabled, the field is grayed out and the user cannot interact with it.

Parameters:

• object field: The field object which will be disabled.

Return value:

• void: It does not return any value.

Note: The data in a disabled field is not saved as a case variable when a DynaForm is submitted. To make sure that its data gets saved, either enable the field when the DynaForm is submitted or set the readOnly property of the field to true instead of disabling the field.

Example:

Where:

• disField: The name of the function.
• myfield: The field that will grey out.
• mybutton: The name of the button that will disable myfield when clicked.

disableById()

disableById() works the same as the disable() function, but it is a more convenient version of that function which looks up an object by its field name.

Parameters:

• string fieldName: The name of the field to be disable.

Return value:

• void: It does not return any value.

Example:

Where:

• disByIdField: The name of the function.
• myfield: The field that will be disable.
• mybutton: The name of the button that will disable myfield.

enable()

enable() activates a field, so its value can be changed by the user (or clicked in the case of a button). It sets its HTML disabled property to false.

Parameters:

• object field: The field object to enable, which can be obtained with the getField() function.

Return value:

• void: It does not return any value. .

Example:

Where:

• enaField: The name of the function.
• myfield: The field that will grey out.
• mybutton: The name of the button that will enable myfield when clicked.

enableById()

enableById() is a more convenient version of the enable() function, since its parameter is a field name, rather than a field object.

Parameters:

• string fieldName: The name of the field to enable.

Return value:

• void: It does not return any value.

Example:

Where:

• disByIdField: The name of the function.
• myfield: The field that will be enable.
• mybutton: The name of the button that will enable myfield.

Field Focus

setFocus()

setFocus() moves the focus in a specific field in a DynaForm so the user can interact with it directly without having move the mouse and clicking on the object. If the object is an input object such as a textbox, the cursor will be placed in the object so the user can begin changing its value. If the object is a button, it will receive the focus and the user can click it by pressing the ENTER key.

Parameters:

• object field: The object for the field where the focus will be moved. Use the getField() function to get the field object.

Return value:

• void: It does not return any value.

Example:

Where:

• setFocusField: The name of the function.
• myfield: The field that you want be focus on.
• mybutton: The name of the button that will focus the attention on myfield.

setFocusById()

setFocusById() works the same as the setFocus() function, but it is a more convenient version of that function which looks up a field by its field name and moves the focus to that field.

Parameters:

• string fieldName: The field name of the field which will receive the focus.

Return value:

• void: It does not return any value.

Example:

Where:

• setFocusByIdField: The name of the function.
• myfield: The field that you want be focus on.
• mybutton: The name of the button that will focus the attention on myfield.

dynaformSetFocus()

dynaformSetFocus() sets the focus in the first field in a DynaForm. This function is useful when resetting a DynaForm back to its original state.

Parameters:
None.

Return value:

• void: It does not return any value.

Example:

Read-Only

toReadOnly()

toReadOnly() sets the specified field to read-only. Unlike activating the read only property of a field which doesn't change the appearance of the field, this function changes the background of the field to the color grey (#CCCCCC).

Parameters:

• object field: The field object which will be set to read-only. Use the getField() function to get the field object.

Return value:
None.

Note: There is no function to set fields back so they are writable after calling this function, so the .readOnly and .style.background properties will have to be manually set to undo the changes caused by this function.

Example:
The following code clears the field "telephoneNo" and sets it to read-only when any option except "telephone" is selected from the "howContact" dropdown box:

toReadOnlyById()

toReadOnlyById() sets the specified field to read-only, just like the toReadOnly() function, but it is more convenient because its parameter is the field name.

Parameters:

• object fieldName: The name of the field which will be set to read-only.

Return value:
None.

Notes:

• There is no function to set fields back so they are writable after calling this function, so the .readOnly and .style.background properties will have to be manually set to undo the changes caused by this function.

• Setting the readOnly property in JavaScript does not affect dropdown boxes, listboxes, yes/no boxes, checkboxes and checkgroups.

Examples:
The following code checks whether the "specifyName" hidden field was set to "yes" in a prior trigger when the DynaForm loads. If so, then it sets the "firstName" and "lastName" fields to read-only:

Highlight Functions

G.highLight()

G.highLight() sets the background color of a field to pink (#ffcaca). The field blinks once in red (#ff9d9d) after calling the function to call the user's attention to the field.

Parameters:

• object field: The field to be highlighted. Use getField() or getGridField() to obtain the field object.

Return Value:
None.

Note: To remove the highlighting from a field after calling G.highLight(), set the field's style.backgroundColor to an empty string. To make the highlighting disappear after a fixed amount of time, use the setTimeout() function to set the style.backgroundColor back to an empty string after a certain amount of time. (See examples below).

Examples:
If a user enters a value in the "bidTotal" field which is over the "maxBid", then highlight the "BidTotal" field and set focus to the "bidTotal" so the user can change it. If the "bidTotal" is less than the "maxBid", then the

The following code highlights all the empty fields in a DynaForm for three seconds when a DynaForm first loads.

highlightRow()

highlightRow() sets the background color of a row (or any object) to a specified color.

Parameters:

• object obj: An object whose background color should be changed. A row in a DynaForm can obtained with the getRow() function. The cell holding a DynaForm field can be obtained with: getField("field-name").parentNode
• string color: A color which can either be one of the 147 standard color names (such as "red") or the hexadecimal RGB (red-green-blue) numbers for the color (such as "#F2C2A1").

Return Value:
None.

Note for Normal Fields: For normal fields (not grid fields), this function only sets the background color of the cell holding the label, but not the background color of the cell holding the field itself. To set the background color around the field, use: highlightRow(getField("field-name").parentNode, "color");

Note for Grids: This function sets the background color of the whole row in grids, but that background color is quickly overwritten for every other row in the grid, which is set to a light blue color.

Examples:
If a currency field named "bidAmount" is set to a value over $1000, the background color of its row is changed to green:

Set the background color of any row in a grid to yellow, whose "amount" field is over $100:

Grid Functions

getGridField()

getGridField() returns a field inside of a row in a grid. This function is useful when referencing the properties of a field in a grid (such as its .value property).

Parameters:

• string gridName: The field name for the grid.
• int rowNo: The number of the row in the grid, which starts counting from the number 1.
• string fieldName: The name of a field inside the grid.

Return value:

• object: Returns the specified field inside a grid.

Examples:
Set the values of the "firstName" and "lastName" fields in the first row of the "contactsGrid" when the DynaForm loads:

When a DynaForm's submit button is clicked, the following code loops through a grid and creates a list of all the first and last names in the grid and saves them to a hidden field named "contactsList", so they can be displayed in a textarea in a subsequent DynaForm.

getGridValueById()

getGridValueById() returns the value of a specified grid field.

Parameters:

• string gridName: The field name for the grid.
• int rowNo: The number of the row in the grid, which starts counting from the number 1.
• string fieldName: The name of a field inside the grid.

Return value:

• string: Returns the value of the specified grid field as a string. If the content of the field is a number or date, it will need to be converted.

Example:
The following code displays an alert showing the total price including tax whenever the "price" in the first row of a grid is changed:

Number_Rows_Grid()

Number_Rows_Grid() returns the number of rows in a grid.

Parameters:

• string gridName: The field name for the grid.
• string fieldName: The name of any field inside the grid.

Return value:

• string: Returns the number of rows in a grid. If the grid field doesn't exist or there are zero rows, this function returns 0.

Example:
Loop through all the rows in a grid named "contactsGrid" and clear their "firstName", "lastName" and "address" fields:

getObject()

getObject() returns an object representing a grid in a DynaForm. This object contains the grid methods, such as grid.addGridRow() and grid.deleteGridRow(). Available from version 1.2-2372 on.

Parameters:

• string gridName: The field name of the grid.

Return value:

• object: The grid object.

Examples:
To better understand the structure of a grid object, examine its contents with var_dump():

grid.getElementByName()

grid.getElementByName() returns the specified grid field object for a specified row.

Parameters:

• int iRow: The number of the row in the grid. Remember that the counting of rows starts from 1.
• string sName: The name of the grid field.

Return value:

• object: The object of the specified grid field.

Example:
When the user leaves the "contactsGrid", set the background color of all "lastName" fields which are blank to yellow in the "contactsGrid":

grid.getElementValueByName()

grid.getElementValueByName() returns the value of a specified grid field for a specified row.

Parameters:

• int iRow: The number of the row in the grid. Remember that the counting of rows starts from 1.
• string sName: The name of the grid field.

Return value:

• string: The value of the specified grid field.

Example:
When a new row is added to the "accountsGrid", automatically copy the "accountName" from the previous row:

grid.getFunctionResult()

grid.getFunctionResult() returns the result of an aggregate function (sum or avg) for a grid column.

Parameters:

• string sName: The name of the grid field which has an aggregate function.

Return value:

• string: The result of the aggregate function (sum or avg). Remember to convert it to a number before using it in mathematical operations.

Example:
When the "price" field in the "productsGrid" or the "taxRate" field (outside the grid) changes, calculate the "total" based upon the sum of the "price" column, multipled by the "taxRate":

grid.addGridRow()

The grid.addGridRow() method adds a new row to the bottom of a grid object. The grid object can be obtained with the getObject() function.

Parameters:
None.

Return value:
None.

Warning: The addGridRow() method does not work in the DynaForm editor in versions 2.0.36 - 2.0.39 due to this bug, but it does work when executing cases.

Example:
When the user clicks on the "addAccount" button, add a new row to a grid named "AccountsGrid" and then insert the value of the "accountName" and "accountNo" fields into the "name" and "no" grid fields in the new row:

grid.deleteGridRow()

The grid.deleteGridRow() method deletes a specified row from a grid object. The grid object can be obtained with the getObject() function.

Parameters:

• variant sRow: The number of the row in the grid. Remember that the counting of rows starts from 1. Can pass the row number as either a string or a number. If the number is enclosed in square brackets such as "[3]" (as is found in grid field ids), then the square brackets will be stripped.
• boolean bWithoutConfirm: An optional parameter available in version 2.0.30 and later. If not included or set to false then a message will appear asking the user to confirm the deletion of the row. Set to true to delete the row without confirmation from the user.

Return value:

• boolean: Returns false if unable to delete a row, because it doesn't exist or because it is the only row in the grid.

Warning: This function does not work correctly in the DynaForm Designer, but it does work when running a case.

Example:
Delete all the rows in a grid named "contactsGrid", when a user click on the "clearGrid" button:

Data Manipulation Functions

isNumber()

isNumber() evaluates if the sent value is numeric. The only parameter for this function is the value.

Parameters:

• variant value: This is the value that the function will evaluate.

Return value:

• boolean: The function returns a boolean value (true = 1 or false = 0).

Example:

Where:

• x: A variable defined as a string.
• y: A variable defined as a integer.

roundNumber()

roundNumber() rounds a number to a specified number of decimal places. If the number decimal places is not specified or is 0, then 2 decimal places are taken by default.

Parameters:

• variant value: This is the value that the function will round. It can be a float, int, or string (which converts to a number).
• int number: This is the number of decimals wished.

Return value:

• float: The function returns the rounded number.

Note: When a floating point number is assigned to a DynaForm field it is automatically converted into a string, but JavaScript's toString() method drops any zeros, so 84.30 becomes "84.3". To ensure that zeros are displayed, use the roundNumber() function to round the number to a specified number of decimal places, then convert the number to a string with that specified number of decimal places with the toFixed() method. For example:

To just round to the nearest whole number, use the Math.round() function. For example:

Example:
When the "price" or "quantity" field changes, multiple the two fields and round it to two decimal places before inserting it into the "total" field:

creaZero()

creaZero() creates a string of zeros, whose length is determined by its parameter.

Parameters:

• int number: This is the number of zeros that will be added.

Return value:

• string: The function returns a string with the number of zeros specified.

Example:

Where:

• x: A string variable.
• y: The number of zeros wished.

toUnmaskNumber()

toUnmaskNumber() strips any "," (commas), " " (spaces), "%" (percent signs) and "$" dollar signs from a string and converts it into a floating point number.

Parameters:

• variant sNumber: A string or number to be converted into a floating point number.

Return value:

• float: The function returns a floating point number.

Example:
In this example, the string "9.025,123" is converted into the number 9.025123:

validateURL()

validateURL() checks whether a string appears to be a valid URL (web address) which starts with "http://" or "https://" and appears to have a domain name or IP address. It only checks whether the URL matches a certain pattern of characters, so the URL may or may not exist in reality.

Parameters:

• string url: The URL (Universal Resource Locator) to test.

Return value:

• boolean: Returns true if appears to be a valid URL or false if it doesn't match the specified pattern.

Example:
When a user finishes entering the URL for a company website, an alert informs the user if the address appears to be invalid.

removeCurrencySign()

removeCurrencySign() strips all characters which are "$" (dollar signs), " " (spaces) and "," (commas) and returns a string without those characters. This function can be used before converting the value from a currency field to a number.

Parameters:

• variant sNumber: A string or number.

Return value:

• boolean: Returns a string without dollar signs, spaces or commas.

Example:
Show an alert message if the "price" times the "quantity" is over the maximum budget.

removePercentageSign()

removePercentageSign() strips all characters which are "%" (percent signs), " " (spaces) and "," (commas) and returns a string without those characters. This function can be used before converting the value from a percentage field to a number.

Parameters:

• variant sNumber: A string or number.

Return value:

• string: Returns a string without dollar signs, spaces or commas.

Example:
Change the border color of the "price" field if the price plus tax is over budget:

htmlentities()

htmlentities() converts a string into its HTML entities, so characters are converted into an HTML code which can not be confused by the character encoding. For example, ">" becomes "&gt;" and "á" becomes "&aacute;". This function is useful for saving text which will later be displayed in email or output document templates where the character encoding may cause problems. Note that this function will only convert 8 bit characters found in Roman alphabet languages. It can not be used to convert languages like Russian, Greek, Chinese, etc.

Parameters:

• string str: A string to convert to HTML entities.
• string quote_style: Set to "ENT_QUOTES" to convert quotation marks into HTML entities or "ENT_NOQUOTES" to not convert quotation marks.

Return value:

• string: Returns the converted string.

Example:
A DynaForm has a textarea named "MessageToEmployee" which is the message to be inserted into a form letter to an employee. JavaScript code copies the text of this message into a hidden field named "MessageToEmployeeHtml" whose contents will be later inserted into an email template:

fix()

fix() sets a string (which is how fields store numbers) to have a specified number of decimal digits. This function just drops any extra digits and does not round. If rounding is needed, see Converting numbers to strings.

Parameters:

• string val: A number in the format of a string. This function must be passed a string.
• int dec: The number of decimal digits.

Return value:

• string: Returns a string of the number with the specified number of decimal digits.

Note: This function should only be used with strings. If using numbers, it is recommended to use the number.toFixed() method.

Example:
When a user finishes entering the URL for a company website, an alert informs the user if the address appears to be invalid.

stripslashes()

stripslashes() returns a string which has removed the backslashes "\" before quotation marks. Backslashes are used in SQL to escape quotation marks so they can be used inside a string and not terminate it.

Parameters:

• string str: A string of characters.

Return value:

• string: A string with the backslashes removed.

Example: Strip the backslashes from the string "Don\'t say \"hello\" to him", so it becomes "Don't say "hello" to him":

addslashes()

addslashes() returns a string which has added backslashes "\" before quotation marks (' or "). Backslashes are used in SQL to escape quotation marks (" or ') so they can be used inside a string and not terminate it.

Parameters:

• string str: A string of characters.

Return value:

• string: A string with the backslashes added before quotation marks.

Example: Add backslashes to the string "Don't say "hello" to him", so it becomes "Don\'t say \"hello\" to him":

string.trim()

string.trim() method returns a string which has eliminated all leading and trailing spaces from a string.

Parameters:
None.

Return value:

• string: A string with all leading and trailing spaces stripped.

Examples:
Convert " this is a test! " to "this is a test!";:

When the "firstName" and "lastName" fields are changed, trim and concatenate them before inserting into the read-only "fullName" field:

Trim the "accountName" field when the DynaForm is submitted:

variant.toJSONString()

variant.toJSONString() method returns the value of an object converted into a JSON string. This method is available for DynaForm fields, strings, numbers, arrays, and objects.

Parameters:
None.

Return value:

• string: A JSON string.

Examples:

Date Functions

compareDates()

compareDates() compares two dates if one of them is greater or lesser the function returns a false value it means that the dates are not equal. On the other hand, if the function returns a true value it means that the dates are equal.

Parameters:

• string dateA: The first input date to be compared. The input date must be a string in the format 'YYYY-MM-DD'. (Any time information will be ignored.)
• string dateB: The second input date to be compared. The input date must be a string in the format 'YYYY-MM-DD'. (Any time information will be ignored.)
• boolean byDays: To compare the date by days, then set to true. To only compare the year and month, but not the day, then set to false.

Return value:

• boolean: The function returns true if the dates are equal and false if they are unequal.

Note: This function only works with dates in the default 'YYYY-MM-DD' format. If using dates with different formats, reorder the date string with JavaScript. (See example for diff_date() below.) To compare dates with different masks and do more advanced comparisons, see Accessing Dates with JavaScript.

Examples:
Comparing whether the "DueDate" and "DeliveryDate" are the same day:

Comparing whether the "DueDate" and "DeliveryDate" are in the same month:

diff_date()

diff_date() calculates the difference in days between two dates which use the default "YYYY-MM-DD" format.

Parameters:

• string date1: A date string in the default "YYYY-MM-DD" format.
• string date2: A date string in the default "YYYY-MM-DD" format.

Return value:

• int: Returns the number of whole days of difference between two dates. If date1 is before date2, then the number will be negative.

Examples: When a user finishes entering the URL for a company website, an alert informs the user if the address appears to be invalid.

In this case the dates use the format "MM/DD/YYYY", so they will have to reordered as "YYYY-MM-DD" before being passed to diff_date():

validDate()

validDate() tests whether a date field (or any other type of field) has a valid date. After version 2.0.32, it can check fields which have any format for the date, as long as it includes a four digit year, a two digit month and a two digit day.

Parameters:

• string dateFieldName: The name of a date field.
• boolean required: Set to true, if the date field is not allowed to be blank. If allowed to be blank, then set to false.

Return value:

• boolean: Returns true if the date field contains a valid date value; otherwise returns false.

Warning: This function did not work before before version 2.0.32 due to this bug.

Example:
Check whether the input in a textbox named "dueDate" is a valid date when the user leaves the field. If not, highlight the field in pink:

datePicker4()

datePicker4() sets the mask, date range and time option for a date field in version 2.0 and later.

Parameters:

• variant obj: An unused parameter that can be set to "" (an empty string).
• string id: The id for the date field. Remember that DynaForm fields use the id: "form[field-name]"
• string mask: The mask for the date field.
• string startDate: The starting date for the date range in the date picker dialog in the format "YYYY-MM-DD".
• string endDate: The starting date for the date range in the date picker dialog in the format "YYYY-MM-DD".
• boolean showTime: To show the time (hours and minutes), set to true; otherwise set to false. This parameter is currently unused, although it may be implemented in future versions of Processmaker, so it is unused. To have the current time automatically inserted in the date, add the hours and minutes codes to the mask.

Return Value:

• void: This function does not return any value.

Examples:
Set the "deliveryDate" date field to use the mask "%d-%m-%Y", so it will have the format "DD-MM-YYYY" and set its date range from January 1, 2010 to December 31 2013:

In this example, the starting date of the date range for the "dueDate" date field is set by the value of the "orderDate" field. The ending date is set to 10 days after the "orderDate". The date field is set to use an English style date which has the mask "%m/%d/%Y":

Cookie Functions

createCookie()

createCookie() creates a cookie which is a name-value pair which is stored on the local browser for set amount of time. Cookies are commonly used to store temporary information which shouldn't be lost every time a web page unloads or is refreshed.

Parameters:

• string name: The name of the cookie.
• string value: The value of the cookie.
• int days: The number of days to store the cookie.

Return Value:
None.

Example:
Store the client name for a week when a DynaForm is submitted, so the same client name can be auto inserted in subsequent DynaForms for the next week in that web browser.

readCookie()

readCookie() returns the value of a previously stored cookie.

Parameters:

• string name: The name of the cookie.

Return Value:

• string: Returns the value of the cookie. If the cookie doesn't exist or it has expired, then it returns null.

Example:
When a DynaForm loads, check if the "clientName" cookie (which was set in the previous example) exists. If so, insert its value into the "contactName" field.

eraseCookie()

eraseCookie() deletes a previously stored cookie.

Parameters:

• string name: The name of the cookie to delete.

Return Value:
None.

Example:
If the user clicks on a reset button named "resetButton", then "clientName" cookie is deleted:

Messages to the User

Standard JavaScript functions such as alert(), confirm(), and prompt() can be used, but ProcessMaker also provides custom functions to display messages to the user.

Unlike the standard JavaScript functions, ProcessMaker's custom message functions do not wait until the user closes the message box. Any code immediately after the message function will immediately execute and not wait for the response of the user to the message. If needing to wait for the response of the user, then use the setInterval() and clearInterval() functions to execute code after the user responds. See the examples below for msgBox() and leimnud.module.app.confirm().

G.alert()

G.alert() displays a message to the user. It is very similar to the standard alert() function, but the title of the message can be specified and the message box matches the ProcessMaker style.

Parameters:

• string msg: The text to display to the user. HTML formatting tags can be used. To insert a newline, use <br>.
• string title: The title of the message box. HTML formatting tags can be used.

Return Value:
None.

Note: The width of the message box will not change, but the height of the message box will adjust to accommodate larger texts so we recommend to use short texts.

Example:
When a DynaForm is submitted, check whether the "estimate", "transport" and "taxes" fields sum up to more than $100 and less than $1000. If not stop the submit and display a message to the user to change the quantities in the fields.

msgBox()

msgBox() displays a message to the user. The style of the message box changes depending upon its type parameter, so it can be used to simply inform the user (similar to the standard alert() function) or to receive confirmation from the user (similar to the standard confirm() function).

Parameters:

• string msg: The text to display to the user. HTML formatting tags can be used. To insert a newline, use <br>.
• string type: The type of message box, which can be "info", "alert", or "confirm". The icon displayed in the message box will adjust according to the type. "info" and "alert" message boxes, display only an "Accept" button, while "confirm" message boxes display "Accept" and "Cancel" buttons. If the type parameter is not defined, then it will default to "info". If the type is not set to one of the three acceptable values, then the message box will not display.
• object callbackAccept: A function to be executed when the user clicks on the "Accept" button. If no callback function is neeeded, set to null or do not include the parameter in the function call.
• object callbackCancel: A function to be executed when the user clicks on the "Cancel" button (which only exists for "confirm" message boxes). If no callback function is neeeded, set to null or do not include the parameter in the function call.

Return Value:
None.

Note 1: If the user closes the message box by clicks on [x] in the upper right hand corner, then no callback function will be executed.

Note 2:The height and width of the message box will not adjust accommodate larger texts. If the msg is longer than two lines, vertical scroll bars will appear to allow larger texts to be read.

Example 1:
When a user marks the "notifyClient" checkbox, an "info" message box appears informing that user that a letter needs to be sent out by the user in the next week. The current time is automatically inserted into the "notifyTime" textbox when the user clicks on the "Accept" button.

Example 2:
When a user marks the "notifyClient" checkbox, a "confirm" message box appears asking whether the client should be notified via email. If the "Accept" button is clicked, then an an anonymous callback function is executed to set the "sendEmail" hidden field to "yes". If the "Cancel" button is clicked, then the "sendEmail" hidden field is set to "no":

Example 3:
When a user clicks on the "saveData" button, a "confirm" message box appears asking whether the form data should be saved. If the user click on "Accept", the variable resp will be set to "yes". If the user clicks on "Cancel", it will be set to "no". A polling function is activated with the setInterval() function, which checks every 100 milliseconds whether the user has responded by looking at the resp variable. If the user has responded then the polling function will be removed with clearInterval(). If the response of the user was "yes", then call the saveForm() function to save the data in the form to the database. (Note: it would be much easier to just call saveForm() with the "Accept" callback function, but this example is provided to demonstrate how to set a polling function with setInterval() and clearInterval().)

commonDialog()

commonDialog() is a generic function to create custom message boxes to interact with the user.

leimnud.module.app.confirm()

leimnud.module.app.confirm() is used to display a confirmation message to the user. It displays a panel with a question which the user can respond to by clicking on the Accept button or the Cancel button.

Properties:

• label: A text message with a question for the user. HTML tags can be used to add formatting to the text. Use <br> to add line breaks.
• action: A named or anonymous function to be executed when the user clicks on the Accept button.
• cancel: Optional. A named or anonymous function to be executed when the user clicks on the Cancel button.
• ...: Optional. Any other properties which can be defined for panels.

Note: If needing to check which button was clicked by the user, then set up a polling function with setInterval(). See example 2 below.

Example 1:
When the user clicks on the "SaveButton", check whether the user has selected a client in the "selectClient" dropdown box. If not, then display a confirmation message informing the user that the client is blank and asking whether the form should be saved. If the user clicks on Accept, then an anonymous function is executed which submits the form. If the user clicks on Cancel, then another anonymous function is executed which highlights the blank "selectClient" dropdown box to direct the user's attention to that field.

Example 2:
A confirmation message is displayed to ask users if they accept the contract. A polling function is created to check whether the user clicked on Accept or Cancel. Both buttons call anonymous functions to set a value in the response variable. Once the response variable is set, then the polling function is terminated with clearInterval(). If the response is "yes" (accept), then the contract fields are displayed in the DynaForm. If "no" (cancel), then the contract fields are hidden.

leimnud.module.app.alert()

leimnud.module.app.alert() is used to display a message to the user. It displays a panel with a message with an Accept button below. Set an anonymous or named function to be called when the user clicks on the Accept button.

Properties:

• label: A text message with a question for the user. HTML tags can be used to add formatting to the text. Use <br> to add line breaks.
• action: Optional. A named or anonymous function to be executed when the user clicks on the Accept button.
• ...: Optional. Any other properties which can be defined for panels.

Example:
Display the text of a contract to the user after the user clicks on button named "displayContract". When the user clicks on Accept, then hide the "ContractDetails" textbox.

leimnud.module.app.prompt()

leimnud.module.app.prompt() asks a user to input a value. It displays a panel with a message and a textbox, with Accept and Cancel buttons below.

Properties:

• label: A text message with a question for the user. HTML tags can be used to add formatting to the text. Use <br> to add line breaks.
• action: Optional. A named or anonymous function to be executed when the user clicks on the Accept button. Its first parameter will be the value entered into the prompt's textbox by the user.
• cancel: Optional. A named or anonymous function to be executed when the user clicks on the Cancel button.
• ...: Optional. Any other properties which can be defined for panels.

Example:
When the DynaForm is displayed, display a prompt for the user to enter the name of a client:

The entered value will be inserted in the "clientName" field, which has a dependent field which is a listbox which searches in the database for the value of the "clientName" with this SQL query:

After the entered value is inserted in the "clientName" field, a "change" event is fired for the field to invoke the dependent field search to take place.

leimnud.module.panel()

leimnud.module.panel() is used to construct a "panel" which is a generic interface space in the LEIMNUD JavaScript framework. Panels can be used to construct customized dialog boxes with the user.

A LEIMNUD panel can have a number of member properties and methods. Some of the more common ones are listed below. To see the default values for a panel, examine its definition in <INSTALL-DIRECTORY>/gulliver/js/maborak/core/module.panel.js

Member Properties:

• object options: The options (characteristics) for the panel.
  • array statusBarButtons: An array of button objects to be displayed at the button of the panel.
    • object {value: "button-label"}: An object defining the button.
    • ...
  • object position: An object defining the position of the panel on the screen. It can contain:
    • object {center: boolean}
  • object size: An object defining the width and height of the panel, which contains:
    • object {w: int, h: int}
  • object control: An object defining the controls on the panel, which can contain:
    • object {close: boolean, resize: boolean}
  • object fx: An object defining the functions of the panel, which can contain:
    • object {modal: boolean}:
• object setStyle: Defines the style properties for the panel.
  • object content: Defines the style content. The following properties can be any appropriate CSS property. Here is a sample:
    • int padding: Pixels of padding between elements and the edges of the panel.
    • int paddingTop: Pixels to pad the top edge of the panel.
    • int paddingBottom: Pixels to pad the bottom edge of the panel.
    • int paddingRight: Pixels to pad the right edge of the panel.
    • int paddingLeft: Pixels to pad the left edge of the panel.
    • string textAlign: Pixels of padding between elements and the edges of the panel.
    • string background: The URL to an image to place in the background.
    • string backgroundRepeat: Set to "no-repeat" or "repeat" to determine whether the background image should be repeated to fill the available space.
    • string backgroundPosition: "Pixels or percentage where the background image should be places. The first number is the left position and the second number is the width of the image.
    • string backgroundColor: A named color or a hexadecimal RGB color. For no color, set to "transparent".
    • int borderWidth: Width of the border in pixels.
• object elements: Objects in the panel.
• object event: Define the event handlers for the object's events.

Panel Methods:

• make(): Displays the panel to the user.
• remove(): Closes the panel.
• addContent(string sContent): HTML content to add to the panel.
• fixContent(): Sets the positions of the elements in the panel, so they will not move afterwords.

Examples:

Browser Window Information

getClientWindowSize()

getClientWindowSize() returns the width and height in pixels of the web browser window.

Parameters:
None.

Return Value:
An object with the following elements:

• int width: The width in pixels of the browser window.
• int height: The height in pixels of the browser window.

Example:
Find the center of the DynaForm:

getBrowserClient()

getBrowserClient() returns an object with information about the current browser client

Parameters:
None.

Return Value:
An object with the following elements:

• string name: The name of the web browser as reported in navigator.userAgent
• string browser: A predictable browser name that can be used in script tests. It is one of the following values: "opera", "msie", "firefox", "safari"
• string version: The version number of the browser.

Note: If using objects/functions which are browser specific, it is not recommended to use getBrowserClient() to decide what code to execute, because browser names can change, future versions of browsers may implement the object/function, and browsers even miss-report their names to ensure greater compatibility.