Overview

The DynaForm Designer offers two different controls to manage options represented by checkable boxes, which are checkbox and checkgroup controls.

Note: In version 3.0.1.4, the functionality of checkboxes was divided into checkboxes and checkgroups, so be aware of this change if upgrading ProcessMaker.

Checkbox

A checkbox offers a binary on/off choice and appears as a square box with a check mark when activated (marked). Checkboxes are convenient for allowing a user to activate only one option with a single click of the mouse. Its icon in the toolbar of the DynaForm designer is the following:

The default appearance of a checkbox field is the following:

Note: Notice that no options are displayed when working with a checkbox.

When running a case, a "checkbox" control looks similar to:

Managing Checkboxes

After adding a checkbox into the designer, it is possible to customize its functionality and behavior, using the properties panel.

The properties set by default are the following:

  • type Set by default as "checkbox ". This property cannot be modified.
  • id Set by default as checkbox 000000000X where "X" represents the corresponding numbering of the control in the design. This numbering starts in 1. After a variable is related to this control, the ID changes to the name of the variable. Nevertheless, it is possible to set a new ID to work with the control.
  • label Set by default as "checkbox _X" where "X" represents the corresponding numbering of the control in the design. This numbering starts in 1.
  • display mode Set by default as "parent". See this documentation for more information about display modes available for this control.

Checkbox Properties

The properties related to this web control are the following:

Property Description
Type checkbox (readonly)
Variable

Click on the ... option to select the variable from the list of available variables. See this section to learn more of how to relate a variable to a control.
Only variables of the following data type can be selected:

  • boolean

When a variable is not related to this control, the values returned are:

  • 0: false
  • 1: true
Variable Data Type After a variable has been related to the control, this property shows the data type of the variable (readonly).
ID

[Required]

Field and HTML unique identifier.

Label Set the label of the control in this property
Default value Value set by default when the value retrieved is null. When the form is first rendered, the value set is "null". If the field is not required and the user does not mark at any moment any option, the value retrieved will also be "null". Thus, take into account that the data saved will be the default value for this control in these cases.

See this documentation to learn how the default value works in this control.

Hint Used to show help when the checkbox is rendered. It is shown when the pointer of the mouse is hovered over the ? icon.
Required By checking this option, an asterisk is added in the label to indicate that the field is required. It means that an option must be selected mandatorily from the control. When a required field is not filled in with any value, it will not possible to go to the next step.
Display Mode

[Required]

Display mode:

  • parent: inherits the display mode defined in the parent container (form/grid)
  • edit: the field is enabled for edition when it is rendered.
  • view: the field can only be viewed when it is rendered. The content can’t be edited.
  • disabled: the field is displayed as disabled. The field is displayed in gray in order to indicate the disabled mode. The content can't be edited either.
Options For a checkbox that has not been related to any boolean variable, the options of the control can be directly set using this option.

Note: This property is no longer available from version 3.0.1.5

Checkbox Control Example

For this example add a "Checkbox" control by simply dragging it and then dropping it into the Dynaform designer.

After adding the control the Create Variable window will appear. For this example create a variable named "married" and configure the settings as seen in the image below.

When a variable is added the "variable" and "variable data type" properties will change. Also the "Id" property will gain the name of the variable as well, observe the image below.

The "label" property of the control must be changed for it to have a proper name instead of "label_1". For this example the property will be changed to "Married:"

It is not advisable to add a text in the "default value" property because the control does not show text.

The next property is called "hint" which will be used to show help to the user by adding an icon with the text added in the property. For example, the hint can be the following text added can be the following: "Check if married"; and when running a case the hint will appear when hovering the pointer of the mouse over the icon next to the control as seen in the image below.

Next is the "required" property which adds a red asterisk next to the name of the control. If enabled then the checkbox must be selected and if it's not then an error message will appear as observed in the image.

Now the next property which is the "display mode" property will make the following alterations to the control.

Observe that for this example the "options" property already has values, this is because when the variable was created it was type Boolean and therefore its values where added directly from there. For more information about the "option" control read this documentation.

Checkgroup

A checkgroup offers an on/off choice for one or more options in a DynaForm, and appears as one or several square boxes with a check mark when activated (marked). Checkgroups are convenient for allowing a user to activate more than one option with a single click of the mouse. Its icon in the toolbar of the DynaForm designer is the following:

The default appearance of a checkgroup is the following:

When running a case it looks similar to:

Managing Checkgroups

After adding a checkgroup to the design, it is possible to customize its functionality and behavior by configuring its properties.

