Helper

Gli helper sono le funzioni JavaScript che i tuoi template richiamano per fare qualcosa: inviare una domanda, aprire un’anteprima, reagire a una risposta, inviare un modulo, mostrare o nascondere la finestra. Li richiami dagli eventi HTML come skdwn.instance.helpers.<name>(...). Sono il complemento comportamentale dei template Liquid: il template disegna il pulsante, l’helper è ciò che viene eseguito quando lo si clicca. Nel browser dei file dell’Advanced editor si trovano sotto Template Helpers (settings.extensions.helpers).

Come viene eseguito un helper

Ogni helper è una semplice funzione associata a skdwn.instance.helpers. Al suo interno raggiunge l’assistente in esecuzione tramite l’oggetto skdwn.instance e guida l’interfaccia aggiornando lo state o creando risultati. I metodi su cui un helper si appoggia di più:

I valori di type dei risultati che creerai: WELCOME (saluto + suggerimenti), FORM (un modulo contatti) ed ERROR (un fumetto di errore). Leggere e scrivere il payload di un risultato è il modo in cui gli helper conservano lo stato di ogni risposta, come una reazione.

Helper integrati

Di seguito trovi tutti gli helper integrati, cosa si aspettano e come si comportano. Le firme corrispondono al codice sorgente; quando un helper non accetta argomenti, le parentesi sono vuote.

Ciclo di vita della domanda

sendQuery(): asincrono, senza argomenti. Legge il testo corrente da #skdwn-search-input. Se è vuoto non fa nulla. Altrimenti porta lo state a { query, isLoading: true }, scorre fino in fondo e invia la richiesta in streaming al backend. La richiesta che costruisce contiene:

• userPrompt: il testo del campo.
• previousConversation: i turni precedenti, solo quando

settings.usePreviousConversation è attivo; altrimenti una stringa vuota.

• additionalContext: ciò che la pagina ospitante ha passato in startOptions.additionalContext.

In caso di successo svuota il campo (query: ''), reimposta l’altezza della textarea e chiude qualsiasi scheda aperta. In caso di errore mantiene il testo così l’utente può riprovare, azzera isLoading, registra l’errore e aggiunge un risultato ERROR.

onChangeQuery(event): da collegare a oninput sulla textarea. Scrive il valore del campo in state.query e fa crescere automaticamente la textarea. Dove il browser supporta il CSS field-sizing: content la crescita è nativa; altrove (ad es. Firefox) ricorre alla regolazione dell’altezza in JS.

onPressEnter(event): da collegare a onkeydown sulla textarea. Invio invia la domanda (chiama sendQuery() e impedisce il ritorno a capo predefinito); Maiusc+Invio inserisce un’interruzione di riga così il campo si espande per una domanda su più righe.

stopQuery(): senza argomenti. Interrompe una domanda attualmente in streaming.

hintBoxClick(element): passa l’elemento cliccato come this. Legge la domanda suggerita dal suo attributo data-hint, la inserisce nel campo di ricerca, chiama sendQuery() e traccia un evento HintBoxClick.

Conversazione e reazioni

showHints(): senza argomenti. Mostra di nuovo il saluto/i suggerimenti creando un nuovo risultato WELCOME e traccia ShowHints.

clearHistory(): senza argomenti. Cancella i risultati memorizzati, svuota state.results, crea un nuovo WELCOME e traccia ClearHistory.

react(resultId, reactionType, element): registra un pollice in su/giù su una risposta. resultId è l’id del risultato della risposta; reactionType è 'like' o 'dislike' (element è accettato per simmetria ma non viene usato). La logica di attivazione: cliccare di nuovo la stessa reazione non ha effetto; cliccare quella opposta la riporta a neutral. Traccia un evento Reaction e riscrive payload.reaction sul risultato.

Finestra di anteprima

openPreview(event, element): apre l’anteprima dell’immagine/del documento. Legge data-previewsrc (il segmento del percorso della fonte) e data-title dall’elemento, costruisce ${serviceURL}/api/public/assistants/${previewsrc} (aggiungendo l’accesstoken come parametro di query quando presente) e lo mostra nella finestra modale tramite { modalOpen: true, modalContent, modalTitle }.

closePreview(): senza argomenti. Chiude la finestra modale ({ modalOpen: false, modalContent: '' }).

Finestra e layout

toggleMaximized(): senza argomenti. Alterna #skdwn-main-container tra le dimensioni minimized e maximized e lo riflette in state.skdwnWindowState.

