Helper

Helper sind die JavaScript-Funktionen, die Ihre Templates aufrufen, um etwas zu tun – eine Anfrage senden, eine Vorschau öffnen, auf eine Antwort reagieren, ein Formular absenden, das Fenster ein- oder ausblenden. Sie referenzieren sie aus HTML-Events als skdwn.instance.helpers.<name>(...). Sie sind das Verhaltensgegenstück zu den Liquid-Templates: Das Template zeichnet den Button, der Helper ist das, was beim Klick ausgeführt wird. Im Dateibrowser des Advanced editor finden Sie sie unter Template Helpers (settings.extensions.helpers).

Wie ein Helper ausgeführt wird

Jeder Helper ist eine einfache Funktion, die an skdwn.instance.helpers hängt. Darin erreicht er den laufenden Assistenten über das Objekt skdwn.instance und steuert die Oberfläche, indem er den State aktualisiert oder Ergebnisse erzeugt. Die Methoden, auf die sich ein Helper am häufigsten stützt:

Ergebnis-type-Werte, die Sie erzeugen: WELCOME (Begrüßung + Vorschläge), FORM (ein Lead-Formular) und ERROR (eine Fehlermeldung). Über das Lesen und Schreiben der payload eines Ergebnisses speichern Helper Zustand pro Antwort, etwa eine Reaktion.

Integrierte Helper

Nachfolgend jeder integrierte Helper, was er erwartet und wie er sich verhält. Die Signaturen entsprechen dem Quellcode; nimmt ein Helper keine Argumente entgegen, sind die Klammern leer.

Lebenszyklus einer Anfrage

sendQuery() – async, keine Argumente. Liest den aktuellen Text aus #skdwn-search-input. Ist er leer, passiert nichts. Andernfalls setzt er den State auf { query, isLoading: true }, scrollt nach unten und streamt die Anfrage an das Backend. Die erzeugte Anfrage enthält:

• userPrompt – den Text aus dem Feld.
• previousConversation – die vorherigen Gesprächsrunden, nur wenn

settings.usePreviousConversation aktiviert ist; andernfalls einen leeren String.

• additionalContext – was auch immer die Host-Seite in startOptions.additionalContext übergeben hat.

Bei Erfolg leert er das Feld (query: ''), setzt die Höhe der Textarea zurück und schließt einen eventuell geöffneten Tab. Bei einem Fehler behält er den Text, damit der Nutzer es erneut versuchen kann, setzt isLoading zurück, protokolliert den Fehler und fügt ein ERROR-Ergebnis hinzu.

onChangeQuery(event) – an oninput der Textarea binden. Schreibt den Feldwert in state.query und vergrößert die Textarea automatisch. Wo der Browser CSS field-sizing: content unterstützt, geschieht das Wachstum nativ; andernfalls (z. B. Firefox) wird die Höhe per JS angepasst.

onPressEnter(event) – an onkeydown der Textarea binden. Enter sendet ab (ruft sendQuery() auf und verhindert den Standard-Zeilenumbruch); Shift+Enter fügt einen Zeilenumbruch ein, sodass das Feld für eine mehrzeilige Frage wächst.

stopQuery() – keine Argumente. Bricht eine gerade gestreamte Anfrage ab.

hintBoxClick(element) – übergeben Sie das angeklickte Element als this. Liest die vorgeschlagene Frage aus dessen data-hint-Attribut, setzt sie ins Suchfeld, ruft sendQuery() auf und zeichnet ein HintBoxClick-Event auf.

Unterhaltung und Reaktionen

showHints() – keine Argumente. Zeigt Begrüßung/Vorschläge erneut an, indem ein neues WELCOME-Ergebnis erzeugt wird, und zeichnet ShowHints auf.

clearHistory() – keine Argumente. Löscht gespeicherte Ergebnisse, leert state.results, erzeugt ein neues WELCOME und zeichnet ClearHistory auf.

react(resultId, reactionType, element) – zeichnet einen Daumen hoch/runter für eine Antwort auf. resultId ist die ID des Antwort-Ergebnisses; reactionType ist 'like' oder 'dislike' (element wird der Symmetrie halber akzeptiert, aber nicht verwendet). Die Umschaltlogik: Ein erneuter Klick auf dieselbe Reaktion bewirkt nichts; ein Klick auf die entgegengesetzte setzt sie auf neutral zurück. Der Helper zeichnet ein Reaction-Event auf und schreibt payload.reaction zurück in das Ergebnis.

Vorschau-Modal

openPreview(event, element) – öffnet die Bild-/Dokumentvorschau. Liest data-previewsrc (das Pfadsegment der Quelle) und data-title vom Element, baut ${serviceURL}/api/public/assistants/${previewsrc} – mit angehängtem accesstoken als Query-Parameter, sofern vorhanden – und zeigt es im Modal über { modalOpen: true, modalContent, modalTitle } an.

closePreview() – keine Argumente. Leert das Modal ({ modalOpen: false, modalContent: '' }).

Fenster und Layout

toggleMaximized() – keine Argumente. Schaltet #skdwn-main-container zwischen den Größen minimized und maximized um und spiegelt dies in state.skdwnWindowState.

toggleShowFloatingWindow(show) – show ist ein Boolean. true blendet den schwebenden Button aus, zeigt das Fenster (stellt seine letzte Größe wieder her oder erzwingt minimized, wenn der Floating Action Button deaktiviert ist), fokussiert das Suchfeld und spielt die Öffnungsanimation ab. false blendet das Fenster aus, markiert es als closed und bringt den Button zurück.

