Helpers

Les helpers sont les fonctions JavaScript que vos templates appellent pour agir : envoyer une requête, ouvrir un aperçu, réagir à une réponse, envoyer un formulaire, afficher ou masquer la fenêtre. Vous les référencez depuis les événements HTML sous la forme skdwn.instance.helpers.<name>(...). Ils sont le pendant comportemental des templates Liquid : le template dessine le bouton, le helper est ce qui s’exécute au clic. Dans le navigateur de fichiers de l’éditeur avancé, ils se trouvent sous Template Helpers (settings.extensions.helpers).

Comment s’exécute un helper

Chaque helper est une simple fonction attachée à skdwn.instance.helpers. À l’intérieur, il accède à l’assistant en cours d’exécution via l’objet skdwn.instance et pilote l’interface en mettant à jour l’état ou en créant des résultats. Les méthodes sur lesquelles un helper s’appuie le plus :

Valeurs de type de résultat que vous créerez : WELCOME (accueil + suggestions), FORM (un formulaire de prospect) et ERROR (une bulle d’erreur). Lire et écrire le payload d’un résultat permet aux helpers de conserver un état propre à chaque réponse, comme une réaction.

Helpers intégrés

Voici chaque helper intégré, ce qu’il attend et comment il se comporte. Les signatures correspondent au code source ; lorsqu’un helper ne prend pas d’arguments, les parenthèses sont vides.

Cycle de vie d’une requête

sendQuery() : asynchrone, sans argument. Lit le texte actuel de #skdwn-search-input. S’il est vide, il ne fait rien. Sinon, il passe l’état à { query, isLoading: true }, fait défiler jusqu’en bas et envoie la requête en streaming au backend. La requête construite contient :

• userPrompt : le texte du champ.
• previousConversation : les tours précédents, uniquement lorsque

settings.usePreviousConversation est activé ; sinon une chaîne vide.

• additionalContext : ce que la page hôte a transmis dans startOptions.additionalContext.

En cas de succès, il vide le champ (query: ''), réinitialise la hauteur de la zone de texte et ferme tout onglet ouvert. En cas d’échec, il conserve le texte pour que l’utilisateur puisse réessayer, réinitialise isLoading, journalise l’erreur et ajoute un résultat ERROR.

onChangeQuery(event) : à brancher sur oninput de la zone de texte. Écrit la valeur du champ dans state.query et agrandit automatiquement la zone de texte. Lorsque le navigateur prend en charge le CSS field-sizing: content, l’agrandissement est natif ; ailleurs (par ex. Firefox), il ajuste la hauteur en JS.

onPressEnter(event) : à brancher sur onkeydown de la zone de texte. Entrée envoie (appelle sendQuery() et empêche le saut de ligne par défaut) ; Maj+Entrée insère un saut de ligne pour que le champ s’agrandisse en question sur plusieurs lignes.

stopQuery() : sans argument. Interrompt une requête en cours de streaming.

hintBoxClick(element) : passez l’élément cliqué via this. Lit la question suggérée dans son attribut data-hint, la place dans le champ de recherche, appelle sendQuery() et trace un événement HintBoxClick.

Conversation et réactions

showHints() : sans argument. Réaffiche l’accueil et les suggestions en créant un nouveau résultat WELCOME et trace ShowHints.

clearHistory() : sans argument. Efface les résultats stockés, vide state.results, crée un nouveau WELCOME et trace ClearHistory.

react(resultId, reactionType, element) : enregistre un pouce levé/baissé sur une réponse. resultId est l’id du résultat de la réponse ; reactionType vaut 'like' ou 'dislike' (element est accepté par symétrie mais inutilisé). La logique de bascule : cliquer de nouveau sur la même réaction ne fait rien ; cliquer sur la réaction opposée la réinitialise à neutral. Il trace un événement Reaction et réécrit payload.reaction sur le résultat.

Fenêtre modale d’aperçu

openPreview(event, element) : ouvre l’aperçu d’image ou de document. Lit data-previewsrc (le segment de chemin de la source) et data-title sur l’élément, construit ${serviceURL}/api/public/assistants/${previewsrc} (en ajoutant accesstoken comme paramètre de requête s’il est présent) et l’affiche dans la fenêtre modale via { modalOpen: true, modalContent, modalTitle }.

closePreview() : sans argument. Vide la fenêtre modale ({ modalOpen: false, modalContent: '' }).

Fenêtre et disposition

toggleMaximized() : sans argument. Bascule #skdwn-main-container entre ses tailles minimized et maximized et reflète ce changement dans state.skdwnWindowState.

