Skip to content
Formulare

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

  1. Überblick
  2. Schnellstart
  3. Wizard
  4. Container-Attribute
  5. Bedingte Seiten (data-wizard-if)
  6. Optionale UI-Elemente
  7. Validierung
  8. Ereignisse
  9. Absende-Verhalten
  10. PictureUpload
  11. JavaScript-API
  12. Beispiele
  13. 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.PictureUpload und window.resizeImage sind global verfügbar; die Instanz liegt zusätzlich am DOM-Element (form.wizard bzw. 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:

Seite 1

Seite 2

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

… Seite 1 …
… Seite 2 …
… Seite 3 …
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.

  • 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-Klasse was-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 mit data-wizard-if sofort 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 Format Step 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 auf position / aktiveSeiten * 100 % gesetzt; zusätzlich wird aria-valuenow gepflegt.

Validierung

Die Validierung nutzt die native HTML5-Validierung im Browser:

  1. Alle input, select und textarea-Elemente der aktuellen Seite werden mit checkValidity() geprüft (d. h. required, pattern, minlength, … wirken ganz normal).
  2. Die Seite erhält die Bootstrap-Klasse was-validated, dadurch werden Fehler rot markiert.
  3. Bei einem ungültigen Feld bekommt das erste ungültige Feld den Fokus; der Wizard bleibt auf der Seite.
  4. data-validate="false" auf dem Container schaltet diesen Schritt komplett ab.

Tipp: Setzen Sie novalidate auf 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); });

TXT
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 Enter erzeugt ein submit-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:finish und lässt das submit-Ereignis laufen (kein preventDefault). Andere submit-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:finish wird 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">

TXT
  <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-input oder data-pic-table nicht 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 (rote btn 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 auf input.files geschrieben wird — beim Absenden des umgebenden Formulars werden genau diese Dateien an den Server übertragen und dort aus Request.Context.Files gelesen.
  • 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 accept nicht eingehalten wird) werden unverändert übernommen.
  • Canvas-Fehler (z. B. toBlob schlägt fehl): Die ursprüngliche Datei wird als Fallback übernommen — das Bild wird nicht verworfen.
  • Bild lädt nicht (img.onerror): Der Promise wird mit Failed to load image: <name> abgelehnt; in addFiles wird 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: Default 1600, quality: Default 0.8.
  • Gibt Promise<File>: verkleinertes Bild als neue File (gleicher Dateiname, neues type, neues lastModified).
  • Nicht-Bilder werden unverändert aufgelöst.
  • Wird bei Fehlschlag abgelehnt (reject) — addFiles fä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">

TXT
  <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

TXT
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">

TXT
  <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)

TXT
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.

© 2026 Aduna Dokumentation. Alle Rechte vorbehalten.