Accessing Checkgroups with JavaScript

From pmusers
Jump to: navigation, search

This page explains how to manipulate a checkgroup using JavaScript.

Tested in: ProcessMaker 3.1.3 Community in Firefox 51

Getting a checkgroup's list of options

A checkgroup consists of a set of checkboxes. The list of options (i.e., checkboxes) in a checkgroup can be obtained in the model information with the following JavaScript code:


For example, the following checkgroup has the ID "selectServices":



The following code gets the list of options in the "selectServices" checkgroup:

var aOpts = $("#selectServices").getInfo().options

Now the variable aOpts has the following content:

    label:    "Accounting & Auditing",
    value:    "accounting", 
    selected: false
    label:    "Cleaning Service",
    value:    "cleaning",  
    selected: false
    label:    "Maintenance & grounds",  
    value:    "maintenance",  
    selected: false

The selected property is set to true if the checkbox is marked by default when the Dynaform was first loaded.

Use the .length property of the options array to get the number of checkboxes in a checkgroup:

var numberOptions = $("#selectServices").getInfo().options.length

Getting currently selected options

If needing to get the current state of the checkboxes, then use control.getValue(), not the .selected property. The control.getValue() method returns an array of the values of the marked checkboxes in the checkgroup.

For example:

var aValues = $("#selectServices").getValue();

Now the aValues variable contains the array ["accounting", "maintenance"], since the first and third checkboxes in the checkgroup are marked.

Likewise, use the control.getText() method to get a JSON string holding an array of the marked checkboxes' labels. JSON.parse() can be used to convert the string into an array of the selected labels.

For example:

var aLabels = JSON.parse($("#selectServices").getText());

Now the aLabels variable contains the array: ["Accounting & Auditing", "Maintenance & grounds"]

For example, the following JavaScript code uses the control.setOnchange() method to set an event handler to check whether the "cleaning" checkbox is marked when the checkgroup changes. $.inArray() is used to search for "cleaning" in the array of selected values of the checkgroup. If it is found, then the textarea "areasToClean" is shown; otherwise it is hidden.

