Come strutturare il codice HTML per le diapositive dei moduli interattivi – SMARTFENSE

Questo articolo spiega i requisiti minimi e la struttura consigliata affinché il contenuto HTML funzioni correttamente all'interno delle diapositive di tipo Contenuto HTML nei moduli interattivi di SMARTFENSE.

Come funziona il contenitore della piattaforma

L'attività Contenuto HTML visualizza la diapositiva all'interno di un iframe gestito internamente dalla piattaforma. Lo sviluppatore non interagisce direttamente con quell'iframe.

Per consentire all'iframe di adattare la propria altezza al contenuto della diapositiva, la piattaforma inietta automaticamente lo script di ridimensionamento automatico al momento della visualizzazione nella vista finale. Non è necessario includerlo nel proprio HTML.

Questo adattamento automatico richiede che la diapositiva abbia un'altezza naturale, definita dal proprio contenuto. Se l'HTML forza un'altezza fissa o relativa allo schermo su html, body o sul contenitore principale, la piattaforma non riesce a calcolare correttamente quanto deve crescere l'iframe e il contenuto viene troncato (vedere la sezione "Altezze: cosa evitare" più avanti).

Requisiti obbligatori

Una diapositiva HTML deve soddisfare questi requisiti per funzionare correttamente sulla piattaforma.

1. HTML autonomo

La diapositiva non deve fare riferimento a file esterni propri. Tutti gli stili devono essere incorporati nel <head> all'interno di un tag <style>.

2. Notificare il completamento (solo se la diapositiva blocca l'avanzamento)

Se la diapositiva è configurata come obbligatoria per avanzare, il codice deve notificare alla piattaforma quando l'utente completa l'attività:

function notifyCompleted(success = true) {
  window.parent.postMessage({ type: 'ACTIVITY_COMPLETED', success }, '*');
}

Chiamare questa funzione nel momento in cui l'utente completa l'attività definita.

Altezze: cosa evitare

Il ridimensionamento automatico dell'altezza misura l'altezza naturale del contenuto della diapositiva. Qualsiasi regola CSS che forzi un'altezza fissa o relativa allo schermo interrompe quella misurazione: il contenuto viene troncato nella vista finale, anche se nell'anteprima dell'editor appare completo (quella anteprima ha uno scroll proprio, per questo non mostra il problema).

Evitare di dichiarare, su html, body o nel contenitore principale della diapositiva:

height: 100% (o qualsiasi percentuale) su html o body.
min-height: 100vh, height: 100vh, o qualsiasi altra unità relativa al viewport (vh, vw) nel contenitore principale. All'interno dell'iframe, il "viewport" è l'iframe stesso, non lo schermo dell'utente, quindi quella unità non rappresenta l'altezza reale disponibile.

Lasciare che html e body abbiano la loro altezza naturale (senza dichiarare height, o con height: auto), e che il contenitore principale cresca in base al contenuto. Se è necessaria un'altezza minima, usare un valore fisso in pixel, mai in vh.

Struttura base consigliata

<!DOCTYPE html>
<html lang="it">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Titolo della diapositiva</title>
  <style>
    /* Stili propri della diapositiva */
    /* Non dichiarare height:100% su html/body né min-height:100vh nel contenitore principale */
  </style>
</head>
<body>
  <!-- Contenuto della diapositiva -->

  <script>
    // Logica della diapositiva

    // Solo se la diapositiva blocca l'avanzamento:
    function notifyCompleted(success = true) {
      window.parent.postMessage({ type: 'ACTIVITY_COMPLETED', success }, '*');
    }
  </script>
</body>
</html>

Variabili di personalizzazione

L'editor supporta variabili che vengono sostituite dinamicamente con i dati dell'utente e dell'organizzazione quando il modulo viene visualizzato.

Variabili utente:

Variabile	Descrizione
`$name`	Nome dell'utente
`$lastname`	Cognome dell'utente
`$email`	Indirizzo email dell'utente
`$username`	Nome utente
`$manager_email`	Email del responsabile diretto

Variabili organizzazione (configurate in Impostazioni → Organizzazione → Dati dell'organizzazione):

Variabile	Descrizione
`$organization_name`	Nome dell'organizzazione
`$tenant_name`	Nome del tenant
`$domain`	Dominio principale
`$main_organization_domain`	Dominio principale dell'organizzazione
`$help_desk_area`	Nome dell'area help desk
`$help_desk_email`	Email dell'help desk
`$help_desk_phone`	Telefono dell'help desk
`$compliance_area`	Nome dell'area compliance
`$hr_area`	Nome dell'area risorse umane
`$is_area`	Nome dell'area sicurezza delle informazioni
`$is_email`	Email dell'area sicurezza delle informazioni
`$incident_report_area`	Nome dell'area di segnalazione incidenti
`$incident_report_email`	Email di segnalazione incidenti
`$incident_report_phone`	Telefono di segnalazione incidenti
`$ceo`	Nome del CEO
`$ceo_email`	Email del CEO
`$cto`	Nome del CTO
`$ciso`	Nome del CISO
`$ciso_email`	Email del CISO
`$cpo`	Nome del CPO
`$cpo_email`	Email del CPO
`$chro`	Nome del CHRO
`$cco`	Nome del CCO
`$cco_email`	Email del CCO
`$cco_area`	Nome dell'area del CCO
`$procurement_area`	Nome dell'area acquisti
`$procurement_area_email`	Email dell'area acquisti

Per utilizzare una variabile, inserirla direttamente nell'HTML nel punto desiderato:

<p>Salve, <strong>$name $lastname</strong>. Per qualsiasi incidente, contattare <strong>$incident_report_area</strong> all'indirizzo <strong>$incident_report_email</strong>.</p>

Le variabili organizzazione vengono aggiornate in un unico punto e si propagano automaticamente a tutti i moduli che le utilizzano.

💡 Buone pratiche

Prendere come punto di partenza una diapositiva esistente dalla galleria di SMARTFENSE. Include già la struttura base corretta.
Non dichiarare height: 100% su html/body né min-height: 100vh (o altre unità relative al viewport) nel contenitore principale: impediscono alla piattaforma di calcolare l'altezza reale della diapositiva e il contenuto viene troncato.
Usare il pulsante Anteprima dopo ogni modifica prima di salvare, tenendo presente che quella vista ha uno scroll proprio: una diapositiva con l'altezza configurata in modo errato può apparire completa lì e risultare comunque troncata nella vista finale.
Testare sempre con una campagna di prova prima di lanciare il modulo agli utenti finali — è l'unico modo per vedere la diapositiva esattamente come la vedrà l'utente.
Verificare che tutti gli stili siano incorporati nel <head> e che l'HTML non faccia riferimento a file esterni