# Klubboard Formularfelder – Word-Add-in Task-Pane-Add-in für Word, das die `[wpformsfield ...]`-Shortcodes für die Klubboard-Wordvorlagen zusammenstellt, an der Cursorposition einfügt und das Dokument gegen die Eigenheiten des DOCX-Importers prüft. Gegenstück auf der WordPress-Seite: | Was | Wo | |---|---| | Katalog-Endpunkt | `klubboard-stammdaten/thirdparty/wpforms/word-addin-api.php` | | DOCX-Import | `klubboard-stammdaten/thirdparty/wpforms/word-importer-and-pdf-generator.php` | | Ausfüllen des DOCX | `klubboard-stammdaten/thirdparty/wpforms/KBTemplateProcessor.php` | ## Wozu das Ganze Drei Dinge gehen beim Schreiben der Shortcodes von Hand regelmäßig schief, und alle drei fängt das Add-in ab: 1. **Word ersetzt gerade Anführungszeichen durch typografische.** Die Ersetzung im fertigen DOCX matcht aber hart auf `id="N"` – nach der Autokorrektur bleibt der Shortcode als sichtbarer Text im PDF stehen. Programmatisch eingefügter Text löst keine Autokorrektur aus, deshalb sind Shortcodes aus dem Add-in immer sauber. Für bereits vorhandene gibt es im Reiter „Prüfen“ die Reparaturfunktion. 2. **Die Feld-Nummern müssen lückenlos von 1 aufwärts laufen**, sonst bricht der Import komplett ab. Das Add-in schlägt die nächste freie Nummer vor und kann das ganze Dokument neu durchnummerieren. 3. **`default_value` und `acf_user_profile_field_name` erwarten unterschiedliche Dinge** und es gibt keine Liste der gültigen Werte. Beide bekommen im Add-in eine durchsuchbare Auswahl, die der Endpunkt aus den echten ACF-Feldgruppen und den registrierten WPForms-Smart-Tags erzeugt. ## Deployment Der Inhalt dieses Ordners wird 1:1 nach `https://addin.kbapiserver.de/` kopiert. Kein Build-Step, kein npm – reine ES-Module. ``` manifest.xml -> https://addin.kbapiserver.de/manifest.xml taskpane.html -> https://addin.kbapiserver.de/taskpane.html taskpane.css js/*.js assets/icon-*.png test/ nur für die Entwicklung, kann beim Kopieren wegbleiben ``` Bedingungen auf dem Webserver: - **HTTPS mit gültigem Zertifikat.** Office lädt Task-Panes ausschließlich über HTTPS. - Korrekte MIME-Types. `.js` muss als `text/javascript` bzw. `application/javascript` ausgeliefert werden, sonst verweigert der Browser die ES-Module. ### Freischaltung auf der Klubboard-Seite Der Katalog-Endpunkt gibt CORS-Header nur für bekannte Origins aus. Standardmäßig ist `https://addin.kbapiserver.de` eingetragen. Weitere Adressen (z. B. für lokale Entwicklung) über den Filter: ```php add_filter('kb_wordaddin_allowed_origins', function ($origins) { $origins[] = 'https://localhost:3000'; return $origins; }); ``` ## Installation in Word Das Add-in wird über sein Manifest installiert, nicht über den Store. **Einzelner Rechner (zum Ausprobieren):** 1. `manifest.xml` lokal speichern. 2. In Word: *Einfügen → Add-Ins → Meine Add-Ins → Mein Add-In hochladen*. 3. Die `manifest.xml` auswählen. **Für mehrere Leute:** Netzwerkfreigabe als vertrauenswürdigen Katalog eintragen (*Datei → Optionen → Trust Center → Einstellungen für das Trust Center → Kataloge vertrauenswürdiger Add-Ins*), `manifest.xml` in die Freigabe legen, Word neu starten. Alternativ zentral über das Microsoft-365-Admin-Center ausrollen. Nach der Installation liegt im Reiter *Start* die Gruppe **Klubboard** mit dem Knopf **Formularfelder**. **Voraussetzung:** Word aus Microsoft 365 oder Word 2021+ (WebView2). Ältere Versionen mit dem Internet-Explorer-Unterbau können die ES-Module nicht laden. ## Bedienung ### Erstellen Feldtyp wählen, Attribute ausfüllen, `An Cursorposition einfügen`. Die Vorschau zeigt jederzeit den Shortcode, der tatsächlich eingefügt wird. Leere Attribute fallen dabei weg – der Importer setzt seine Standardwerte ohnehin selbst. Steht der Cursor in einem vorhandenen Shortcode, erscheint oben *Shortcode an der Cursorposition bearbeiten*: die Attribute werden ins Formular geladen und beim Speichern an Ort und Stelle ersetzt, samt Formatierung. Zwei Felder haben eine durchsuchbare Auswahl: - **Vorbelegung** (`default_value`) – alle bekannten Platzhalter. Freitext bleibt erlaubt, weil `{acf_…}` im Kern auf `get_user_meta()` aufläuft und damit jeder Meta-Key funktioniert. Der Validator warnt dann nur. - **ACF-Feld für Datenübernahme** (`acf_user_profile_field_name`) – die Profilfelder, in die nach dem Absenden zurückgeschrieben werden kann. Diese Liste kommt aus derselben Funktion, die auch das Schreiben erledigt, kann also nichts anbieten, was hinterher nicht ankommt. ### Prüfen `Dokument prüfen` listet alle Befunde, jeder mit Sprung an die Fundstelle: | Befund | Warum es zählt | |---|---| | Typografische Anführungszeichen | Shortcode bleibt im fertigen PDF stehen | | Lücke, Dublette oder fehlende ID | Import bricht ab | | Nicht unterstützter Feldtyp | Feld wird beim Import kommentarlos übersprungen | | Shortcode über Absatzgrenze zerrissen | Wird beim Import nicht erkannt | | Unbekannter Platzhalter | Löst zu einem leeren Wert auf | | Platzhalter braucht einen Eintrag | Als Vorbelegung immer leer | | Unbekanntes ACF-Ziel | Eingabe landet nirgends | | Unbekanntes Attribut | Wird von WPForms ignoriert | | Mehr als eine Auswahlmöglichkeit | Siehe unten | Dazu zwei Reparaturen: *Alle Felder neu nummerieren* und *Anführungszeichen begradigen*. Beide fassen nur die Shortcodes an, der übrige Text bleibt unberührt. ### Einstellungen Die Klubboard-Adresse (Standard `https://vwk.klubboard.com`) und der Katalog. Der Katalog wird 12 Stunden lang zwischengespeichert; ist der Server nicht erreichbar, arbeitet das Add-in mit dem letzten bekannten Stand weiter und weist darauf hin. ## Bekannte Einschränkung: mehrere Auswahlmöglichkeiten Der Export (`[wpforms_field_export]`) verkettet mehrere Auswahlen mit `|`, der Import (`kb_docsforms_parse_choices`) trennt sie an Zeilenumbrüchen – und Zeilenumbrüche innerhalb eines Attributs überleben den Weg Word → PHPWord → HTML → `strip_tags()` nicht. Ein Feld mit mehreren Auswahlen kommt daher nicht zuverlässig durch den Import. Das Add-in schreibt die vom Parser erwartete zeilengetrennte Form und warnt, wenn mehr als eine Auswahl im Spiel ist. In der Praxis hat jedes Checkbox-Feld in den bestehenden Vorlagen genau eine Auswahl. Wer mehrere Optionen braucht, legt besser mehrere Felder an. ## Entwicklung Lokal braucht auch das Task-Pane HTTPS: ```bash npx office-addin-dev-certs install # beliebiger Static-Server auf https://localhost:3000, dann im manifest.xml # alle addin.kbapiserver.de-URLs darauf umbiegen ``` Die Klubboard-Seite kann dabei die lokale Installation sein – Local liefert für `https://klubboard.local` ein Zertifikat, dem WebView2 vertraut. Die Origin-Freischaltung nicht vergessen (siehe oben). Die reine Logik (Shortcodes bauen/parsen, Validierung) hängt nicht an Office.js und lässt sich direkt testen: ```bash node test/shortcode.test.mjs ``` Der Test läuft gegen die echten Beispiel-Shortcodes aus den bestehenden Vorlagen.