LA RISPOSTA DI PAGINA

Tipi condivisi e testo formattato

Alcuni oggetti ricorrono in ogni parte della risposta: l'intestazione, le regole di visibilita, il contenuto multimediale, lo sfondo, la destinazione di un collegamento e il gruppo di pulsanti. A questi si aggiunge il formato del testo formattato, che il software di rendering traduce in marcatura.

Intestazione e visibilita

L'oggetto heading ha sempre tre proprieta: eyebrow, title e subtitle. Ciascuna e presente solo se compilata nel pannello.

Proprieta del titolo	Descrizione
`html`	Testo gia reso in marcatura. E la forma di riserva.
`raw`	Nodi strutturati dello stesso testo. E la forma preferita.
`text`	Testo semplice. Valorizzato nei soli componenti globali, dove il titolo non e formattato.
`anchorId`	Ancora del titolo, da usare come identificativo dell'elemento. Corrisponde a una voce del sommario.
`level`	Livello gerarchico: H1, H2, H3 o H4. Determina il tag di intestazione da usare.

Sopracciglio e sottotitolo espongono soltanto html e raw: non sono titoli, quindi non hanno ne ancora ne livello, e non vanno resi con un tag di intestazione.

L'oggetto visibility ha tre valori logici: hiddenOnDesktop, hiddenOnTablet e hiddenOnMobile. Sono regole di presentazione, non di autorizzazione: il componente nascosto e comunque presente nella risposta e nel documento generato. Un contenuto da non pubblicare non va gestito con la visibilita.

Il contenuto multimediale

Un solo oggetto rappresenta immagini, filmati, icone, animazioni ed etichette. La proprieta type stabilisce quali altre proprieta sono significative: Image, VideoMp4, VideoYoutube, Svg, Icon, Number, LabelText, LabelNumber, Logo, LottieAnimation o AudioMp3.

Proprieta	Descrizione
`url`	Indirizzo assoluto della risorsa nella variante principale.
`mobileUrl`	Variante per schermi ridotti, quando caricata. Ha proprie mobileWidth e mobileHeight.
`thumbnailUrl`	Miniatura, adatta agli elenchi e ai segnaposto di caricamento.
`posterUrl`	Fotogramma di anteprima dei filmati.
`alt`	Testo alternativo. Va sempre riportato nella marcatura, anche vuoto per le immagini decorative.
`width` e `height`	Dimensioni native, da riportare negli attributi per evitare lo spostamento del layout.
`durationSeconds`	Durata dei contenuti audio e video.
`svg` e `icon`	Marcatura SVG in linea e nome dell'icona, per i tipi corrispondenti.
`label` e `number`	Etichetta testuale e valore numerico, per i tipi Number, LabelText e LabelNumber.
`license`, `licenseHtml`, `author`, `authorUrl`	Attribuzione della risorsa. Presenti solo quando compilate; vanno pubblicate se valorizzate.
`isAiGenerated`	Presente e pari a true soltanto per le risorse dichiarate come generate da intelligenza artificiale. Negli altri casi e assente.
`tags`	Etichette di classificazione, con id e name. Presente solo se non vuoto.

Lo sfondo di un componente e un oggetto a se: dichiara type con valore Image o Multimedia e contiene fino a tre contenuti multimediali: image, multimedia e multimediaMobile. Il tipo indica quale usare; l'immagine puo restare come ripiego per i dispositivi che non riproducono il filmato.

Destinazioni e pulsanti

L'oggetto link ha quattro proprieta: type, url, title e openInNewTab. Il tipo indica come costruire l'indirizzo nella marcatura.

Tipo	Trattamento
`Internal`	Percorso relativo del sito. Va gestito con la navigazione interna del client.
`External`	Indirizzo assoluto verso un altro dominio.
`Mail`, `Phone`, `WhatsApp`	Recapiti. Il client antepone lo schema corrispondente.
`AnchorText`	Ancora interna alla pagina corrente.
`Lightbox`	Apertura della risorsa in una finestra sovrapposta, senza cambiare pagina.
`Self`	Rimanda alla pagina corrente.
`None`	Nessuna destinazione. L'elemento non e cliccabile.

Quando openInNewTab e true, il collegamento va aperto in una nuova scheda e accompagnato dagli attributi di sicurezza previsti per i collegamenti esterni.

Il gruppo di pulsanti espone helperHtml, un testo di accompagnamento, e l'elenco buttons. Ogni pulsante ha caption, link e iconType, che assume i valori None, ArrowRight, ArrowExternal, Download, WhatsApp, Phone, Email, Document, Calendar, Map, Cart o Play. L'icona corrispondente e a carico del software di rendering.

Il testo formattato

Ogni testo redazionale e disponibile in due forme. La proprieta html contiene la marcatura gia generata; la proprieta raw, o il campo con lo stesso suffisso, contiene l'elenco dei nodi da cui quella marcatura deriva.

