Felder¶

FieldBuilder¶

Der FieldBuilder steuert die Eingabefelder in Meta-Boxen, Optionen und Taxonomien. Er arbeitet mit Tabs und Felddefinitionen.

Datei: includes/engine/FieldBuilder.php

Aufbau: Felder werden in Tabs organisiert. Jeder Tab hat id, title und fields. Der Tab-id ist später der Meta-Key in der Datenbank.

Feldtypen¶

Der FieldBuilder unterstützt einfache, komplexe und Layout-Feldtypen. Die wichtigsten Typen:

Typ	Beschreibung	Hinweis
`text`	Einzeiliger Text.	Standardtyp, wenn nichts angegeben ist.
`number`	Numerische Eingabe.	Für Preise, Zähler, Sortierung.
`email`	E-Mail-Adresse.	Browservalidierung.
`date`	Datumseingabe.	HTML5-Datepicker.
`hidden`	Verstecktes Feld.	Wert wird gespeichert, nicht sichtbar.
`textarea`	Mehrzeiliger Text.	Für Beschreibungen oder Notizen.
`secret`	Geheimer Wert.	Wird als Platzhalter gespeichert.
`select`	Auswahlliste.	Optionen als Array definieren.
`radio`	Einzelauswahl.	Optionen mit `checked` möglich.
`checkbox`	Boolesche Auswahl.	Speichert true/false.
`image`	Bildauswahl aus Mediathek.	Einzelbild.
`gallery`	Mehrere Bilder.	Speichert IDs als Liste.
`media`	Dateiauswahl aus Mediathek.	Auch für PDFs oder Audio.
`editor`	WordPress-Editor.	Mit TinyMCE und Media Buttons.
`code`	Code-Editor (z. B. HTML/CSS/JS).	CodeMirror mit Mode-Optionen.
`color`	Farbpicker.	WordPress Color Picker.
`button`	Button im Formular.	Für Aktionen in Meta-Boxen.
`nonce`	Sicherheits-Nonce.	Wird als Hidden Field erzeugt.
`html`	Freies HTML.	Über Filter erweiterbar.
`repeater`	Wiederholbare Feldergruppen.	Für Listen, Fakten, Module.
`group`	Gruppierte Unterfelder.	Für logisch zusammenhängende Felder.
`sortable`	Sortierbare Gruppen.	Wie Repeater, aber sortierbar.
`columns`	Layout-Spalten.	Unterfelder in Spalten.
`headline`	Überschrift im Formular.	Nur Anzeige.
`description`	Hinweistext (Info-Box).	Nur Anzeige.
`warning`	Warnhinweis.	Nur Anzeige.
`icon`	Icon-Auswahl (SVG).	Öffnet den Icon-Dialog im Backend.
`qrcode`	QR-Code Feld (Engine Add-on).	Wird über `twtheme_custom_field_input` gerendert.

Hinweis: Felder vom Typ description werden als Info-Box angezeigt.

Feld-Optionen¶

Diese Optionen funktionieren bei vielen Feldtypen:

Option	Beschreibung
`id`	Pflicht. Eindeutiger Key im Tab.
`name`	Pflicht. Wird für das Speichern genutzt.
`label`	Label im Backend.
`description`	Hilfetext unter dem Feld.
`value`	Standardwert.
`required`	Pflichtfeld.
`readonly`	Nur lesen.
`disabled`	Deaktiviert.
`editable`	Zusatzbutton zum Entsperren.
`multiple`	Mehrfachauswahl (z. B. Select).
`placeholder`	Platzhaltertext.
`pattern`	Validierungs-Pattern.
`title`	Titel/Tooltip.
`class`	Zusätzliche CSS-Klassen.
`style`	Inline-Styles.
`validate`	Validierungs-Flag (data-validation).
`col_class`	Bootstrap-Spalte, z. B. `col-6`.
`label_class`	Klasse für das Label.
`options`	Optionen für Select/Radio.
`options_from_data`	Optionen aus Datenquelle.
`data-filter`	Filter wie `htmlentities`, `esc_url`.
`json`	Zusätzliche JSON-Daten.
`data-set`	Beliebige `data-*`-Attribute.
`value_reset`	Preset für „Wert zurücksetzen“.
`integration`	Integration-Tooling (z. B. Maps).

Integration¶

