Handbuch:Erweiterung/Forms/Fortschrittsbalken

← Erweiterung/Forms

no subpages

Der Fortschrittsbalken zeigt einen berechneten Fortschrittswert basierend auf den ausgewählten Optionen in einem Formular an. In diesem Beispiel wird er für eine Checkliste verwendet, kann jedoch auch für andere Anwendungsfälle eingesetzt werden.

Hinzufügen eines Fortschrittsbalkens

Dieses Beispiel zeigt eine mögliche Implementierung eines Fortschrittsbalkens für eine Checkliste.

Beispiel eines Fortschrittsbalkens für Checklistenpunkte

Um dieses Formular nachzubilden, werden folgende Komponenten benötigt:

1. Bereitstellen der JavaScript-Logik in MediaWiki:Common.js
2. Definition der passenden Syntax für Kontrollkästchenfelder und deren Optionen
3. Hinzufügen eines Event-Listeners in den Formulareigenschaften

Bereitstellen der Logik in MediaWiki:Common.js

Fügen Sie die folgende JavaScript-Funktion zu MediaWiki:Common.js hinzu:

/*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();
}

In Zeile 5 wird das Präfix für jedes Kontrollkästchen definiert, das in die Fortschrittsberechnung einbezogen werden soll:

input[value^=check]

Das bedeutet, dass der Wert data Ihrer Kontrollkästchen mit check beginnen muss. Dies bezieht sich auf den data-Wert, der in jeder Kontrollkästchenoption definiert wird:

Datendefinition im Formular, hier beginnend mit „check-“

In Zeile 14 werden nur diejenigen Felder berücksichtigt, deren Name mit checkbox_multi beginnt:

	if ( !name.startsWith( 'checkbox_multi-' ) ) {

Basierend auf diesem Implementierungsbeispiel wird eine Kontrollkästchenoption nur dann in die Fortschrittsberechnung einbezogen, wenn der Feldname mit checkbox_multi- beginnt und der data-Wert der Option mit check anfängt.

Wenn Sie andere Präfixe für Feldnamen oder Optionswerte verwenden, müssen Sie den JavaScript-Code entsprechend anpassen.

Anwenden der Syntax auf die Checklistenpunkte

Das folgende Feld vom Typ checkbox_multiselect verwendet sowohl das korrekte Namenspräfix als auch das korrekte data-Präfix. Das Feld wird daher in die Berechnung einbezogen, und alle drei Optionen tragen zum Fortschrittswert bei:

	{
			"name": "checkbox_multi-workplace_setup",
			"label": "Workplace setup",
			...
			"options": [
				{
					"data": "check-equipment",
					"label": "Ausstattung bereitstellen (Laptop, Telefon)"
				},
				{
					"data": "check-access",
					"label": "Zugriff auf erforderliche Systeme gewähren"
				},
				{
					"data": "check-intro",
					"label": "Vorstellung im Team"
				}
			],
			"type": "checkbox_multiselect"
		}

Erstellen eines Event-Listeners in den Formulareigenschaften

Um Ihr Formular mit der JavaScript-Funktion zu verbinden, müssen Sie in den Formulareigenschaften den Listener anlegen:

Hinzufügen des Listeners zu den Formulareigenschaften

So fügen Sie den Listener hinzu:

1. Öffnen Sie die Formulareigenschaften.
2. Klicken Sie auf Listeners.
3. Wählen Sie das Ereignis beforeSubmitData aus und geben Sie den Namen Ihrer JavaScript-Funktion ein. In unserem Beispiel lautet dieser CalcProgress.

Das Ereignis beforeSubmitData wird beim Speichern des Formulars ausgelöst. Änderungen an Kontrollkästchen-Auswahlen werden daher während der Bearbeitung nicht unmittelbar berücksichtigt. Der Fortschrittsbalken wird erst nach dem Speichern des Formulars aktualisiert.

Vollständiges Implementierungsbeispiel

Dieses Beispiel basiert auf der oben beschriebenen JavaScript-Logik (insbesondere den erforderlichen Namenskonventionen). Zusätzlich wird in der untenstehenden JSON-Konfiguration ein Schema für die Seitennamensgebung definiert. Jede Checkliste wird als eigene Wiki-Seite unter dem Präfix ExampleChecklist/ gespeichert, wobei der Name der Checkliste Bestandteil des Seitentitels ist.

Um dieses Beispiel zu verwenden, speichern Sie ein neues Formular (z. B. ExampleChecklist.form) und kopieren Sie die folgende Konfiguration in die Definitionsquelle:

{
	"title": "Beispiel Fortschrittsbalken",
	"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": "BeispielCheckliste/{{checklistname}}"
	},
	"show_target_afterAction": false,
	"listeners": {
		"beforeSubmitData": "jscb:CalcProgress"
	},
	"lang": "json",
	"items": [
		{
			"name": "checklistname",
			"label": "Checkliste Name",
			"help": "",
			"noLayout": false,
			"showOn": [
				"create"
			],
			"editableOn": [
				"create"
			],
			"widget_classes": [],
			"style": "",
			"widgetCustomProps": [],
			"widget_listeners": [],
			"value": "",
			"required": false,
			"type": "text"
		},
		{
			"name": "progress",
			"label": "Fortschritt",
			"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": "Loslegen",
			"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": "Persönliche Angaben und Rolleninformationen bereitstellen"
				},
				{
					"data": "check-documents",
					"label": "Erforderliche Dokumente einreichen"
				},
				{
					"data": "check-intro",
					"label": "Einführungsmaterialien durchsehen"
				}
			],
			"type": "checkbox_multiselect"
		},
		{
			"name": "checkbox_multi-workplace_setup",
			"label": "Einrichtung des Arbeitsplatzes",
			"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": "Ausstattung bereitstellen (Laptop, Telefon)"
				},
				{
					"data": "check-access",
					"label": "Zugriff auf erforderliche Systeme gewähren"
				},
				{
					"data": "check-intro",
					"label": "Vorstellung im Team"
				}
			],
			"type": "checkbox_multiselect"
		}
	]
}