Widget Settings Felder

Widget Settings Felder ermöglichen es Staffbase-Administratoren, Ihr Custom Widget ohne Programmierung zu konfigurieren. Jedes Feld, das Sie definieren, erscheint im Staffbase Widget Settings Panel, wenn ein Administrator Ihr Widget zu einer Seite hinzufügt.

Feldwerte sind in Ihrem Handlebars-Layout-Template über {{settings.propName}} zugänglich.

Gemeinsame Eigenschaften

Jeder Feldtyp teilt die folgenden Konfigurationsoptionen:

Eigenschaft	Typ	Erforderlich	Beschreibung
Label	string	Ja	Anzeigename, der dem Administrator im Settings Panel angezeigt wird.
Property Name	string	Ja	Interner Bezeichner, der in Templates verwendet wird. Darf nur Buchstaben, Zahlen, Bindestriche und Unterstriche enthalten (A-Za-z0-9-_). Wird beim Erstellen eines neuen Feldes automatisch aus dem Label generiert.
Required	boolean	Nein	Ob der Administrator einen Wert angeben muss. Standard ist false.

Namenskonvention

Verwenden Sie aussagekräftige Property Names in camelCase oder snake_case. Der Property Name wird automatisch aus dem Label generiert (Leerzeichen werden zu Unterstrichen, Sonderzeichen werden entfernt, deutsche Umlaute werden transliteriert). Sie können ihn jederzeit manuell bearbeiten.

Feldtypen

Text

Ein einzeiliges Texteingabefeld für kurze Zeichenkettenwerte.

Eigenschaft	Details
Feldkennung	text
Datentyp	string
Standardwert	Optional. Beliebiger String. Fällt auf leeren String "" zurück.

Template-Verwendung:

<h2>{{settings.headline}}</h2>
<a href="{{settings.link_url}}">Read more</a>

Ideal für: Titel, URLs, kurze Labels, einzeilige Inhalte.

---

Number

Ein numerisches Eingabefeld, das nur Zahlenwerte akzeptiert.

Eigenschaft	Details
Feldkennung	number
Datentyp	number
Standardwert	Optional. Beliebige Zahl. Fällt auf 0 zurück.

Template-Verwendung:

<div style="padding: {{settings.spacing}}px;">
  Showing {{settings.item_count}} items
</div>

Ideal für: Anzahlen, Größen, Abstandswerte, numerische Schwellenwerte.

---

Textarea

Ein mehrzeiliges Texteingabefeld für längere Inhalte.

Eigenschaft	Details
Feldkennung	textarea
Datentyp	string
Standardwert	Optional. Beliebiger String (unterstützt Zeilenumbrüche). Fällt auf leeren String "" zurück.

Template-Verwendung:

<p>{{settings.description}}</p>

Ideal für: Beschreibungen, Absätze, HTML-Snippets, CSS-Überschreibungen, JSON-Konfiguration.

---

Checkbox

Ein boolescher Schalter (wird als True/False-Dropdown im Settings Panel dargestellt).

Eigenschaft	Details
Feldkennung	checkbox
Datentyp	boolean
Standardwert	true oder false. Fällt auf false zurück.

Template-Verwendung:

