checkbox toggleall
Moodle 3.8
The \core\output\checkbox_toggleall output component provides an easy way of rendering a set of checkboxes that can be toggled simultaneously by one or more master controls. It is a renderable that ties up with the core/checkbox-toggleall AMD module which provides the functionality of toggling the states of the checkboxes on the frontend.
This element provides a method for developers to implement a consistent method of selecting and deselecting multiple items in a list.
Constructor
\core\output\checkbox_toggleall's constructor accepts four parameters:
- $togglegroup (string, required)
- The toggle group parameter defines the name of the group that a checkbox and a master control belong to. A checkbox and a master control can belong to one or more toggle groups.
- $ismaster (bool, required)
- True when we're rendering for a master control. False, otherwise.
- $options (array, optional)
- These are options for the element. Accepted values are:
- id (string) - The element ID.
- name (string) - The element name.
- classes (string) - The CSS classes that you want to add for your checkbox or toggle controls.
- Note: For button type master toggle controls, this could be any Bootstrap 4 "btn" classes that you might want to add. Defaults to " btn-secondary ".
- value (string|int) - The element's value
- checked (bool) - Whether to render this initially as checked.
- label (string) - The label for the element.
- labelclasses (string - CSS classes that you want to add for your label.
- selectall (string, master only) - The language string that will be used to indicate that clicking on the master will select all of the slave checkboxes. Defaults to "Select all".
- deselectall (string, master only) - The language string that will be used to indicate that clicking on the master will select all of the slave checkboxes. Defaults to "Deselect all".
- These are options for the element. Accepted values are:
- $isbutton (bool, optional, master only) Whether to render the master control as a button. Defaults to false.
Master controls
Master controls are elements that toggle the states of the checkboxes. There are currently two types of master controls -- a checkbox-type, and a button-type.
Checkbox-type master control
To define a checkbox-type master control, make sure to set the $ismaster parameter to true, and the $isbutton parameter to false.
Sample usage:
$options = [
'id' => 'check-items',
'name' => 'check-items',
'value' => 1,
];
$mastercheckbox = new \core\output\checkbox_toggleall('items', true, $options);
Button-type master control
To define a button-type master control, set the both the $ismaster and the $isbutton parameters to true.
Sample usage:
$options = [
'id' => 'check-items',
'name' => 'check-items',
'value' => 1,
];
$masterbutton = new \core\output\checkbox_toggleall('items', true, $options, true);
// Then you can export for template.
$masterdata = $masterbutton->export_for_template($OUTPUT);
Slave checkboxes
These checkboxes are the ones that are being controlled by the master controls.
Sample usage:
$options = [
'id' => 'item1',
'name' => 'item1',
'value' => 1,
];
$itemcheckbox = new \core\output\checkbox_toggleall('items', false, $options);
// Or instead of exporting for template, you can render it directly as HTML.
echo $OUTPUT->render($itemcheckbox);
Action elements
Sometimes it's preferable for elements, which perform actions on list items, to be enabled only when there are checked items.
For example, you have a list of users and you have a single-select element that you only want to be enabled when there are at least a single user selected. If the checkboxes and the master controls are rendered using \core\output\checkbox_toggleall, you can simply add the following data attributes to the single-select.
- data-action="toggle"
- data-togglegroup="[TheToggleGroupName]"
- data-toggle="action"
With these data attributes, when at least one user gets selected, the single select will be enabled. When nothing is selected, it will get disabled.
Note: Optionally, you might want to also set the "disabled" attribute on your action element in case there are no items initially selected on page load.
Multiple toggle groups
There might be a scenario when you would want checkboxes to be controlled by multiple master controls. You can have a checkbox_toggleall element to belong to multiple toggle groups by listing the toggle group names together, separated by space, and passing to the "$togglegroup" parameter.
Note that it is necessary for the more encompassing toggle group to be written first, before the more specific ones. If it helps, you can think of having checkbox_toggleall elements belonging to multiple toggle groups as a tree structure.
Example
For example, in the responses page of a Choice activity which has the following choices: Option 1, Option 2, and Option 3. It would be handy to be able to choose all of the users based on each option (e.g. a master control that selects all users under Option 1, another master control that toggles the selects the users under Option 2, etc.).
It would also be handy to have another master control that selects all users under Options 1 through 3 at the same time.
For this scenario, you will have the following toggle groups:
- For all users (let's call this toggle group as "allusers")
- For all users under Option 1 (let's call this as "option1users")
- For all users under Option 2 (let's call this as "option2users")
- For all users under Option 3 (let's call this as "option3users")
So the structure would be like:
- allusers
- option1users
- option2users
- option3users
Then the following toggle group names would be:
- For the master control that selects all of the users: "allusers"
- For all master control(s) and checkboxes under Option 1: "allusers option1users"
- For all master control(s) and checkboxes under Option 2: "allusers option2users"
- For all master control(s) and checkboxes under Option 3: "allusers option3users"