toggleShowFloatingWindow(show) : show est un booléen. true masque le bouton flottant, affiche la fenêtre (en restaurant sa dernière taille, ou en forçant minimized lorsque le bouton d’action flottant est désactivé), donne le focus au champ de recherche et joue l’animation d’ouverture. false masque la fenêtre, la marque comme closed et fait réapparaître le bouton.

handleScroll() : sans argument. Fait défiler le conteneur de la conversation (#skdwn-floating-window-main) jusqu’en bas ; les helpers l’appellent après avoir ajouté du contenu pour que la réponse la plus récente soit visible.

Formulaires et proxys

showForm(formType) : formType est l’id du formulaire. Définit activeForm: true et crée un résultat FORM (avec un UUID généré) qui affiche ce formulaire.

sendForm(formType, event) : asynchrone, à brancher sur le onsubmit d’un formulaire. Empêche l’envoi par défaut, sérialise les champs du formulaire dans un payload, marque le résultat comme en cours d’envoi et appelle sendFormRequest(formType, payload). En cas de succès, le résultat est marqué submitted ; en cas d’échec, il ajoute un résultat ERROR ; dans tous les cas, il réinitialise activeForm.

sendProxyForm(proxyId, event, callback) : asynchrone, pour les formulaires qui appellent un endpoint proxy. Empêche l’envoi par défaut, sérialise les champs, active isLoading et appelle executeProxyRequest(proxyId, payload, callback). Si le proxy renvoie une réponse, elle est ajoutée comme résultat ; les erreurs deviennent un résultat ERROR.

Helpers de rendu

materialIcon(parameters) : renvoie du HTML sûr pour une icône Material. Contrairement aux helpers d’événement, celui-ci produit du balisage : vous l’utilisez donc comme filtre Liquid (voir Les helpers sont aussi des filtres). parameters accepte :

• iconName : le nom de ligature (par ex. search, close).
• size : la taille de police CSS (par défaut 16px).
• iconStyle : une variante d’icône comme outlined ou round (correspond à material-icons-<style>).

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

La valeur que vous transmettez par le pipe devient l’objet parameters : en pratique, vous l’appelez avec l’objet disponible dans le contexte. Sa sortie est déjà du HTML sûr : n’ajoutez pas | safe.

greet(parameters) : un petit helper d’exemple qui renvoie JSON.stringify(parameters). Il sert de point de départ quand vous ajoutez les vôtres : ouvrez-le, utilisez Test code pour transmettre du JSON d’exemple et observez l’aller-retour dans le panneau de débogage.

Appeler un helper

Liez les helpers aux événements DOM directement depuis le Liquid :

<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>

Transmettez des données à un helper via des attributs data-* et lisez-les sur l’élément avec this :

<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>

Pour une fiche de suggestion, placez la question dans data-hint et laissez hintBoxClick la récupérer :

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

Les helpers sont aussi des filtres

Chaque helper, intégré ou personnalisé, est enregistré deux fois :

1. Comme méthode de skdwn.instance.helpers.<name>, pour onclick/oninput/onsubmit.
2. Comme filtre Liquid du même nom, à utiliser dans {{ … }}.

Le choix dépend de ce que fait le helper. Les helpers d’événement (sendQuery, react, openPreview…) se placent sur les événements DOM. Les helpers qui renvoient une valeur, comme materialIcon qui renvoie du HTML, s’utilisent comme filtres, la valeur transmise par le pipe devenant le premier argument du helper :

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

C’est pourquoi un helper personnalisé ajouté pour la mise en forme peut être utilisé directement dans {{ }} sans aucun câblage supplémentaire.

Vos propres helpers

L’éditeur avancé vous permet d’ajouter des helpers personnalisés : du JavaScript stocké dans settings.extensions.helpers. Chaque entrée peut être une fonction unique ou un objet de fonctions ; Seekdown les évalue au démarrage et les fusionne dans skdwn.instance.helpers, de sorte que vous les appelez exactement comme les helpers intégrés. Si l’évaluation d’un helper échoue, il est ignoré (avec un avertissement dans la console) au lieu de casser le widget.

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

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

Dans un helper personnalisé, vous disposez de la même API d’instance que les helpers intégrés. Pour changer ce qui s’affiche à l’écran, appelez skdwn.instance.updateState({ ... }) ; pour ajouter un message, appelez skdwn.instance.createResult({ type: 'ERROR', payload: { reply: 'Something went wrong' } }) ; pour enregistrer un événement analytique, appelez skdwn.instance.sendTrace('MyEvent', { ... }).

Pour aller plus loin

• Utiliser l’éditeur avancé
• L’objet state