WP-Multi-Formular/README.md

# WP Multi Formular

**Version:** 1.0.0  
**Autor:** M_Viper  
**Website:** https://m-viper.de  

---

## Inhaltsverzeichnis

1. [Beschreibung](#beschreibung)
2. [Installation](#installation)
3. [Erstes Formular erstellen](#erstes-formular-erstellen)
4. [Formular-Builder](#formular-builder)
5. [Feldtypen](#feldtypen)
6. [Bedingte Logik](#bedingte-logik)
7. [Mehrstufige Formulare](#mehrstufige-formulare)
8. [E-Mail-Einstellungen](#e-mail-einstellungen)
9. [Einreichungen verwalten](#einreichungen-verwalten)
10. [Integrationen](#integrationen)
11. [Anti-Spam](#anti-spam)
12. [Shortcode](#shortcode)
13. [Datenbankstruktur](#datenbankstruktur)
14. [Häufige Fragen](#häufige-fragen)
15. [Changelog](#changelog)

---

## Beschreibung

WP Multi Formular ist ein vollständiger Drag & Drop Formular-Builder für WordPress.  
Komplett auf Deutsch, keine externe Lizenz, keine monatlichen Kosten.

**Kernfunktionen:**
- Drag & Drop Builder mit Live-Vorschau
- 18 Feldtypen inkl. DSGVO, Unterschrift, Bewertung
- Bedingte Logik (Felder ein-/ausblenden)
- Mehrstufige Formulare mit Fortschrittsleiste
- Einreichungen vollständig im Backend lesen
- E-Mail-Benachrichtigungen (Admin + Absender)
- SMTP-Unterstützung (eigener Mailserver)
- Honeypot + reCAPTCHA Anti-Spam
- 11 Integrationen (Mailchimp, Stripe, Zapier u.v.m.)
- CSV-Export aller Einreichungen
- DSGVO-konform

---

## Installation

1. ZIP-Datei herunterladen
2. WordPress Admin → **Plugins → Installieren → Plugin hochladen**
3. ZIP auswählen und installieren
4. Plugin **aktivieren**

Das Plugin legt beim ersten Aktivieren automatisch die Datenbank-Tabelle `wp_wmf_submissions` an.

**Mindestanforderungen:**
- WordPress 5.8 oder höher
- PHP 7.4 oder höher
- MySQL 5.7 oder höher

---

## Erstes Formular erstellen

1. **Formulare → + Neues Formular** anklicken
2. Einen Titel eingeben (z.B. „Kontaktformular")
3. Felder aus der linken Palette in die Mitte ziehen oder anklicken
4. Felder per Drag & Drop anordnen
5. Rechts die Formular-Einstellungen konfigurieren (E-Mails, Erfolgsmeldung)
6. **Formular speichern** klicken
7. Den angezeigten Shortcode auf einer Seite oder in einem Beitrag einfügen:

```
[wp_multi_formular id="123"]
```

---

## Formular-Builder

Der Builder besteht aus drei Bereichen:

```
┌──────────────┬─────────────────────────┬────────────────┐
│   Palette    │         Canvas          │  Einstellungen │
│  (Felder)    │   (Formular-Aufbau)     │  (rechts)      │
│              │                         │                │
│ ▪ Textfeld   │  ┌─ Ihr Name ────────┐  │  [Tabs]        │
│ ▪ E-Mail     │  ├─ E-Mail ──────────┤  │  Allgemein     │
│ ▪ Textarea   │  ├─ Nachricht ───────┤  │  E-Mails       │
│ ▪ Auswahl    │  └─ Absenden ────────┘  │  Schritte      │
│ ▪ …          │                         │  Erweitert     │
└──────────────┴─────────────────────────┴────────────────┘
```

**Feld hinzufügen:** Links anklicken oder in die Mitte ziehen  
**Feld verschieben:** Am ≡ Symbol ziehen  
**Feld konfigurieren:** Auf das Feld klicken → Einstellungen öffnen sich rechts  
**Feld löschen:** ✕ Button im Feld oder „Feld löschen" im Einstellungs-Panel  
**Vorschau:** „👁 Vorschau" Button oben rechts

---

## Feldtypen

### Standard-Felder

| Feldtyp | Beschreibung |
|---|---|
| **Textfeld** | Einzeiliges Textfeld, mit Platzhalter und Pflichtfeld-Option |
| **E-Mail** | E-Mail mit Formatvalidierung |
| **Textbereich** | Mehrzeiliges Feld, konfigurierbare Zeilenanzahl und Zeichenbegrenzung |
| **Zahl** | Numerisches Eingabefeld mit Min/Max/Schrittweite |
| **Telefon** | Telefonnummer-Feld (type="tel") |
| **Website-URL** | URL mit Formatvalidierung |
| **Datum** | Datums-Picker mit optionalem Min/Max-Datum |
| **Datei-Upload** | Dateiupload mit Typ- und Größenbeschränkung, speichert in WordPress-Mediathek |

### Auswahl-Felder

| Feldtyp | Beschreibung |
|---|---|
| **Auswahlliste** | Dropdown-Menü, einzeln oder Mehrfachauswahl |
| **Kontrollkästchen** | Mehrere Optionen wählbar, horizontales oder vertikales Layout |
| **Radio-Buttons** | Genau eine Option wählbar |
| **Bewertung (Sterne)** | Sterne-Bewertung, 1–10 Sterne konfigurierbar |
| **Schieberegler** | Numerischer Bereich mit konfigurierbarem Min/Max |
| **DSGVO-Zustimmung** | Pflicht-Checkbox mit anpassbarem Datenschutz-Text |
| **Unterschrift** | Canvas-Feld zum Unterschreiben (Maus oder Touch) |

### Layout-Felder

| Feldtyp | Beschreibung |
|---|---|
| **Trennlinie / Abschnitt** | Optische Trennung oder Abschnittsüberschrift |
| **HTML-Block** | Freier HTML-Inhalt im Formular |
| **Verstecktes Feld** | Unsichtbares Feld, unterstützt dynamische Werte |

**Dynamische Werte für versteckte Felder:**
- `{{user_ip}}` – IP-Adresse des Besuchers
- `{{page_url}}` – Aktuelle Seiten-URL
- `{{date}}` – Aktuelles Datum (YYYY-MM-DD)

### Feld-Optionen (alle Felder)

- **Bezeichnung** – Label über dem Feld
- **Feldname** – Interner Name (nur a-z, 0-9, _)
- **Platzhaltertext** – Grauer Hilfstext im leeren Feld
- **Hilfetext** – Beschreibung unter dem Feld
- **Pflichtfeld** – Formular kann nicht ohne dieses Feld abgesendet werden
- **Breite** – Volle Breite / ½ Breite / ⅓ Breite
- **CSS-Klasse** – Eigene CSS-Klasse für individuelles Styling
- **Bedingte Logik** – Feld ein-/ausblenden je nach anderen Feldinhalten

---

## Bedingte Logik

Felder können abhängig von anderen Feldern ein- oder ausgeblendet werden.

**Einrichten:**
1. Feld anklicken → Einstellungen öffnen
2. Ganz unten „Bedingte Logik" auf **Aktiviert** stellen
3. Wählen: Dieses Feld **anzeigen** oder **ausblenden**
4. Bedingung: **alle** oder **eine** Regel muss erfüllt sein
5. Regeln hinzufügen: Welches Feld / Welcher Operator / Welcher Wert

**Verfügbare Operatoren:**
- `ist` – Feldwert ist genau gleich
- `ist nicht` – Feldwert ist ungleich
- `enthält` – Feldwert enthält den Text
- `ist ausgefüllt` – Feld hat irgendeinen Wert

**Beispiel:**  
Ein Textarea-Feld „Anmerkungen" soll nur erscheinen, wenn bei einem Radio-Feld „Ja" ausgewählt wird:
- Dieses Feld: **anzeigen**
- Wenn: **alle** Bedingungen erfüllt sind
- Regel: `[Radio-Feld] ist Ja`

---

## Mehrstufige Formulare

Lange Formulare können in übersichtliche Schritte aufgeteilt werden.

**Aktivieren:**
1. Rechts auf Tab **Schritte** wechseln
2. „Mehrstufiges Formular aktivieren" anhaken
3. Optional: Fortschrittsleiste aktivieren
4. Schritt-Bezeichnungen eingeben (z.B. „Persönliche Daten", „Kontakt", „Bestätigung")

**Felder Schritten zuweisen:**
- Im Canvas hat jedes Feld ein Schritt-Dropdown (S1, S2, S3 …)
- Felder ohne Zuweisung landen in Schritt 1

**Funktionsweise:**
- Besucher navigieren mit „Weiter" / „Zurück" durch die Schritte
- Jeder Schritt wird vor dem Weiterblättern validiert
- Fortschrittsleiste zeigt den aktuellen Schritt an
- Formular wird erst beim letzten Schritt abgesendet

---

## E-Mail-Einstellungen

### Globale Einstellungen (für alle Formulare)

**Formulare → Integrationen → Globale E-Mail-Einstellungen**

- **Absendername** – Name der in der „Von:"-Zeile erscheint
- **Absender-E-Mail** – E-Mail-Adresse des Absenders

> **Tipp:** Nutzen Sie eine E-Mail-Adresse Ihrer eigenen Domain  
> (z.B. `noreply@viper-network.de`) um Spam-Filter zu vermeiden.

### SMTP (eigener Mailserver)

Wenn WordPress-Standard-Mail nicht funktioniert oder E-Mails im Spam landen:

| Einstellung | Beispiel Gmail | Beispiel Strato/IONOS |
|---|---|---|
| SMTP-Host | smtp.gmail.com | smtp.strato.de |
| Port | 587 | 587 |
| Verschlüsselung | TLS | TLS |
| Benutzername | ihre@gmail.com | ihre@domain.de |
| Passwort | App-Passwort | E-Mail-Passwort |

> **Gmail:** Kein normales Passwort verwenden!  
> Google Konto → Sicherheit → 2-Faktor-Authentifizierung → **App-Passwörter** → Neues App-Passwort erstellen

**Test-Mail:** Nach dem Speichern kann eine Test-E-Mail gesendet werden.

### Pro-Formular E-Mail-Einstellungen

Im Formular-Builder (Tab **E-Mails**):

**Admin-Benachrichtigung:**
- An: Empfänger-E-Mail (Standard: WordPress-Admin)
- Betreff: Frei konfigurierbar
- Reply-To: Wird automatisch auf die E-Mail-Adresse des Absenders gesetzt

**Absender-Bestätigung:**
- Sendet automatisch eine Bestätigungs-E-Mail an den Formular-Ausfüller
- Voraussetzung: Formular muss ein E-Mail-Feld enthalten
- Betreff und Nachricht frei konfigurierbar

---

## Einreichungen verwalten

### Übersicht

**Formulare → Einreichungen**

Zeigt alle Formulare mit:
- Gesamtanzahl der Einreichungen
- Anzahl neuer (ungelesener) Einreichungen (blauer Badge)
- Datum der letzten Einreichung

### Einreichungsliste

Klick auf ein Formular öffnet die Liste aller Einreichungen:
- **Status-Tabs:** Alle / Neu / Gelesen / Archiviert
- **Suche:** Volltextsuche in allen Feldwerten
- **Status ändern:** Direkt in der Liste per Dropdown
- **Pagination:** 25 Einreichungen pro Seite
- **CSV-Export:** Alle Einreichungen als Tabelle exportieren

### Detailansicht

Klick auf eine Einreichung öffnet die vollständige Ansicht:
- Alle Feldwerte typengerecht dargestellt
- E-Mail-Adressen als anklickbare Links
- URLs als anklickbare Links
- Sterne-Bewertungen als goldene Sterne
- Bilder direkt angezeigt (bei Datei-Uploads)
- Unterschriften als Bild
- DSGVO-Zustimmung mit Symbol
- Vorherige / Nächste Navigation
- **Drucken** ohne Admin-Menü
- Wird beim Öffnen automatisch als „Gelesen" markiert

### Status-Bedeutung

| Status | Bedeutung |
|---|---|
| **Neu** | Noch nicht geöffnet, blau hervorgehoben |
| **Gelesen** | Wurde in der Detailansicht geöffnet |
| **Archiviert** | Manuell archiviert, ausgeblendet in Standard-Ansicht |

---

## Integrationen

**Formulare → Integrationen**

### E-Mail-Marketing

| Dienst | Benötigt | Funktion |
|---|---|---|
| **Mailchimp** | API-Key + Audience-ID | Abonnenten in Liste eintragen |
| **MailerLite** | API-Key (+ Gruppen-ID) | Abonnenten eintragen |
| **ActiveCampaign** | Konto-URL + API-Key | Kontakt erstellen + Liste |
| **ConvertKit / Kit** | API-Key + (Formular-ID) | Abonnent in Formular eintragen |

### Zahlungsabwicklung

| Dienst | Modus | Benötigt |
|---|---|---|
| **Stripe** | Test / Live | Publishable Key + Secret Key |
| **PayPal** | Sandbox / Live | Client-ID + Secret |

### Automatisierung

| Dienst | Funktion |
|---|---|
| **Zapier** | Sendet JSON-Webhook bei jeder Einreichung |

Zapier kann damit mit 5.000+ anderen Apps verbunden werden (Google Sheets, Slack, CRMs, etc.)

### Analyse

| Dienst | Funktion |
|---|---|
| **Google Analytics (GA4)** | Bindet gtag.js automatisch ein |

### Standortdienste

| Dienst | Funktion |
|---|---|
| **Google Places** | Adress-Autocomplete in Textfeldern |

---

## Anti-Spam

### Honeypot (Standard, immer aktiv)

Ein unsichtbares Feld wird dem Formular hinzugefügt. Menschen sehen und füllen es nicht aus. Bots füllen es automatisch aus und werden stillschweigend blockiert.

**Aktivierung:** Formular-Builder → Tab Allgemein → „Honeypot Anti-Spam aktivieren"

Kein API-Key nötig, kein externer Dienst, keine Auswirkung auf Nutzer.

### reCAPTCHA

**Aktivierung:**
1. Formulare → Integrationen → reCAPTCHA v2 oder v3
2. API-Keys bei [google.com/recaptcha](https://www.google.com/recaptcha/admin/create) erstellen
3. Keys eintragen und speichern
4. Im Formular-Builder → Tab Allgemein → „reCAPTCHA aktivieren"

**v2:** Zeigt die „Ich bin kein Roboter"-Checkbox  
**v3:** Unsichtbar, bewertet Nutzerverhalten mit Score (0.0–1.0, empfohlen: 0.5)

---

## Shortcode

```
[wp_multi_formular id="123"]
```

| Parameter | Beschreibung | Beispiel |
|---|---|---|
| `id` | ID des Formulars (Pflicht) | `id="123"` |

Die Formular-ID ist in der Formularliste unter dem Formular-Namen sichtbar, oder im Shortcode der automatisch nach dem Speichern angezeigt wird.

**Verwendung:**
- In Seiten und Beiträgen als Block oder klassischer Editor
- In Widgets (Textwidget)
- In PHP-Templates: `echo do_shortcode('[wp_multi_formular id="123"]');`

---

## Datenbankstruktur

Das Plugin erstellt eine eigene Tabelle:

**`wp_wmf_submissions`**

| Spalte | Typ | Beschreibung |
|---|---|---|
| `id` | BIGINT | Primärschlüssel, Auto-Increment |
| `form_id` | BIGINT | ID des WordPress-Posts (wmf-form) |
| `data` | LONGTEXT | JSON-kodierte Feldinhalte |
| `ip` | VARCHAR(45) | IP-Adresse des Absenders |
| `user_agent` | TEXT | Browser/OS des Absenders |
| `status` | VARCHAR(20) | neu / gelesen / archiviert |
| `created_at` | DATETIME | Zeitstempel der Einreichung |

Formulare werden als Custom Post Type `wmf-form` gespeichert.  
Formular-Konfiguration (Felder, Einstellungen) liegt in Post-Meta `_wmf_form_data`.

**WordPress-Optionen:**
- `_wmf_service_credentials` – API-Keys aller Integrationen
- `wmf_global_settings` – Globale E-Mail/SMTP-Einstellungen
- `wmf_db_version` – Datenbankversion für Migrations

---

## Häufige Fragen

**Formulare werden abgesendet aber keine E-Mail kommt an**  
→ Formulare → Integrationen → SMTP aktivieren und eigenen Mailserver eintragen.  
→ Test-Mail senden und prüfen ob der Versand funktioniert.  
→ Einreichung trotzdem im Backend unter Formulare → Einreichungen prüfen.

**Labels sind im Frontend unsichtbar (dunkles Theme)**  
→ Die Plugin-CSS setzt Labels auf weiß (`color:#fff!important`) für dunkle Themes.  
→ Falls weiterhin Probleme: In der Theme-CSS `.wmf-label { color: ... !important; }` überschreiben.

**„Headers already sent" Warnung beim Löschen**  
→ Ein anderes aktives Plugin gibt Output aus bevor WordPress die Header sendet.  
→ WP Multi Formular hat dafür einen eingebauten JavaScript-Fallback-Redirect.  
→ Das Löschen funktioniert trotzdem, die Warnung erscheint nur kurz.

**Einreichungen werden nicht gespeichert**  
→ Formular-Builder → Tab Allgemein → „Einreichungen in DB speichern" aktivieren.

**Formular erscheint nicht auf der Seite**  
→ Shortcode prüfen: `[wp_multi_formular id="123"]` – die ID muss korrekt sein.  
→ Formular-Status muss „Veröffentlicht" sein.

**Datei-Uploads funktionieren nicht**  
→ PHP-Einstellung `upload_max_filesize` und `post_max_size` prüfen.  
→ WordPress → Einstellungen → Medien: Upload-Ordner muss beschreibbar sein.

**Bedingte Logik funktioniert nicht**  
→ Feldnamen prüfen: Der interne Feldname (nicht Label) muss in der Bedingung verwendet werden.  
→ JavaScript-Fehler in der Browser-Konsole prüfen (F12).

---

*WP Multi Formular – entwickelt von M_Viper*  
*https://M-viper.de*