Formulare
Dieses Dokument beschreibt zwei kleine, voneinander unabhängige JavaScript-Bausteine, die über Data-Attribute automatisch initialisiert werden:
- Wizard — ein Mehrseiten-Formular (Wizard) für Bootstrap 5.1 mit bedingbaren Seiten, Schritt-Anzeige, Fortschrittsbalken und pro-Seite-Validierung.
- PictureUpload — eine Mehrfach-Bildauswahl mit Vorschauliste, pro-Datei-Löschen und optionaler clientseitiger Verkleinerung, bevor das echte
<input type="file">mit dem Formular übermittelt wird.
Beide Bausteine brauchen keinen manuellen JS-Aufruf von der Seite: Das Legen der Data-Attribute im HTML genügt. Beim DOMContentLoaded sucht die Bibliothek automatisch alle [data-wizard]- bzw. [data-pic-upload]-Elemente und erzeugt je ein Objekt.
Inhaltsverzeichnis
- Überblick
- Schnellstart
- Wizard
- Container-Attribute
- Bedingte Seiten (data-wizard-if)
- Optionale UI-Elemente
- Validierung
- Ereignisse
- Absende-Verhalten
- PictureUpload
- JavaScript-API
- Beispiele
- Hinweise & FAQ
Überblick
| Baustein | Auslöser im HTML | Zweck |
|---|---|---|
| Wizard | <form data-wizard> (oder jedes andere Element) |
Zeigt pro Seite einen Ausschnitt des Formulars an, validiert vor dem Weiterklicken und sammelt am Ende nur die Werte der tatsächlich gezeigten Seiten. |
| PictureUpload | <div data-pic-upload> |
Steuert ein <input type="file" multiple> über einen Button, zeigt Vorschaubilder mit Größe an, erlaubt pro Datei Löschen und verkleinert Bilder optional im Browser, bevor sie hochgeladen werden. |
Gemeinsame Konventionen:
- Auto-Initialisierung:
document.querySelectorAll("[data-wizard]")bzw."[data-pic-upload]"— ein Objekt pro gefundenem Element. Mehrere Instanzen pro Seite sind erlaubt. - Öffentliche Objekte:
window.Wizard,window.PictureUploadundwindow.resizeImagesind global verfügbar; die Instanz liegt zusätzlich am DOM-Element (form.wizardbzw.container.pictureUpload). - Keine Abhängigkeiten außer Bootstrap-5.1-Klassen (
d-none,was-validated,btn,progress-bar, …).
Schnellstart
Minimalbeispiel eines Wizards ohne zusätzliche JS:
Bereits daraus folgt:
- Seite 1 ist sichtbar, Seite 2 ist ausgeblendet.
- „Next“ validiert Seite 1 (Bootstrap
was-validated-Feedback) und blendet dann Seite 2 ein. - Auf der letzten Seite wechselt das Label auf „Finish“ und die native Formular-Absendung läuft.
- „Bilder hinzufügen“ öffnet den Dateidialog, gewählte Bilder erscheinen mit Vorschau in der Tabelle, „Löschen“ entfernt sie.
Wizard
HTML-Struktur
| Element | Zweck |
|---|---|
[data-wizard] |
Container (meist <form>), wird beim Laden initialisiert |
[data-wizard-page] |
Eine Seite des Wizards; exakt eine ist sichtbar |
[data-wizard-back] |
Button „Zurück“ (typisch type="button") |
[data-wizard-next] |
Button „Weiter“/„Finish“; bei <form>-Wurzeln type="submit" |
[data-wizard-step] |
(optional) Textanzeige für die aktuelle Position |
[data-wizard-progress] |
(optional) Bootstrap .progress-bar, dessen Breite den Fortschritt anzeigt |
Hinweis: Wenn der Container keine
[data-wizard-page]-Elemente enthält, wird kein Wizard angelegt.
Navigation im Detail
- Weiterklicken validiert zuerst die aktuelle Seite (
checkPage()). Bei Fehlern bleibt der Wizard auf der Seite, das erste ungültige Feld erhält den Fokus und die Seite bekommt die Bootstrap-Klassewas-validated. - Zurückklicken validiert nicht und springt direkt zur vorherigen aktiven Seite.
- Tastatur: Auf einer Formular-Wurzel führt auch
Enter(native Absenden) zum nächsten Schritt — das Absende-Ereignis wird für die Navigation genutzt (siehe Absende-Verhalten). - Auf der ersten aktiven Seite ist der Back-Button deaktiviert.
- Bei jeder Änderung eines Formularfelds im Container (
change-Ereignis) werden Buttons, Schritt-Text und Fortschrittsbalken neu berechnet — dadurch wirken sich Radios-Auswahlen mitdata-wizard-ifsofort auf die Anzahl der Seiten aus.
Container-Attribute
| Attribut | Wert | Standard | Beschreibung |
|---|---|---|---|
data-next-text |
Text | Next |
Label des Vorwärts-Buttons |
data-finish-text |
Text | Finish |
Label des Buttons auf der letzten Seite |
data-validate |
false |
aktiv | Deaktiviert die pro-Seite-Feldvalidierung (Navigation ohne Prüfen) |
Beispiel:
<form data-wizard novalidate data-next-text="Weiter" data-finish-text="Abschließen" data-validate="false"> …
Bedingte Seiten (data-wizard-if)
Ein data-wizard-if-Attribut auf einer Seite bestimmt, ob die Seite angezeigt, validiert und übermittelt wird. Ohne Attribut ist die Seite immer aktiv.
| Syntax | Bedeutung |
|---|---|
data-wizard-if="feld=wert" |
Seite nur anzeigen, wenn das Feld feld den Wert wert hat |
data-wizard-if="feld=wert1,wert2" |
Mehrere erlaubte Werte (Komma-getrennt) |
data-wizard-if="checkbox=true" |
Seite nur anzeigen, wenn die Checkbox aktiviert ist |
Wie der aktuelle Feldwert ermittelt wird:
| Feldtyp | Ermittelter Wert |
|---|---|
radio |
value der ausgewählten Option |
checkbox |
true bzw. false |
input, select, textarea |
aktueller value |
mehrfache gleiche name |
Wert des letzten Feldes mit diesem Namen |
Wird eine Seite übersprungen, gilt: weder validiert noch übermittelt. Bei wizard:finish fehlen ihre Felder in detail.data, und beim collect() werden sie ausgelassen.
Optionale UI-Elemente
Beide Elemente werden automatisch mit der aktuellen Position synchron gehalten.
[data-wizard-step]: Textanzeige im FormatStep 2 of 3(aktive Seite / aktive Seiten, nur gezählt wird, was gerade sichtbar ist).[data-wizard-progress]: Bootstrap-.progress-bar-Element. Die Breite wird aufposition / aktiveSeiten * 100 %gesetzt; zusätzlich wirdaria-valuenowgepflegt.
Validierung
Die Validierung nutzt die native HTML5-Validierung im Browser:
- Alle
input,selectundtextarea-Elemente der aktuellen Seite werden mitcheckValidity()geprüft (d. h.required,pattern,minlength, … wirken ganz normal). - Die Seite erhält die Bootstrap-Klasse
was-validated, dadurch werden Fehler rot markiert. - Bei einem ungültigen Feld bekommt das erste ungültige Feld den Fokus; der Wizard bleibt auf der Seite.
data-validate="false"auf dem Container schaltet diesen Schritt komplett ab.
Tipp: Setzen Sie
novalidateauf das Formular, damit der Browser sein eigenes natives Validierungs-Overlay nicht zusätzlich anzeigt — die pro-Seite-Prüfung übernimmt der Wizard.
Ereignisse
Beide Ereignisse werden am Container als CustomEvent mit bubbles: true ausgelöst.
| Ereignis | detail |
Zeitpunkt |
|---|---|---|
wizard:change |
{ index, page } |
nach jedem Seitenwechsel (index = 0-basierter Seitenindex, page = DOM-Element) |
wizard:finish |
{ data } |
auf der letzten Seite nach erfolgreicher Validierung |
data ist das Ergebnis von collect() (siehe JavaScript-API): ein Objekt mit den Werten aller aktiven Seiten. form.addEventListener("wizard:change", function (e) { console.log("Seite", e.detail.index + 1, e.detail.page); });
form.addEventListener("wizard:finish", function (e) {
console.log(e.detail.data);
});
Absende-Verhalten
Gilt nur für Container mit der Wurzel <form>:
- Zwischen den Seiten: Klick auf „Next“ oder
Entererzeugt einsubmit-Ereignis. Der Wizard unterbricht es (preventDefault) und blendet einfach die nächste Seite ein — es findet kein Netzwerk-Request statt. - Letzte Seite: Wenn die Validierung besteht, feuert der Wizard
wizard:finishund lässt dassubmit-Ereignis laufen (keinpreventDefault). Anderesubmit-Listeners am Formular (z. B. Einfügen versteckter Felder, Analytics) laufen daher genau wie bei einem normalen Formular, und das Formular wird tatsächlich an den Server gesendet. - Letzte Seite, Validierung fehlgeschlagen: Das Ereignis wird unterbrochen,
wizard:finishwird nicht ausgelöst, es wird nichts gesendet.
Nicht-Formulare (z. B. <div data-wizard>) senden nicht; auf der letzten Seite wird nur wizard:finish gefeuert, ohne dass das submit-Ereignis beteiligt ist.
PictureUpload
HTML-Struktur
<div data-pic-upload data-pic-max-width="1600" data-pic-max-height="1600" data-pic-quality="0.8" data-pic-resize="false">
<input type="file" data-pic-input name="pictures" multiple accept="image/*">
<table data-pic-table style="display:none">
<thead>
<tr><th></th><th>Datei</th><th>Größe</th><th></th></tr>
</thead>
<tbody></tbody>
</table>
</div>
| Element | Zweck |
|---|---|
[data-pic-upload] |
Container, wird beim Laden initialisiert |
[data-pic-add] |
Button, der den Dateidialog öffnet |
[data-pic-input] |
Das eigentliche <input type="file" multiple>; seine name wird beim Absenden verwendet |
[data-pic-table] |
Tabelle für die Vorschauliste; bleibt verborgen, solange keine Dateien gewählt sind |
Hinweis: Sind
data-pic-add,data-pic-inputoderdata-pic-tablenicht vorhanden, wird keine Instanz angelegt.
Attribute
| Attribut | Standard | Beschreibung |
|---|---|---|
data-pic-max-width |
1600 |
Maximale Breite in Pixel nach der Verkleinerung |
data-pic-max-height |
1600 |
Maximale Höhe in Pixel nach der Verkleinerung |
data-pic-quality |
0.8 |
JPEG-/WebP-Qualität (0–1) |
data-pic-resize |
aktiv | Auf false setzen, um die Verkleinerung komplett zu überspringen |
Funktionsweise
- Verkleinerung: Bilder größer als die Maximalwerte werden mit einem Canvas herunterskaliert (Seitenverhältnis erhalten, nie vergrößert). PNG bleibt verlustfrei PNG; alle anderen Bildtypen werden zu JPEG mit der konfigurierten Qualität konvertiert.
- Vorschau: Jede gewählte Datei erhält eine Zeile mit 60×60-Vorschaubild, dem Label
Bild N (dateiname)und der Größe in KB. - Löschen: Der
Löschen-Button (rotebtn btn-danger btn-sm) entfernt die Datei aus dem Upload; die Liste und das echte<input>werden neu synchronisiert. - Echte Übermittlung: Die gewählten Dateien liegen immer in einem
DataTransfer, der aufinput.filesgeschrieben wird — beim Absenden des umgebenden Formulars werden genau diese Dateien an den Server übertragen und dort ausRequest.Context.Filesgelesen. - Gleiche Datei erneut wählen: Nach jeder Auswahl wird der Input geleert (
value = ""), sodass dieselbe Datei ein zweites Mal gewählt werden kann.
Fehlerbehandlung
- Nicht-Bilder (z. B. wenn
acceptnicht eingehalten wird) werden unverändert übernommen. - Canvas-Fehler (z. B.
toBlobschlägt fehl): Die ursprüngliche Datei wird als Fallback übernommen — das Bild wird nicht verworfen. - Bild lädt nicht (
img.onerror): Der Promise wird mitFailed to load image: <name>abgelehnt; inaddFileswird dann ebenfalls auf die Ursprungsdatei zurückgefallen.
JavaScript-API
Wizard
Instanz: form.wizard (oder new Wizard(root) manuell).
| Methode / Eigenschaft | Beschreibung |
|---|---|
value(name) |
Aktueller Wert eines Feldes mit name (Radio/Checkbox/normal, siehe oben) |
isActive(page) |
true, wenn die Seite page gerade angezeigt wird |
activePages() |
Array aller aktuell aktiven Seiten |
find(step) |
Index der nächsten (+1) bzw. vorherigen (-1) aktiven Seite; -1 wenn keine |
show(index) |
Seite index anzeigen (triggert wizard:change) |
update() |
Back-/Next-Buttons, Schritt-Text und Fortschrittsbalken neu berechnen |
next() |
Aktive Seite validieren und zur nächsten aktiven Seite springen bzw. wizard:finish feuern |
back() |
Zur vorherigen aktiven Seite (ohne Validierung) |
checkPage() |
Felder der aktuellen Seite validieren; true/false |
collect() |
Objekt mit den Werten aller aktiven Seiten (Checkboxen → boolean, Radios → value, sonst value; Felder außerhalb von Seiten sind ebenfalls enthalten) |
emit(name, detail) |
CustomEvent am Container auslösen |
Eigenschaften: root, pages, index, nextText, finishText, validate.
PictureUpload
Instanz: container.pictureUpload (oder new PictureUpload(root) manuell).
| Methode / Eigenschaft | Beschreibung |
|---|---|
addFiles(fileList) |
Dateien aufnehmen: optional verkleinern, in den internen DataTransfer aufnehmen, Input + Tabelle aktualisieren |
updateList() |
input.files mit dem internen DataTransfer synchronisieren und die Vorschautabelle neu zeichnen |
removeFile(index) |
Datei an der Position index entfernen (0-basiert) |
Eigenschaften: root, input, table, tbody, dataTransfer, doResize, maxWidth, maxHeight, quality.
resizeImage
Standalone-Helfer (auch global: window.resizeImage): resizeImage(file, maxWidth, maxHeight, quality) → Promise
maxWidth/maxHeight: Default1600,quality: Default0.8.- Gibt
Promise<File>: verkleinertes Bild als neueFile(gleicher Dateiname, neuestype, neueslastModified). - Nicht-Bilder werden unverändert aufgelöst.
- Wird bei Fehlschlag abgelehnt (
reject) —addFilesfängt das und fällt auf die Ursprungsdatei zurück.
Beispiele
Beispiel 1: Registrierungswizard mit bedingten Seiten
<form data-wizard novalidate data-next-text="Weiter" data-finish-text="Abschließen">
<div class="progress mb-4" style="height: 6px;">
<div data-wizard-progress class="progress-bar" role="progressbar"></div>
</div>
<div data-wizard-page>
<h2>Kontotyp</h2>
<div class="form-check">
<input class="form-check-input" type="radio" name="scope"
id="scope-simple" value="simple" checked>
<label class="form-check-label" for="scope-simple">Privat</label>
</div>
<div class="form-check">
<input class="form-check-input" type="radio" name="scope"
id="scope-detailed" value="detailed">
<label class="form-check-label" for="scope-detailed">Firma</label>
</div>
</div>
<div data-wizard-page data-wizard-if="scope=detailed">
<h2>Firmendaten</h2>
<div class="mb-3">
<label class="form-label">Firmenname</label>
<input type="text" name="firma" class="form-control" required>
</div>
</div>
<div data-wizard-page>
<h2>Kontaktdaten</h2>
<div class="mb-3">
<label class="form-label">E-Mail</label>
<input type="email" name="email" class="form-control" required>
</div>
<div class="form-check">
<input type="checkbox" name="newsletter" id="nl"
class="form-check-input">
<label class="form-check-label" for="nl">Newsletter</label>
</div>
</div>
<div class="mt-4">
<button type="button" data-wizard-back class="btn btn-outline-secondary">Zurück</button>
<button type="submit" data-wizard-next class="btn btn-primary">Weiter</button>
</div>
</form>
Erwartetes Verhalten:
| Auswahl auf Seite 1 | Ergebnis |
|---|---|
Privat |
2 Seiten: Step 1 of 2 → Step 2 of 2, „Firmendaten“ wird übersprungen, firma fehlt in wizard:finish.data |
Firma |
3 Seiten: Step 1 of 3 → Step 2 of 3 → Step 3 of 3, „Firmenname“ muss ausgefüllt sein, sonst bleibt der Wizard auf Seite 2 |
Bei Firma + ausgefüllten Feldern sieht e.detail.data am Ende so aus: { scope: "detailed", firma: "ACME GmbH", email: "max@acme.de", newsletter: true }
Beispiel 2: Wizard-Ereignisse abfangen
var form = document.querySelector("[data-wizard]");
form.addEventListener("wizard:change", function (e) {
console.log("Seite " + (e.detail.index + 1) + ":", e.detail.page);
});
form.addEventListener("wizard:finish", function (e) {
console.log("Fertig:", e.detail.data);
});
AJAX statt nativer Absendung: Da der Wizard das submit-Ereignis auf der letzten Seite laufen lässt, genügt ein eigener Listener mit preventDefault, um die native Übermittlung zu ersetzen: form.addEventListener("submit", function (e) { e.preventDefault(); // hier z. B. fetch(...) senden });
Beispiel 3: Bild-Upload mit Verkleinerung
<div data-pic-upload data-pic-max-width="1200" data-pic-max-height="1200" data-pic-quality="0.7">
<input type="file" data-pic-input name="pictures"
multiple accept="image/*">
<table data-pic-table class="table table-sm mt-3" style="display:none">
<thead>
<tr><th></th><th>Datei</th><th>Größe</th><th></th></tr>
</thead>
<tbody></tbody>
</table>
</div>
Innerhalb eines <form method="post" enctype="multipart/form-data"> werden die (verkleinerten) Dateien beim Absenden als Upload an den Server gesendet. Serverseitig werden die Dateien aus Request.Context.Files gelesen.
Beispiel 4: Bild-Upload ohne Verkleinerung
Die Originaldateien werden unverändert in den Input geschrieben.
Beispiel 5: Einzelnes Bild verkleinern (resizeImage)
input.addEventListener("change", function () {
var file = this.files[0];
window.resizeImage(file, 800, 800, 0.6)
.then(function (small) {
console.log(small.name, small.size); // verkleinertes Bild
})
.catch(function (err) {
console.error(err.message); // z. B. "Failed to load image: foto.jpg"
});
});
Hinweise & FAQ
Warum novalidate am Formular? Der Wizard validiert pro Seite selbst und setzt was-validated für das Bootstrap-Feedback. Ohne novalidate würde der Browser zusätzlich sein natives Overlay auf der ganzen Seite anzeigen, bevor der Wizard überhaupt gefragt ist.
Was passiert, wenn die Validierung auf der letzten Seite fehlschlägt? Das submit-Ereignis wird unterbrochen: Es wird nichts gesendet und wizard:finish wird nicht ausgelöst.
Werden übersprungene Seiten übermittelt? Nein — weder validiert noch in collect() bzw. wizard:finish.data enthalten.
Kann ich mehrere Wizards/Bild-Uploads auf einer Seite haben? Ja, es wird exakt eine Instanz pro [data-wizard]- bzw. [data-pic-upload]-Element erzeugt.
Was passiert mit Feldern außerhalb von [data-wizard-page]? Sie werden von collect() ebenfalls erfasst (nur Seiten, die nicht aktiv sind, werden ausgeschlossen).
Kann der Wizard in einem div statt form laufen? Ja — dann gibt es aber kein natives Absenden und kein submit-Ereignis; die Navigation läuft über die Buttons (next()/back()), auf der letzten Seite feuert nur wizard:finish.
Warum ist der „Next“-Button bei Formularen type="submit"? Damit auch Enter den nächsten Schritt auslöst. Die Navigation wird bewusst über das submit-Ereignis gesteuert; der Button-Klick ruft next() deshalb nicht direkt erneut auf (das würde den Wizard sonst doppelt pro Klick vorwärts bewegen).
Beeinflusst data-pic-quality PNG-Bilder? Nein — PNG wird verlustfrei als PNG ausgegeben, die Qualität greift nur für JPEG-Ausgaben.
Was passiert, wenn die Verkleinerung fehlschlägt? Die ursprüngliche Datei wird übermittelt, damit kein Bild verloren geht.