{{#if settings.show_header}}
  <header>Welcome!</header>
{{/if}}

Ideal für: Feature-Toggles, Ein-/Ausblenden-Flags, An/Aus-Schalter.

---

Dropdown

Ein Einzelauswahl-Dropdown-Menü mit vordefinierten Optionen.

Eigenschaft	Details
Feldkennung	dropdown
Datentyp	string
Standardwert	Optional. Muss eine der definierten Optionen sein. Fällt auf die erste Option zurück.
Optionen	Erforderlich. Eine Liste von Werten, einer pro Zeile. Doppelte Werte werden automatisch entfernt.

Template-Verwendung:

<div class="theme-{{settings.color_theme}}">
  {{#if (eq settings.layout "grid")}}
    <!-- grid layout -->
  {{else}}
    <!-- list layout -->
  {{/if}}
</div>

Ideal für: Theme-Auswahl, Layout-Modi, vordefinierte Kategorien, jedes Szenario mit "Wähle eines aus einer Liste".

Optionen hinzufügen

Beim Konfigurieren eines Dropdown-Feldes geben Sie jede Option in einer separaten Zeile im Optionen-Textbereich ein. Die erste Option wird zum Standard, wenn kein expliziter Standardwert gesetzt ist.

---

Radio

Eine Radio-Button-Gruppe mit vordefinierten Optionen. Funktional identisch mit Dropdown, wird aber als Radio-Buttons im Staffbase Settings Panel dargestellt.

Eigenschaft	Details
Feldkennung	radio
Datentyp	string
Standardwert	Optional. Muss eine der definierten Optionen sein. Fällt auf die erste Option zurück.
Optionen	Erforderlich. Eine Liste von Werten, einer pro Zeile. Doppelte Werte werden automatisch entfernt.

Template-Verwendung:

<div class="align-{{settings.text_alignment}}">
  {{settings.content}}
</div>

Ideal für: Kleine Optionsmengen (2-4 Auswahlmöglichkeiten), bei denen alle Optionen gleichzeitig sichtbar sein sollen.

Felder in Templates verwenden

Alle Feldwerte sind unter dem settings-Objekt in Ihren Handlebars-Templates verfügbar:

<!-- Direkte Wertausgabe -->
<h1>{{settings.title}}</h1>

<!-- Bedingte Darstellung mit Checkbox -->
{{#if settings.show_footer}}
  <footer>{{settings.footer_text}}</footer>
{{/if}}

<!-- Verwendung in Attributen -->
<div style="background-color: {{settings.bg_color}}; padding: {{settings.padding}}px;">
  {{settings.content}}
</div>

<!-- Verwendung in API Proxy URLs -->
<!-- Siehe den API Proxy-Leitfaden für Details -->

Felddefinitions-Format

Intern wird jedes Feld als JSON-Objekt gespeichert. Dies ist die Struktur, die Sie sehen, wenn Sie Widget-Konfigurationen inspizieren oder importieren/exportieren:

[
  {
    "field": "text",
    "title": "Headline",
    "propName": "headline",
    "required": true,
    "default": "Welcome"
  },
  {
    "field": "dropdown",
    "title": "Theme",
    "propName": "color_theme",
    "required": false,
    "default": "light",
    "values": ["light", "dark", "blue"]
  },
  {
    "field": "checkbox",
    "title": "Show Header",
    "propName": "show_header",
    "required": false,
    "default": true
  }
]

Best Practices

• Verwenden Sie klare Labels -- Das Label ist das, was Staffbase-Administratoren sehen. Machen Sie es aussagekräftig genug, damit der Zweck ohne zusätzlichen Kontext offensichtlich ist.
• Setzen Sie sinnvolle Standardwerte -- Geben Sie immer einen Standardwert an, damit das Widget auch ohne Konfiguration gut aussieht.
• Wählen Sie aussagekräftige Property Names -- Property Names erscheinen in Ihrem Template-Code. Verwenden Sie Namen, die das Template lesbar machen (z. B. show_header anstelle von flag1).
• Bevorzugen Sie Dropdown gegenüber Radio bei langen Listen -- Radio-Buttons eignen sich am besten für 2-4 Optionen. Für längere Listen verwenden Sie ein Dropdown.
• Verwenden Sie Checkbox für boolesche Logik -- Wenn eine Einstellung An/Aus ist, verwenden Sie Checkbox anstelle eines Dropdowns mit "Yes"/"No"-Optionen.
• Halten Sie Property Names stabil -- Das Ändern eines Property Names nach der Veröffentlichung des Widgets wird bestehende Widget-Instanzen beschädigen, die auf den alten Namen verweisen.