La forma strutturata e quella da preferire: consente di generare la marcatura secondo le convenzioni del proprio progetto e di sostituire i collegamenti interni con la navigazione del client. La marcatura pronta resta la forma di riserva, utile quando il testo va inserito senza trasformazioni.

Le due forme rappresentano lo stesso contenuto e non vanno rese entrambe. Il software di rendering ne sceglie una: se raw e presente la usa, altrimenti ricade su html.

Ogni nodo ha una proprieta type. I nodi di testo hanno text e un eventuale elenco marks; i nodi contenitori hanno un elenco content con i propri figli. Alcuni nodi hanno inoltre un oggetto attrs.

I nodi e la loro marcatura

La tabella riporta i nodi previsti e la marcatura con cui vengono resi dal renderer di riferimento. Un software di rendering puo scegliere una marcatura diversa, purche conservi la struttura.

Nodo	Marcatura di riferimento
`paragraph`	Un paragrafo. Nei titoli il tag viene omesso e resta il solo contenuto.
`heading`	Reso come paragrafo: i livelli di titolo della pagina sono governati dalle intestazioni dei componenti, non dal testo.
`text`	Testo, con le formattazioni dichiarate in marks.
`hardBreak`	Interruzione di riga.
`bulletList`, `orderedList`, `listItem`	Elenco puntato, elenco numerato e relative voci.
`blockquote`	Citazione.
`codeBlock`	Blocco di codice preformattato.
`gajaAlert`	Avviso in evidenza. L'attributo variant vale info, success, warning o error.
`gajaChecklist`	Elenco di controllo, reso come elenco con una classe dedicata.
`gajaSeparator`	Separatore orizzontale.
`table`, `tableRow`, `tableHeader`, `tableCell`	Tabella e sue parti. Le celle possono avere gli attributi colspan e rowspan, riportati solo se maggiori di 1.

Un nodo di tipo sconosciuto non va scartato: il software di rendering ne rende comunque i figli, cosi che il testo non vada perduto quando il contratto viene esteso.

Le formattazioni del testo

L'elenco marks di un nodo di testo dichiara le formattazioni applicate. Vanno aperte nell'ordine dell'elenco e chiuse in ordine inverso.

Formattazione	Resa
`bold`, `italic`, `strike`, `small`	Grassetto, corsivo, testo barrato, testo ridotto.
`code`	Termine tecnico, comando o identificativo, reso a spaziatura fissa.
`underline`	Nel corpo del testo e una sottolineatura; nei titoli e invece una porzione in evidenza, resa con una classe dedicata anziche con la sottolineatura.
`link`	Collegamento. Gli attributi sono href, target, title e data-internal-id.
`cmsClass`	Classe di presentazione scelta dalla redazione, dichiarata nell'attributo class.

Le classi ammesse per cmsClass sono un elenco chiuso: text-size-sm, text-size-lg, text-primary, text-cms-secondary, text-action, text-secondary, text-gray, text-white e e-rte-anchor. Le classi non comprese nell'elenco vengono scartate e il progetto di rendering deve prevedere una regola di stile per ciascuna di quelle ammesse.

Collegamenti nel testo e sicurezza

I collegamenti inseriti nel testo redazionale seguono regole precise, che il software di rendering deve riprodurre quando genera la marcatura dai nodi.

Sono ammessi soltanto gli indirizzi relativi che iniziano con /, le ancore che iniziano con # e gli indirizzi assoluti con schema http, https, mailto o tel. Ogni altro schema va scartato mantenendo il testo.
Quando l'attributo target vale _blank, il collegamento va accompagnato dagli attributi di sicurezza noopener e noreferrer.
L'attributo data-internal-id identifica la destinazione interna. E il riferimento con cui il client puo usare la propria navigazione invece di un caricamento completo della pagina.
Il testo dei nodi va codificato prima di essere inserito nel documento: i caratteri riservati della marcatura non sono gia codificati nella proprieta text.

La proprieta html arriva gia in forma di marcatura. Se il software di rendering la inserisce senza trasformazioni, deve considerarla contenuto attendibile proveniente dal pannello e non applicarvi ulteriori concatenazioni con dati esterni.

{
  "title": {
    "html": "I NOSTRI <u>PARTNERS</u>",
    "raw": [
      { "type": "text", "text": "I NOSTRI " },
      { "type": "text", "text": "PARTNERS", "marks": [ { "type": "underline" } ] }
    ],
    "anchorId": "a-i-nostri-partners",
    "level": "H2"
  }
}

{
  "raw": [
    {
      "type": "paragraph",
      "content": [
        { "type": "text", "text": "Certificazioni possedute:" }
      ]
    },
    {
      "type": "bulletList",
      "content": [
        {
          "type": "listItem",
          "content": [
            {
              "type": "paragraph",
              "content": [
                { "type": "text", "text": "ISO 9001", "marks": [ { "type": "bold" } ] }
              ]
            }
          ]
        }
      ]
    }
  ]
}