Manual:Extension/Forms/Progress bar

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.

Example of a progress bar for checklist items

To recreate this form, the following components are required:

1. Provide the JavaScript logic in MediaWiki:Common.js
2. Define matching checkbox field and option syntax
3. 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:

Data definition in form, here starting with "check-"

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:

Adding the listener to the form properties

To add the listener:

1. Open the form properties.
2. Click on Listeners.
3. Select the event beforeSubmitData and enter the name of your JavaScript function. In our example, it is CalcProgress.

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 defines a page naming pattern 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"
		}
	]
}

PDF exclude - start

---

To submit feedback about this documentation, visit our community forum.

PDF exclude - end