3.0 - Editing the Dynaform's JSON code

Overview

Dynaforms are stored in JSON (JavaScript Object Notation), which is a text format understood by JavaScript. It is possible to edit the JSON code of a Dynaform by first exporting the Dynaform and then editing it in a plain text editor. When done editing, the JSON file can be reimported into ProcessMaker.

It is generally recommended to create Dynaforms using the graphical Dynaform Editor inside ProcessMaker, but it can be useful to edit a Dynaform's JSON code after it has been created. Editing the JSON code allows:

• Insertion of variables into the Dynaform.
• Editing of specialized properties that are not available in the graphical interface.
• Editing with a text editor, which is faster than using the graphical interface when making changes to many different controls.

Exporting and Editing Dynaforms

To edit a Dynaform, first export it. Open the Dynaform to edit it, and then click on the button in the toolbar to export the Dynaform.

By default, the JSON file will be saved in the file dynaform-title.json. Depending on the configuration of your web browser, it may either download the file automatically to the default download directory or allow the filename and file location to be changed by the user.

Then, open the Dynaform's JSON file with a plain text editor. It is recommended to use a code editor, such as Notepad++, Eclipse, Bluefish, or Sublime that has code highlighting to avoid making mistakes. Code highlighting helps to catch errors, such as forgetting to end strings with a " (double quotation mark) or forgetting to include closing ] (brackets) and } (curly braces).

When done editing the JSON code, open a Dynaform for editing and click on the button in the toolbar to import the edited JSON file. Importing will overwrite the contents of the Dynaform (although it will keep the Dynaform's existing title). Any variables used in the Dynaform that don't already exist will be automatically created when the Dynaform is imported.

Understanding JSON format

Before editing the JSON code of a Dynaform, it may be useful to understand the format.

In JSON, strings are enclosed in double quotation marks:
"This is a string"
To include double quotation marks inside a string, escape them by preceding them with \ (a backslash):
"Say \"hello\" to your client"
Tabs are represented in strings as \t and new lines are represented as \n:
"New Client List:\n\tAcme, Inc.\n\tWidgets Corp.\n\tDawkins & Baileys"
Integers are numbers without a decimal point and floating-point numbers are numbers with a decimal point, which is represented with a . (period). Do NOT use the European practice of separating the decimal numbers with , (a comma).
A boolean is a variable that is either set to true or false. In addition, JSON supports the use of null (no value) and undefined.
An array is a list of values separated by , (commas). Arrays are enclosed in [ ] (square brackets). The values in an array can be any data type, such as string, integer, floating-point number, null, and even include arrays and objects embedded inside the array:

Note that spacing outside of strings is ignored in JSON, so the object above can also be represented as:

Format of Dynaform Files

The JSON code in a Dynaform file is organized in a topmost object that contains the name, description and items properties. All the information about the Dynaform is enclosed in items. The most important property is another items property, which holds an array of objects with information about the controls in the Dynaform. The properties for each type of control are listed below. The other important property is variables, which is an array of objects containing information about the variables assigned to the controls in the Dynaform.

Here is the basic structure of a Dynaform file:

Textboxes

For the JSON format of textboxes, see the example listed above.

Textareas

The JSON format of textareas is similar to textboxes, but it has an additional rows property and does not have the formula, maxLength, operation and textTransform properties.

Example:

Dropdowns

The JSON format of dropdown boxes is similar to textboxes, but it does not have the formula, maxLength, operation and textTransform properties. When using a query in the sql property, make sure that it returns two fields to populate the keys and labels in the list of options.

Example:

Checkbox (version 3.0.1.4+)

The JSON format of checkboxes changed in version 3.0.1.4 and later, so they only have one checkable box and are based on boolean variables.

Example:

Checkgroup (version 3.0.1.4+)

Checkgroups were added in version 3.0.1.4. They are based on array variables and allow for multiple checkable boxes. Note that more than one option can be marked by default by separating the values in the defaultValue property with | (vertical bars), such as "US|MX|CA". When using a query in the sql property, make sure that it returns two fields to populate the keys and labels in the list of options.

Example:

Radio

The JSON format of radio buttons is the same as dropdown boxes.

Example:

Datetime

Datetimes have a number of special properties that control the formatting and the appearance of the date picker.

Example:

Suggest

Suggest boxes are similar to textboxes, but they lack the formula, maxLength, operation, textTransform validate and validateMessage properties.

Example:

Hidden

The JSON format of hidden fields is simpler than other types of controls since there are no visual elements to configure.

Example:

Title

Example:

Subtitle

The JSON format of subtitles is the same as titles.

Example:

Label

The JSON format of labels is the same as titles.

Example:

Link

Example:

Image

The JSON format of images have a number of unique properties related to the source, shape, and the text associated with images.

Example:

File

Example:

Submit

For submit controls, the label is the text that appears in the button.

Example:

Button

The JSON format of generic buttons is the same as submit buttons.

Example:

Grid

The JSON format of grids includes not only the definition of the grid, but also an array of all the fields inside the grid.

Example:

Panel

Example:

Subform

The JSON code for a subform is the same as the code for a normal form, except that it has the colSpan property to set the width of the subform.

Example:

Inserting Case and System Variables

Case and system variables can be inserted into the JSON code to generate dynamic content in the Dynaform.

To insert a variable into the JSON code, place @@variable inside double quotation marks in the code. The value of the variable will be inserted into the JSON code when the Dynaform is generated.

Note: Variables can only be inserted inside strings that are enclosed in double quotation marks.

Example:

In a contracting process, a trigger sets the type of organization in the @@organizationType variable, depending on the quantity of the @%amount:

if (@%amount < 500) {
  @@organizationType = "NGO";
}
elseif (@%amount >= 500 and @%amount <= 10000) {
  @@organizationType = "Credit union";
}
elseif (@%amount > 10000) {
  @@organizationType = "International bank";
}

This trigger is set to execute before a Dynaform containing a textbox with the ID "organizationName".

In the JSON code of this Dynaform, the "organizationName" field has the following definition:

{
  "type":      "text",
  "variable":  "organizationName",
  "var_uid":   "158861394565762e1d755c5078115321",
  "dataType":  "string",
  "id":        "organizationName",
  "name":      "organizationName",
  "label":     "Organization name",

To insert the type of organization into the label of the "organizationName" field, change the JSON code to:

{
  "type":      "text",
  "variable":  "organizationName",
  "var_uid":   "158861394565762e1d755c5078115321",
  "dataType":  "string",
  "id":        "organizationName",
  "name":      "organizationName",
  "label":     "@@organizationType name",

Then, open the Dynaform for editing and import the modified JSON file. When a case is run, it will change the label of the "organizationName" field, depending on the quantity of the @%amount variable. For example, if the @%amount is set to 1235 when running a case, then it will display "Credit union name":