I see that there is no documentation on accessing checkgroups with PHP in the wiki. Here you go.
Accessing Checkgroups with PHP
When a checkgroup is submitted, an array variable is created which contains the keys of the selected options in the checkbox and another variable named @@
variable_label is created which is a JSON string holding an array of the labels of the selected options.
For example, the following checkgroup is associated with the "selectedSubjects" variable:
checkgroupProperties.png (20.54 KiB) Viewed 6851 times
This checkgroup has the following list of options:
OptionsInCheckgroup.png (9.84 KiB) Viewed 6851 times
If the user selects the following options when running a case:
SelectedOptionsInCheckgroup.png (6.79 KiB) Viewed 6851 times
Then, the following two case variables will be added to the case when the DynaForm holding the checkgroup is submitted:
Code: Select all@=selectSubjects = array('HIS-101', 'FRE-302', 'LIT-304');
@@selectSubjects_label = '["History 101","French 302","Literature 304"]';
The checkgroup's array variable needs to be accessed as @=selectSubjects in the trigger code. If it is accessed as @@selectSubjects, then it will be converted into a string, which will cause problems if trying to use it as an array.
An individual item in the array can be accessed as @=selectSubjects[
index], where the index starts counting from the number
0. The
count() function can used to get the number of selected items in the checkgroup. If the user might not have submitted the DynaForm or skipped it by using the
Steps menu, then it is a good idea to use
isset() to first check that the checkgroup's variable was set. Also check that the number of selected items is greater than the index number accessing the array.
For example, the following trigger code gets the key of the first selected option in the "selectSubjects" checkgroup:
Code: Select allif (isset(@=selectSubjects) and count(@=selectSubjects) > 0) {
@@firstSelectedKey = @=selectSubjects[0];
}
A
for or
foreach loop can be used to access all the selected options in a checkgroup.
For example, the following code creates a new case in the "Enroll Student" process for each selected item in the "selectSubjects" checkgroup. The code first looks up the unique IDs of the process and its first task named "Check Eligibility," and then uses the
Derivation::getAllUsersFromAnyTask() to get an array of the assigned users to the "Check Eligibility" task. Then, it loops through the selected options in "selectSubjects" checkgroup and uses the
rand() function to randomly select a user to assign to the new case.
Code: Select all$processId = PMFGetProcessUidByName('Enroll Student');
$firstTaskId = PMFGetUidFromText('Check Eligibility', 'TAS_TITLE', $processId, @@SYS_LANG)[0];
$d = new Derivation();
$aUsers = $d->getAllUsersFromAnyTask($firstTaskId);
if (count($aUsers) == 0) {
throw new Exception("No users assigned to task 'Check Eligibility'.");
}
foreach (@=selectSubjects as $subjectKey) {
$random = rand(0, count($aUsers) - 1);
$assignedUserId = $aUsers[$random];
$aVars = array('subjectKey' => $subjectKey);
$newCaseId = PMFNewCase($processId, $assignedUserId, $firstTaskId, $aVars);
if (empty($newCaseId)) {
throw new Exception("Unable to create new case in 'Enroll Student' process.");
}
}
To access the labels of the selected options in the checkgroup, the
decode_json() function can to be used to convert the @@selectSubjects_label variable into an array.
For example, the following trigger code checks whether the user selected an option with the label "History 101" or "Literature 304" in the "selectSubjects" checkgroup. If so, then the key of the selected option is added to an array variable named "languageRequirements".
Code: Select all@=languageRequirements = array();
//check if the DynaForm was submitted:
if (isset(@@selectSubjects_label) and !empty(@@selectSubjects_label)) {
$aLabels = json_decode(@@selectSubjects_label);
for ($i = 0; $i < count($aLabels; $i++) {
$label = $aLabels[$i];
$key = @=selectSubjects[$i];
if ($label == 'History 101' or $label == 'Literature 304') {
@=languageRequirements[] = $key;
}
}
}
To set the selected options in a checkgroup, add the keys of the options to the array variable associated with the checkgroup. Make sure that the trigger is set to fire before the DynaForm which contains the checkgroup.
For example, the following trigger checks if the student is a humanities major, before marking the first and third the options in the "selectSubjects" checkgroup, which have the keys 'HIS-101' and 'LIT-304':
Code: Select allif (@@major == 'Humanities') {
@=selectSubjects = array('HIS-101', 'FRE-304');
}
Before adding an option to the list of selected options a checkgroup, first use the
in_array() function to check whether the option has already been added.
The following code adds the 'FRE-302' option to the list of selected options in the "selectSubjects" checkgroup:
Code: Select all//if not set, then create the checkgroup's variable:
if (!isset(@=selectedSubjects)) {
@=selectSubjects = array();
}
//check if option not already in the array, before adding it:
if (!in_array('FRE-302', @=selectSubjects)) {
@=selectSubjects[] = 'FRE-302';
}
The
unset() function can be used to remove an option from the list of selected options in a checkgroup. Use the
array_search() to first find the index of the selected option.
For example, the following trigger code unselects the 'FRE-302' option in the "selectSubjects" checkgroup:
Code: Select allif (isset(@=selectSubjects)) {
$index = array_search('FRE-302', @=selectSubjects);
if ($index !== false) {
unset(@=selectSubjects[$index]);
}
}