toggleShowFloatingWindow(show): show è un booleano. true nasconde il pulsante flottante, mostra la finestra (ripristinando l’ultima dimensione, o forzando minimized quando il pulsante d’azione flottante è disattivato), mette il focus sul campo di ricerca e riproduce l’animazione di apertura. false nasconde la finestra, la contrassegna come closed e fa ricomparire il pulsante.

handleScroll(): senza argomenti. Scorre il contenitore della conversazione (#skdwn-floating-window-main) fino in fondo; gli helper lo richiamano dopo aver aggiunto contenuti così la risposta più recente è visibile.

Moduli e proxy

showForm(formType): formType è l’id del modulo. Imposta activeForm: true e crea un risultato FORM (con un UUID generato) che visualizza quel modulo.

sendForm(formType, event): asincrono, da collegare all’onsubmit di un modulo. Impedisce l’invio predefinito, serializza i campi del modulo in un payload, contrassegna il risultato come in fase di invio e chiama sendFormRequest(formType, payload). In caso di successo il risultato viene marcato submitted; in caso di errore aggiunge un risultato ERROR; in entrambi i casi azzera activeForm.

sendProxyForm(proxyId, event, callback): asincrono, per i moduli che chiamano un endpoint proxy. Impedisce l’invio predefinito, serializza i campi, attiva isLoading e chiama executeProxyRequest(proxyId, payload, callback). Se il proxy restituisce una risposta, viene aggiunta come risultato; gli errori diventano un risultato ERROR.

Helper di visualizzazione

materialIcon(parameters): restituisce HTML sicuro per un’icona Material. A differenza degli helper di evento, questo produce markup, quindi lo usi come filtro Liquid (vedi Gli helper sono anche filtri). parameters accetta:

• iconName: il nome della ligatura (ad es. search, close).
• size: il font-size CSS (predefinito 16px).
• iconStyle: una variante dell’icona come outlined o round (corrisponde a material-icons-<style>).

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

Il valore che passi con la pipe diventa l’oggetto parameters, quindi in pratica lo chiami con qualunque oggetto sia disponibile. Il suo output è già HTML sicuro: non aggiungere | safe.

greet(parameters): un piccolo helper di esempio che restituisce JSON.stringify(parameters). È lì come punto di partenza quando aggiungi i tuoi: aprilo, usa Test code per passare un JSON di esempio e osserva il risultato nel pannello di debug.

Richiamare un helper

Collega gli helper agli eventi del DOM direttamente dal 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>

Passa i dati a un helper tramite gli attributi data-* e leggili dall’elemento con 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>

Per una scheda di suggerimento, memorizza la domanda in data-hint e lascia che hintBoxClick la recuperi:

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

Gli helper sono anche filtri

Ogni helper, integrato e personalizzato, viene registrato due volte:

1. Come metodo su skdwn.instance.helpers.<name>, per onclick/oninput/onsubmit.
2. Come filtro Liquid con lo stesso nome, da usare dentro {{ … }}.

Quale usare dipende da cosa fa l’helper. Gli helper di evento (sendQuery, react, openPreview, …) vanno sugli eventi del DOM. Gli helper che restituiscono un valore, come materialIcon che restituisce HTML, si usano come filtri, dove il valore passato con la pipe diventa il primo argomento dell’helper:

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

Ecco perché un helper personalizzato che aggiungi per la formattazione può essere inserito direttamente in {{ }} senza alcun collegamento aggiuntivo.

I tuoi helper

L’Advanced editor ti permette di aggiungere helper personalizzati: JavaScript memorizzato in settings.extensions.helpers. Ogni voce può essere una singola funzione o un oggetto di funzioni; Seekdown li valuta all’avvio e li unisce a skdwn.instance.helpers, così li richiami esattamente come quelli integrati. Se la valutazione di un helper fallisce, viene saltato (con un avviso nella console) invece di compromettere il widget.

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

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

Dentro un helper personalizzato hai la stessa API dell’istanza usata da quelli integrati. Per cambiare ciò che appare sullo schermo, chiama skdwn.instance.updateState({ ... }); per aggiungere un messaggio, chiama skdwn.instance.createResult({ type: 'ERROR', payload: { reply: 'Something went wrong' } }); per registrare un evento di analisi, chiama skdwn.instance.sendTrace('MyEvent', { ... }).

Approfondisci

• Usa l’Advanced editor
• L’oggetto state