Felder können Integrationen nutzen, um Daten zu übernehmen oder Hilfsfunktionen zu aktivieren.

Option	Beschreibung
`integration.tool`	Aktiviert ein Tool, z. B. `gmaps` für Kartenfelder.
`integration.service`	Dienstfunktion, z. B. `geocoding` oder `polygon`.
`integration.source`	Quelle für automatische Werte. Unterstützt `the_title` und `the_permalink`.

Wenn integration.tool = gmaps gesetzt ist und ein API-Key vorhanden ist, wird die Google-Maps-API automatisch eingebunden. Bei service = geocoding oder polygon erscheint ein Vorschau-Button.

Google Maps¶

Google Maps Beispiel (inkl. Koordinaten + Vorschau):

Feld adresse liefert die Quelle (the_title oder manuelle Adresse).
Feld koordinaten speichert „Lat, Lng“ und zeigt die Vorschau.

[
  'type' => 'text',
  'id' => 'adresse',
  'name' => 'adresse',
  'label' => 'Adresse',
  'placeholder' => 'Musterstraße 1, 12345 Musterstadt',
],
[
  'type' => 'text',
  'id' => 'koordinaten',
  'name' => 'koordinaten',
  'label' => 'Koordinaten',
  'placeholder' => '52.520008, 13.404954',
  'integration' => [
    'tool' => 'gmaps',
    'service' => 'geocoding',
    'source' => 'adresse'
  ],
]

Beim Ändern der Adresse wird automatisch geocodiert. Über den Vorschau-Button wird die Karte angezeigt.

Zusätzlich lädt die Engine in der Admin-UI automatisch tom-select für erweiterte Auswahlfelder.

Tom Select¶

Tom Select wird in der Admin-UI automatisch geladen und beim Page-Load initialisiert. Du musst nur die passende Klasse und optional JSON-Optionen setzen.

Feld definieren: select mit Klasse tom.
Optionen steuern: Über data-json (für Tom-Select-Settings).

[
  'type' => 'select',
  'id' => 'category',
  'name' => 'category',
  'label' => 'Kategorie',
  'class' => 'tom',
  'options' => [
    ['value' => 'a', 'label' => 'A'],
    ['value' => 'b', 'label' => 'B'],
  ],
  'multiple' => true,
  'json' => [
    'allowEmptyOption' => true,
    'maxItems' => null
  ],
]

Wichtig: Die Engine initialisiert Tom Select für select.tom automatisch (siehe includes/engine/assets/twtheme-admin.js).

Es gibt zwei Sonderfälle, die per CSS-Klasse bzw. JSON-Option ausgelöst werden:

Variante	Wie aktivieren?	Beschreibung
Dynamisch	Klasse `dynamic` plus `tom`	Ajax-Suche nach Posts über `twtheme_get_posts_by_type`.
Custom Ajax	`data-json` mit `action`	Ajax-Suche über eigene WP-Ajax-Action.

// Dynamic Posts
[
  'type' => 'select',
  'id' => 'related',
  'name' => 'related',
  'label' => 'Beiträge',
  'class' => 'tom dynamic',
  'title' => 'post', // post type für die Suche
  'multiple' => true,
]

// Custom Ajax Action
[
  'type' => 'select',
  'id' => 'custom',
  'name' => 'custom',
  'label' => 'Custom',
  'class' => 'tom',
  'json' => [
    'action' => 'mein_ajax_hook'
  ],
]

QR-Code-Feld¶

Das QR-Code-Feld ergänzt den FieldBuilder um den Feldtyp qrcode. Die Darstellung erfolgt über twtheme_custom_field_input, die Generierung via Ajax.

Dateien: includes/engine/add-ons/qrcode/qrcode.php, includes/engine/add-ons/qrcode/fields.php
Ajax: twtheme_generate_qrcode
Assets: includes/engine/add-ons/qrcode/assets/twtheme-qrcode.js

Felddefinition mit Integration-Quelle:

[
  'type' => 'qrcode',
  'id' => 'qr_code',
  'name' => 'qr_code',
  'label' => 'QR-Code',
  'integration' => [
    'source' => 'the_permalink',
    'type' => 'url'
  ],
]

Im Backend gibt es Buttons zum Generieren und Download. Das Feld speichert die Attachment-ID des QR-Codes.