The properties set by default are the following:

  • type Set by default as "checkgroup". This property can not be modified.
  • id Set by default as checkgroup000000000X where "X" represents the corresponding numbering of the control in the design. This numbering starts in 1. After a variable is related to this control, the ID changes to the name of the variable, nevertheless it is possible to set a new ID to work with the control.

  • label Set by default as "checkgroup_X" where "X" represents the corresponding numbering of the control in the design. This numbering starts in 1.
  • display mode Set by default as "parent". See this documentation for more information of the modes available for this control.
  • DB connection Set by default to "PM Database". Take into account that if no SQL query is defined in the "sql" property, then no execution will be done. Also, when a variable is related to this control which has its own definition of the connection to a database (an external database or the ProcessMaker's workflow database) this property inherits the definition of the variable related in the control.

Checkgroup Properties

All of the options related to the variable assigned to this field, will be displayed. If the group of options must be retrieved from a database, these will not be shown in the designer. The properties related to this control are the following:

Property Description
Type checkgroup (readonly)
Variable

Click on the ... option to select the variable from the list of available variables. See this section to learn more of how to relate a variable to a control.
Only variables of the following data types can be selected:

  • array

Variable Data type After a variable has been related to the control, this property shows the data type of the variable (readonly).
ID

[Required]

Field and HTML unique identifier.

Label Set the label of the control in this property
Default value

Value set by default when the value retrieved is null. To set more than an option in this control use a pipe. For example, to define that "Bolivia", "Argentina" and "Venezuela" should be the countries by default, set “BO|AR|VE” as the default value.

Take a look at this documentation to learn how checkgroups work with default values.

Hint Used to show help when the checkgroup is rendered. It is shown when the pointer of the mouse is hovered over the ? icon.
Required By checking this option, an asterisk is added in the label to indicate that the field is required. It means that an option must be selected mandatorily from the control. When a required field is not filled in with any value, it will not possible to go to the next step.
Display Mode

[Required]

Display mode:

  • parent: inherits the display mode defined in the parent container (form/grid)
  • edit: the field is enabled for edition when it is rendered.
  • view: the field can only be viewed when it is rendered. The content can’t be edited.
  • disabled: the field is displayed as disabled. The field is displayed in gray in order to indicate the disabled mode. The content can't be edited either.
DB Connection For a checkgroup control, if needing to store a value retrieved from a database, select from the dropdown of this property the database connection that will be used (the connection must be already created in the process, see this section to learn more about it).
SQL Insert in this property, the SQL query to populate the option of the control from database.

Take a look at this documentation to learn how this options work in the designer

Options

Define in this property the options that will be used to define the value used in the field.

For a checkgroup control take into account that if the options are defined first in the designer and then a variable is related to the control, these options are replaced by the options of the variable (the options are deleted even if the variable has no options pre-defined).

After a variable has been related to the control, it is possible to add manually more variables to the control by defining them in this property (after the variable has been related) even if the variable has a SQL query defined or variables inside its configuration.

Take a look at this documentation to learn how this options work in the designer

Checkgroup Control Example

For this example add a "Checkgroup" control by dragging the control and dropping it into the Dynaform Designer.

After adding the control a window will immediately pop up. This is the Create Variable window which allows the user to create variables or select an already existent variable. For this case created a variable named "new item". Use the "Settings" section to add more configuration to the variable. Finish with the variable window by clicking on the "Save" button.

Now that the variable has been created, display the properties of the control by clicking on any space within the control. The properties will be shown on the left hand panel.

Now the "label" property must be changed to a proper name instead of having "checkgroup_1" it can be changed to (for this example) "Item to buy".

For this control is not advisable to change the "default value" property because it will not have an effect in this type of control as seen in the image below.

The "hint" property can be used to show help to the user. For this example the user will choose between a certain amount of items to buy , therefore in the hint box the following text can be added: "Check the item(s) for the purchase". When running a case hover the pointer of the mouse over the icon next to the control and the hint will be displayed as shown in the image below.

Next is the "required" property, when/if checked then the field will automatically show a red asterisk which means that the checkbox must be selected otherwise an error message will appear as observed in the image below.

Next is the "display mode" property which allows the user to choose the mode the control will have. If the mouse is hovered over the question mark icon the explanation of each mode will be displayed. As seen in the image below, each mode will have the following effect on the control.

The following properties are the "DB Connection" which is used to select between the list of database connections defined in the process objects, and then the "sql" property is used to query values from databases. For this a different example will be used. Let's pretend a country needs to be chosen therefore a query will be used to call the UID and name of a table named ISO_COUNTRY.

SELECT IC_UID, IC_NAME FROM ISO_COUNTRY

The result of using this query in the control would be the following

Note: In the image above the amount of countries is not completely shown because it would be extremely long to show in one image but when testing the example the complete list will be shown.

Notice that the "options" property already has values, this is because when creating variables one can define the values. For more information about the "option" property this read this documentation

JavaScript in Checkboxes and Checkgroups

To learn how to manipulate DynaForm controls using JavaScript, see JavaScript in DynaForms.

Checkboxes/Checkgroups in ProcessMaker 3 have the following field components:

  • Label: The text displayed above or to the left of the field to identify it to the user.
  • Text: The text (label) for the marked option, which is configured in the list of options. This text can be configured in checkboxes, but by default it is "true" if marked and "false" if unmarked. For checkgroups (and checkboxes before version 3.0.1.4), the text is a JSON string containing an array of the labels of the marked options. For example, a checkgroup to select countries might have a text of: '["United States", "Mexico", "Brazil"]'
  • Value: The stored value (key) for the marked option. For checkboxes, this is a value of "1" if marked and "0" if unmarked. For checkgroups (and checkboxes before version 3.0.1.4), this is an array of the values (keys) for the marked options. For example, a checkgroup to select countries might have a value of: ["US", "MX", "BR"]

JavaScript Methods

Some of the JavaScript methods to manipulate checkboxes and checkgroups include:

Method Description
jQuery("#fieldID").getControl()

Use this function to obtain the control's input field, rather than its DIV which is obtained with $("#id")

For checkgroups (and checkboxes before version 3.0.1.4), getControl() returns an array of the options, so the third checkbox in the checkgroup can be accessed as: $("#id").getControl()[2]
jQuery("#fieldID").disableValidation() Disable the validation of the field, so it doesn't check whether the field is required when the form is submitted.
jQuery("#fieldID").enableValidation() Enable validation of the field, so it will check whether the field is required when the form is submitted.
jQuery("#fieldID").getValue() Returns the value (key).
  • For checkboxes, it returns "1" if marked or "0" if unmarked.
  • For checkgroups (and checkboxes before version 3.0.14), it returns an array of the values of the marked options.
jQuery("#fieldID").getText() Returns the text (label). For checkboxes, it returns the label, which by default is "true" if marked and "false" if unmarked. For checkgroups (and checkboxes before version 3.0.14), it returns a JSON string containing an array of the labels of the marked options.
jQuery("#fieldID").getLabel() Returns the field's label, which is the text displayed above or to the left of the field to identify it.
jQuery("#fieldID").setValue(["value1", "value2"]) Sets the value.
  • For a checkboxes, set to "1" to mark it or "0" to unmark it.
  • For checkgroups (and checkboxes before version 3.0.14), set it to an array of the values of the options to mark. For example, a checkgroup to select countries:
    $("#countries").setValue(["US", "MX", "BR"])
jQuery("#fieldID").setText(["label1", "label2"]) Sets when options are marked by using text label(s). For a checkbox, set it to the text label for the marked or unmarked option. Alternatively, to mark a checkbox, set its text to "true", and to unmark it, set its text to "false". For checkgroups (and checkboxes before version 3.0.14), set it to an array of the labels of the marked options.
For example, a checkgroup to select countries:
$("#countries").setText(["United States", "Mexico", "Brazil"])
jQuery("#fieldID").setLabel("newLabel") Change the field's label, which is the text displayed above or to the left of the field to identify it.
jQuery("#fieldID").setOnchange(
function(newVal, oldVal){...})
Define a change event handler, which is a custom function that executes after the value of the field changes. The function may contain the following parameters:

  • newVal: The new value that has just been set in the field.
  • oldVal: The old value which was changed.

To see code examples for these methods, see JavaScript Functions and Methods.

Values in checkboxes

Getting checkbox values:
The value returned by the getValue() method depends upon the version of ProcessMaker. In version 3.1 and later, the value of a checkbox is stored as a string. If the checkbox is marked, then $("#checkbox-id").getValue() returns "1". If unmarked, it returns "0".

In contrast, in version 3.0.1.8 and earlier, $("#checkbox-id").getValue() returned '["1"]' if marked and '["0"]' if unmarked. Take into account this change if upgrading ProcessMaker.

Setting checkbox values:
A checkbox can be marked with either $("#checkbox-id").setValue(["1"]) or $("#checkbox-id").setValue("1"). It can be unmarked with either $("#checkbox-id").setValue(["0"]) or $("#checkbox-id").setValue("0").

Example:

The following JavaScript code marks a checkbox with the ID "hasContract" if a value of "catering_contract" is selected in a dropdown box with the ID "chooseService". If any other value is selected in the dropdown box, then the value of the "hasContract" checkbox is automatically changed to its opposite value. If marked, it is unmarked, or vice-versa.

$("#chooseService").setOnchange( function(newVal, oldVal) {
   if (newVal == "catering_contract") {
      $("#hasContract").setValue("1");
   }
   else {
      //check for versions 3.0.1.8- and versions 3.1+
      if  ($("#hasContract").getValue() == '["1"]' || $("#hasContract").getValue() == "1") {
          $("#hasContract").setValue("0");
       }
       else {
           $("#hasContract").setValue("1");
       }
   }
});

Checkboxes in grids

Getting checkbox values in grids:
In version 3.1 and later, the grid.getValue(row, column) method for a checkbox returns a string. If the checkbox in the grid is marked, then it returns "1". If unmarked, then it returns "0".

In contrast, in version 3.0.1.8 and earlier, the grid.getValue(row, column) method for a checkbox returns ["1"] if marked and ["0"] if unmarked. If upgrading ProcessMaker, then the code should be altered to take into account this change. Also remember that row and column numbers in grids start counting from the number 1.

For example, to check whether a checkbox in the second row in the third column of a grid with the ID "clientList" is checked in version 3.1 and later:

if ($("#clientList").getValue(2, 3) == "1") {
   alert("It's checked");
}

Similarly, the value of a checkbox will be "1" or "0" in the array returned by grid.getValue(). Remember when accessing the array, to start counting the rows and columns from the number 0. For example, to check whether a checkbox in the second row in the third column of a grid with the ID "clientList" is checked:

if ($("#clientList").getValue()[1][2] == "1") {
   alert("It's checked");
}

Setting checkbox values in grids:
A checkbox in a grid can be marked with grid.setValue("1", row, column) or grid.setValue(["1"], row, column). To unmark a checkbox, use a value of ["0"] or "0". For example, to unmark a checkbox in the third column in the second row of a grid with the ID "clientList":

$("#clientList").setValue("0", 2, 3);
or
$("#clientList").setValue(["0"], 2, 3);

Likewise, the value of a checkbox can be ["1"], "1", ["0"] or "0" when adding a new row to a grid with the grid.addRow() method. For example, to add a new row to a grid with the ID "clientList" which has two textboxes and a checkbox in each row:

$("#clientList").addRow( [{value: "Sally"}, {value: "Rogers"}, {value: "1"}] );
or
$("#clientList").addRow( [{value: "Sally"}, {value: "Rogers"}, {value: ["1"]}] );

setOnchange() with checkboxes

The control.setOnchange() method in version 3.0.1.8 reports the value of a checkbox as '["0"]' (unmarked) or '["1"]' (marked). In version 3.1 and later, the control.setOnchange() method reports the value of a checkbox as '"0"' (unmarked) or '"1"' (marked).

Note: The control.setOnchange() does not work correctly in version 3.0.1.7, so it is recommended to upgrade ProcessMaker.

Example
In the following JavaScript example, if a checkbox with the ID "hasContract" is marked, a file control with the ID "contractFile" is shown. If unmarked, then the "contractFile" control is hidden.

$("#hasContract").setOnchange( function(newVal, oldVal) {
   //check for version 3.1+ or version 3.0.1.8-
   if (newVal == '"1"' || newVal == '["1"]') {
      $("#contractFile").show();
   }
   else {
      $("#contractFile").hide();
   }
} );

Displaying options in a horizontal list

The options in a checkgroup are displayed as a horizontal list when displayed in Preview Mode or when running a case. For checkgroups which have a large number of options, this can take up a large amount of space and force the user to scroll through a long form. To change from a vertical list of options to a horizontal list, add the "radio-inline" class to the DIVs around each checkbox.

For example, the following checkgroup with the ID "selectCountries" is used to select from a list of countries:

This checkgroup takes up less space with a horizontal list of options:

The following JavaScript code can be added to a DynaForm to change this checkgroup with the ID "selectCountries" to display a horizontal list of options:

$("#selectCountries").find("div.checkbox").addClass("radio-inline");

Remove shadow box around checkboxes

To remove the light blue shadow box around checkboxes and checkgroups, add the following JavaScript to the DynaForm:

$("div.pmdynaform-control-checkbox-list").css("box-shadow","none");

Accessing with PHP

When a checkbox in a DynaForm is submitted, its associated variable has a value of array(1) if marked or array(0) if unmarked. For example, the following trigger code checks whether a checkbox associated with the "hasContract" variable is marked to set the minimum amount in the @#minimumInvoice variable.

//if checkbox is marked:
if (isset(@=hasContract) and @=hasContract == array(1)) {
   @#minimumInvoice = 1000.00;
}
else { //if unmarked:
   @#minimumInvoice = 200.00;
}

By default, the label variable for checkboxes is set to "true" if marked or "false" if unmarked, however, this value can be customized in the options property of the checkbox. For example, the above trigger could be written as:

//if checkbox is marked:
if (isset(@@hasContract_label) and @@hasContract_label == 'true') {
   @#minimumInvoice = 1000.00;
}
else { //if unmarked:
   @#minimumInvoice = 200.00;
}

To set the value of a checkbox in a trigger, set its associated variable to a value of array(1) or true to mark it or a value of array(0) or false to unmark it. The following trigger marks a checkbox associated with the hasContract variable in a trigger fired before the DynaForm which holds the checkbox:

@=hasContract = array(1);
or
@=hasContract = true;