The progress bar shows a calculated progress value based on selected options in a form. In this example, it is applied to a checklist, but it can also be used for other use cases.
Adding a progress bar
This example shows one possible implementation of a progress bar for a checklist.
For this, we need to set up the following components:
- Provide the JavaScript logic in MediaWiki:Common.js
- Define matching checkbox field and option syntax
- Create an event listener in the form properties
Provide the logic in MediaWiki:Common.js
Add the following JavaScript function to MediaWiki:Common.js:
/*Extension:Forms - Add a progress bar for checkbox items */
function CalcProgress( data ) {
var dfd = $.Deferred();
var checked = 0;
var ItemCheckboxes = this.$element.find( 'input[value^=check]' );
var total = ItemCheckboxes.length;
if ( total < 1 ) {
dfd.resolve( data );
return dfd.promise();
}
var items = this.getItems();
for( var name in data ) {
if ( !name.startsWith( 'checkbox_multi-' ) ) {
continue;
}
var checkedCheckboxes = data[name];
for ( var i = 0; i < checkedCheckboxes.length; i++ ) {
checked++;
}
}
data.progress = ( 100 * checked ) / total;
dfd.resolve( data );
return dfd.promise();
}
On line 5, you define the prefix for each checkbox that should be included in the progress count:
input[value^=check]
This means that the "data" value for your checkboxes needs to start with "check". This corresponds to the "data" value defined in each checkbox option:
On line 14, you define the included fields to only those that have the prefix of "checkbox_multi" in their name.
if ( !name.startsWith( 'checkbox_multi-' ) ) {
Based on this implementation example, a checkbox option is included in the progress calculation only if the "field" name starts with "checkbox_multi-" and the option's "data" value starts with "check."
If you use different prefixes for your field names or option values, you need to update the JavaScript code accordingly.
Apply the syntax to the checklist items
Here is a checkbox_multiselect field that has the correct name-prefix and the correct data-prefix. This field is therefore included in the count and all three options of the field count towards the progress:
{
"name": "checkbox_multi-workplace_setup",
"label": "Workplace setup",
...
"options": [
{
"data": "check-equipment",
"label": "Provide equipment (laptop, phone)"
},
{
"data": "check-access",
"label": "Grant access to required systems"
},
{
"data": "check-intro",
"label": "Meet the team"
}
],
"type": "checkbox_multiselect"
}
Create an event listener in the form properties
To connect your form to the JavaScript function, you need to create the listener in the form properties:
To add the listener:
- Open the form properties.
- Click on Listeners.
- Select the event
beforeSubmitDataand enter the name of your JavaScript function. In our example, it isCalcProgress.
The beforeSubmitData event is triggered when the form is saved. As a result, changes to checkbox selections are not reflected immediately while editing. The progress bar is updated only after the form has been saved.
This example relies on the JavaScript logic above (especially the required naming conventions). To test it, save a new form (e.g. ExampleChecklist.form) and copy the following configuration into the definition source:
{
"title": "Example Progress Bar",
"showTitle": true,
"showFormName": false,
"buttonsFloat": false,
"categories": [],
"sealAfterCreation": false,
"enableProgressSave": false,
"enableEditSummary": false,
"rlDependencies": [],
"useFormRevs": false,
"includable": false,
"extends": "",
"abstract": false,
"partial": false,
"target": {
"type": "json-on-wikipage",
"predefined_title": "ExampleChecklist/{{checklistname}}"
},
"show_target_afterAction": false,
"listeners": {
"beforeSubmitData": "jscb:CalcProgress"
},
"lang": "json",
"items": [
{
"name": "checklistname",
"label": "Checklist name",
"help": "",
"noLayout": false,
"showOn": [
"create"
],
"editableOn": [
"create"
],
"widget_classes": [],
"style": "",
"widgetCustomProps": [],
"widget_listeners": [],
"value": "",
"required": false,
"type": "text"
},
{
"name": "progress",
"label": "Progress",
"help": "",
"noLayout": true,
"showOn": [
"create",
"edit",
"view"
],
"editableOn": [
"create",
"edit"
],
"widget_classes": [],
"style": "margin:1em auto!important; max-width:100%",
"widgetCustomProps": {
"widget_progress": "0"
},
"widget_listeners": [],
"type": "progress_bar"
},
{
"name": "checkbox_multi-getting_started",
"label": "Getting started",
"help": "",
"noLayout": false,
"showOn": [
"create",
"edit",
"view"
],
"editableOn": [
"create",
"edit"
],
"widget_classes": [],
"style": "",
"widgetCustomProps": [],
"widget_listeners": [],
"value": "",
"required": false,
"horizontal": false,
"options": [
{
"data": "check-profile",
"label": "Provide personal and role information"
},
{
"data": "check-documents",
"label": "Submit required documents"
},
{
"data": "check-intro",
"label": "Review introduction materials"
}
],
"type": "checkbox_multiselect"
},
{
"name": "checkbox_multi-workplace_setup",
"label": "Workplace setup",
"help": "",
"noLayout": false,
"showOn": [
"create",
"edit",
"view"
],
"editableOn": [
"create",
"edit"
],
"widget_classes": [],
"style": "",
"widgetCustomProps": [],
"widget_listeners": [],
"value": "",
"required": false,
"horizontal": false,
"options": [
{
"data": "check-equipment",
"label": "Provide equipment (laptop, phone)"
},
{
"data": "check-access",
"label": "Grant access to required systems"
},
{
"data": "check-intro",
"label": "Meet the team"
}
],
"type": "checkbox_multiselect"
}
]
}