function hideShowAreasToClean(newServices, oldServices) {
   //if "cleaning" is selected, then show "areasToClean" textarea:
   if ($.inArray("cleaning", newServices) != -1) {
   else {
$("#selectServices")setOnchange(hideShowAreasToClean);      //when checkgroup changes
hideShowAreasToClean($("#selectServices").getValue(), []);  //when DynaForm loads

Setting selected options

The control.setValue() method can be used to mark checkboxes in a checkgroup. control.setValue() takes an array of the checkbox values to mark in the checkgroup. Note that the values have to be listed in the array in the same order as they appear in the checkgroup.

For example, the following code marks the first and third options in the "selectServices" checkgroup:

$("#selectServices").setValue(["accounting", "maintenance"]);

If the order is reversed, and the third option is listed first in the array and the first option is listed last, then the checkboxes will not be marked correctly. This code will NOT will not mark the checkboxes, because the options are listed out of order:

$("#selectServices").setValue(["maintenance", "accounting"]); //doesn't work!

If needing set just one checkbox, but leave the other checkboxes unchanged in the checkgroup, then use $.inArray() to first check whether the checkbox is not already marked. If unmarked, then mark it using Array.push() to add the value of the checkbox to the array. Then, loop through the list of getInfo().options to recreate the array in the proper order and pass that array to setValue().

For example, the following JavaScript code marks the "accounting" option in the "selectServices" checkgroup, if it is not already marked:

var aVals = $("#selectServices").getValue();
if ($.inArray("accounting", aVals) != -1) {
  var aOrderedVals = [];
  var aOpts = $("#selectServices").getInfo.options;
  for (i in aOpts) {
     if ($.inArray(aOpts[i].value, aVals)) {

Similarly, the following code uses setValue() to unmark (unselect) the "accounting" checkbox in the "selectServices" checkgroup if the checkbox is not already unmarked. It uses the Array.splice() method to remove the value from the array of selected values.

var aVals = $("#selectServices").getValue();
var pos = $.inArray("accounting", aVals);
if (pos != -1) {
  aVals.splice(pos, 1);

HTML structure of checkgroups

Checkgroups have the following HTML structure:

<div id="selectServices" class="pmdynaform-field-checkgroup  form-group col-sm-12 col-md-12 col-lg-12  
    pmdynaform-edit-checkgroup pmdynaform-field">
  <label for="form[selectServices]" class="col-sm-2 col-md-2 col-lg-2 control-label pmdynaform-label">
    <span class="textlabel">Select Services</span>
  <div class="col-sm-10 col-md-10 col-lg-10 pmdynaform-field-control">
    <div class="pmdynaform-control-checkbox-list form-control" style="height: auto;">
      <div class="pmdynaform-checkbox-items">
        <div class="checkbox">
            <input id="form[selectServices][accounting]" name="form[selectServices][]" 
                class="pmdynaform-control-checkgroup" value="accounting" type="checkbox">
            <span>Lawn Service</span>
        <div class="checkbox">
            <input id="form[selectServices][cleaning]" name="form[selectServices][]" 
                class="pmdynaform-control-checkgroup" value="cleaning" type="checkbox">
            <span>Cleaning Service</span>
    <input id="form[selectServices_label]" name="form[selectServices_label]" 
        value="[&quot;Accounting&quot;,&quot;,&quot;Maintenance&quot;]" type="hidden">

Each checkbox in the checkgroup is placed inside a <div>, whose class is named "checkbox".

The following JavaScript code hides the first checkbox and shows the third checkbox in the "selectServices" checkgroup:


In this example, .find() returns an array of the divs holding checkboxes and .eq() is used to select one of them.

Note that arrays start counting from the number 0, so the first checkbox is element 0 in the array and the third checkbox is element 2.

The checkboxes in checkgroups can also be found by searching for their value. The following code has the same effect as the previous code example:


Note that hiding a checkbox does not prevent its value from being saved when the DynaForm is submitted.

To disable a checkbox in a checkgroup, set its disabled property to true and set the color of the <span> holding the checkbox's label to grey.

The following code disables the "accounting" checkbox and enables the "maintenance" checkbox:

$("#selectServices").find("input[value=accounting]").prop("disabled", true)
$("#selectServices").find("input[value=accounting]").siblings("span").css("color", "grey")
$("#selectServices").find("input[value=maintenance]").prop("disabled", false)
$("#selectServices").find("input[value=accounting]").siblings("span").css("color", "") //return to default color

Accessing checkboxes in a checkgroup

The control.getControl() method will return an array of all the checkboxes in a checkgroup. Use .eq() to access a particular checkbox in that array and remember that counting in arrays starts from 0.

For example, the following code sets the label of the second checkbox in the "selectServices" checkgroup. It uses .siblings() to select the <span> element next to the checkbox which holds the checkbox's label.

$("#selectServices").getControl().eq(1).siblings("span").html('Cleaning Service')

It is also possible to do the same thing by searching for the checkbox's value:

$("#selectServices").find("input[value=cleaning]").siblings("span").html('Cleaning Service')

Using checkgroup.setOnchange()

The control.setOnchange() method for checkgroups has its own idiosyncrasies. The newValue in the change event handler function will be an array of the values of the currently selected options. However, the oldValue will be a JSON string holding an array the values of the previously selected options. In order to use that array, it needs to first be decoded with JSON.parse().

For example, a checkgroup with the ID "selectCountries" needs to limit the number of selected options to 3 or less and prevent the "United States" from being selected. If the user has selected more than 3 options or selected the value "US", then the following JavaScript returns the checkgroup to its the previous value. Notice how oldVal is decoded with JSON.parse() before being used.

$("#selectCountries").setOnchange(function(newVal, oldVal) {
  //three selected options is the maximum allowed and the US isn't allowed
  if (newVal.length > 3 || newVal.indexOf('US') != -1) { 
    previousVals = JSON.parse(oldVal);