Manual:Extension/Forms/Progress bar

The progress bar is useful to count completed checklist items, for example.

Adding a progress bar

We add a progress bar to a checklist that shows how many tasks habe been completed.

Example of a progress bar for checklist items

For this, we need to set up the following components:

1. Provide the logic in MediaWiki:Common.js
2. Apply the syntax to the checklist items
3. Create an event listener in the form properties

Provide the logic in MediaWiki:Common.js

Add the following JavasScript 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". You can verify this in the definition source of your form:

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-' ) ) {

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.

If you want to test this example, you can save an empty example form (e.g., ExampleChecklist.form) and copy the following 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