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.
To recreate this form, the following components are required:
- Provide the JavaScript logic in MediaWiki:Common.js
- Define matching checkbox field and option syntax
- Add 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 and refers 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_multiin 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.
Complete implementation example
This example relies on the JavaScript logic above (especially the required naming conventions). It also uses a page naming pattern defined in the JSON configuration below. Each checklist is saved as a separate wiki page under the ExampleChecklist/ prefix, using the checklist name as part of the page title.
To use this example, 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"
}
]
}