handleScroll() – keine Argumente. Scrollt den Container der Unterhaltung (#skdwn-floating-window-main) nach unten; Helper rufen ihn nach dem Hinzufügen von Inhalten auf, damit die neueste Antwort sichtbar ist.

Formulare und Proxys

showForm(formType) – formType ist die ID des Formulars. Setzt activeForm: true und erzeugt ein FORM-Ergebnis (mit generierter UUID), das dieses Formular rendert.

sendForm(formType, event) – async, an das onsubmit eines Formulars binden. Verhindert das Standard-Absenden, serialisiert die Formularfelder in eine Payload, markiert das Ergebnis als „wird gesendet“ und ruft sendFormRequest(formType, payload) auf. Bei Erfolg wird das Ergebnis als submitted gekennzeichnet; bei einem Fehler wird ein ERROR-Ergebnis hinzugefügt; in beiden Fällen wird activeForm zurückgesetzt.

sendProxyForm(proxyId, event, callback) – async, für Formulare, die einen Proxy-Endpunkt aufrufen. Verhindert das Standard-Absenden, serialisiert die Felder, setzt isLoading und ruft executeProxyRequest(proxyId, payload, callback) auf. Liefert der Proxy eine Antwort, wird sie als Ergebnis angehängt; Fehler werden zu einem ERROR-Ergebnis.

Render-Helper

materialIcon(parameters) – gibt sicheres HTML für ein Material-Icon zurück. Anders als die Event-Helper erzeugt dieser Markup, daher verwenden Sie ihn als Liquid-Filter (siehe Helper sind auch Filter). parameters akzeptiert:

• iconName – den Ligaturnamen (z. B. search, close).
• size – CSS-Schriftgröße (Standard 16px).
• iconStyle – eine Icon-Variante wie outlined oder round (wird auf material-icons-<style> abgebildet).

{% assign icon = "" | buildIconParams %}   {# or pass an object you already have in scope #}
{{ icon | materialIcon }}

Der Wert, den Sie hineinleiten, wird zum parameters-Objekt; in der Praxis rufen Sie ihn also mit dem Objekt auf, das gerade verfügbar ist. Seine Ausgabe ist bereits sicheres HTML – fügen Sie kein | safe hinzu.

greet(parameters) – ein winziger Beispiel-Helper, der JSON.stringify(parameters) zurückgibt. Er dient als Ausgangspunkt, wenn Sie eigene hinzufügen – öffnen Sie ihn, übergeben Sie mit Test code Beispiel-JSON und sehen Sie den Durchlauf im Debug-Bereich.

Einen Helper aufrufen

Binden Sie Helper direkt aus dem Liquid an DOM-Events:

<textarea id="skdwn-search-input"
          oninput="skdwn.instance.helpers.onChangeQuery(event)"
          onkeydown="skdwn.instance.helpers.onPressEnter(event)"></textarea>

<button onclick="skdwn.instance.helpers.sendQuery()">
  {{ 'ask' | t: 'Ask' }}
</button>

Übergeben Sie Daten an einen Helper über data-*-Attribute und lesen Sie sie mit this vom Element:

<a href="#" onclick="skdwn.instance.helpers.openPreview(event, this)"
   data-title="{{ reference.title }}"
   data-previewSrc="{{ state.instance.config.key }}/tools/preview/{{ reference.id }}/{{ refPage }}">
  Preview
</a>

Bei einer Vorschlagskarte legen Sie die Frage in data-hint ab und lassen hintBoxClick sie übernehmen:

<button data-hint="{{ hint.text | sanitize }}"
        onclick="skdwn.instance.helpers.hintBoxClick(this)">
  {{ hint.text }}
</button>

Helper sind auch Filter

Jeder Helper – integriert und eigener – wird zweimal registriert:

1. Als Methode unter skdwn.instance.helpers.<name>, für onclick/oninput/onsubmit.
2. Als Liquid-Filter gleichen Namens, zur Verwendung innerhalb von {{ … }}.

Welche Variante Sie nutzen, hängt davon ab, was der Helper tut. Event-Helper (sendQuery, react, openPreview, …) gehören an DOM-Events. Helper, die einen Wert zurückgeben – wie materialIcon, das HTML zurückgibt –, werden als Filter verwendet, wobei der hineingeleitete Wert zum ersten Argument des Helpers wird:

{{ someValue | myFormatter }}   {# equivalent to myFormatter(someValue) #}

Deshalb lässt sich ein eigener Helper zur Formatierung ohne zusätzliche Verdrahtung direkt in {{ }} verwenden.

Ihre eigenen Helper

Im Advanced editor können Sie eigene Helper hinzufügen – JavaScript, das in settings.extensions.helpers gespeichert wird. Jeder Eintrag kann eine einzelne Funktion oder ein Objekt mit Funktionen sein; Seekdown wertet sie beim Start aus und führt sie in skdwn.instance.helpers zusammen, sodass Sie sie genau wie die integrierten aufrufen. Lässt sich ein Helper nicht auswerten, wird er übersprungen (mit einer Warnung in der Konsole), statt das Widget lahmzulegen.

// A helper named "trackClick"
(ref) => { window.analytics?.track('reference_click', { id: ref }); }

<a onclick="skdwn.instance.helpers.trackClick('{{ reference.id }}')">{{ reference.title }}</a>

In einem eigenen Helper steht Ihnen dieselbe Instanz-API zur Verfügung wie den integrierten. Um zu ändern, was angezeigt wird, rufen Sie skdwn.instance.updateState({ ... }) auf; um eine Nachricht hinzuzufügen, skdwn.instance.createResult({ type: 'ERROR', payload: { reply: 'Something went wrong' } }); um ein Analytics-Event aufzuzeichnen, skdwn.instance.sendTrace('MyEvent', { ... }).

Weiterführend

• Den Advanced editor verwenden
• Das State-Objekt