Benutzerdefinierte Variablen

Variablen ermöglichen es Ihrem Widget, Zustände zu speichern, die sich während der Benutzerinteraktion ändern. Verwenden Sie sie, um Pagination, Tab-Navigation, Datumsfilter und andere interaktive Muster zu erstellen -- ganz ohne Backend.

Was sind Variablen?

Variablen sind Schlüssel-Wert-Paare, die im Widget-Editor unter dem Variables-Tab definiert werden. Jede Variable hat:

• Name -- eine eindeutige Kennung (Zugriff in Kleinbuchstaben, z. B. my-var wird zu {{variables.my-var}})
• Typ -- bestimmt, wie der Wert gespeichert und geparst wird
• Standardwert -- der Anfangswert beim ersten Rendern des Widgets

Variablen werden pro Widget-Instanz gespeichert und beim Neuladen der Seite auf ihre Standardwerte zurückgesetzt.

Variablentypen

Typ	Beschreibung	Standard wenn leer
Text	Ein Zeichenkettenwert. Verwenden Sie ihn für Labels, Filterschlüssel, Tab-Namen usw.	"" (leere Zeichenkette)
Number	Ein numerischer Wert. Verwenden Sie ihn für Seitenindizes, Zähler, Offsets usw.	0
Date	Eine ISO-Datumszeichenkette. Funktioniert mit dem datetime Handlebars Helper zur Formatierung.	Aktuelles Datum/Uhrzeit

Variablen in Templates verwenden

Referenzieren Sie jede Variable in Ihrem Handlebars-Template mit der Syntax {{variables.<name>}}. Variablennamen werden immer in Kleinbuchstaben geschrieben.

<p>Current page: {{variables.page}}</p>
<p>Selected filter: {{variables.filter}}</p>
<p>Today: {{datetime variables.selected-date "DD.MM.YYYY"}}</p>

tipp

Wenn Ihr Variablenname Sonderzeichen enthält (wie Bindestriche), verwenden Sie die Klammernotation: {{variables.[my-variable]}}

Variablen in API-Anfragen verwenden

Sie können Variablen überall in Ihrer API-Anfragekonfiguration verwenden -- URL, Header oder Body:

https://api.example.com/items?page={{variables.page}}&filter={{variables.filter}}

In Kombination mit dem refetch-Parameter von setVariable() kann das Ändern einer Variable automatisch die Daten von der API mit dem aktualisierten Wert neu abrufen.

Die Funktion setVariable()

setVariable() ist eine globale JavaScript-Funktion, die der Widget Builder für jedes Widget in die Seite injiziert. Verwenden Sie sie in onclick-Handlern, um Variablenwerte zur Laufzeit zu aktualisieren.

Syntax

setVariable(name, value, refetch)

Parameter	Typ	Beschreibung
name	string	Der Variablenname (Groß-/Kleinschreibung wird nicht unterschieden).
value	string	Der neue Wert. Zahlen und Datumsangaben werden als Strings übergeben und basierend auf dem Variablentyp automatisch geparst.
refetch	boolean	Optional (Standard: false). Wenn true, ruft das Widget seine API-Daten erneut ab und rendert sich mit der aktualisierten Variable neu.

Beispiel

<button onclick="setVariable('page', '2')">Go to page 2</button>
<button onclick="setVariable('page', '1', true)">Go to page 1 (and reload data)</button>

Interaktive Muster

Pagination

Verwenden Sie eine Number-Variable, um die aktuelle Seite zu verfolgen und sie an Ihre API-Anfrage zu übergeben.

Variablen:

• page (Number, Standard: 0)

API-URL:

https://api.example.com/items?offset={{variables.page}}&limit=10

Template:

{{#each data.items}}
  <div>{{this.title}}</div>
{{/each}}

<button onclick="setVariable('page', {{variables.page}} - 1, true)">Previous</button>
<button onclick="setVariable('page', {{variables.page}} + 1, true)">Next</button>

Der Parameter true löst einen erneuten Datenabruf mit dem neuen Seitenwert aus.

Datumsnavigation

Verwenden Sie eine Date-Variable, um Benutzern das Durchblättern von Inhalten nach Datum zu ermöglichen -- beispielsweise ein Speiseplan oder Veranstaltungskalender.

Variablen:

• selected-date (Date, Standard: heute)

Template:

<h3>Menu for {{datetime variables.[selected-date] "dddd, DD MMMM"}}</h3>

{{#each data.meals}}
  <div>{{this.name}} -- {{this.description}}</div>
{{/each}}

<button onclick="setVariable('selected-date', '{{dateAdd variables.[selected-date] -1 "days"}}', true)">
  Previous day
</button>
<button onclick="setVariable('selected-date', '{{dateAdd variables.[selected-date] 1 "days"}}', true)">
  Next day
</button>

Tabs / Filter

Verwenden Sie eine Text-Variable, um zwischen Inhaltskategorien zu wechseln, ohne die Seite neu zu laden.

Variablen:

• tab (Text, Standard: all)

Template:

<div class="tabs">
  <button onclick="setVariable('tab', 'all')">All</button>
  <button onclick="setVariable('tab', 'news')">News</button>
  <button onclick="setVariable('tab', 'events')">Events</button>
</div>

{{#each data.items}}
  {{#if (or (eq ../variables.tab "all") (eq this.category ../variables.tab))}}
    <div>{{this.title}}</div>
  {{/if}}
{{/each}}

Wenn der Tab-Wert in der API-URL verwendet wird, fügen Sie true als dritten Parameter hinzu, um beim Tab-Wechsel die Daten neu abzurufen.

Best Practices

• Verwenden Sie aussagekräftige Namen -- page, selected-date, active-tab sind klarer als v1, d, t.
• Setzen Sie sinnvolle Standardwerte -- Eine Pagination-Variable sollte standardmäßig 0 oder 1 sein, eine Datumsvariable das heutige Datum.
• Verwenden Sie refetch nur bei Bedarf -- Setzen Sie den dritten Parameter nur auf true, wenn die API-Anfrage von der Variable abhängt. Für rein clientseitige Filterung oder Tab-Wechsel lassen Sie ihn weg, um unnötige API-Aufrufe zu vermeiden.
• Variablennamen werden kleingeschrieben -- MyVar und myvar verweisen auf dieselbe Variable. Verwenden Sie durchgehend Kleinbuchstaben, um Verwirrung zu vermeiden.