Home page

Le home page sono una nuova funzionalità dei componenti aggiuntivi di Google Workspace che consente di definire una o più schede non contestuali. Le schede non contestuali vengono utilizzate per visualizzare un'interfaccia utente quando l'utente si trova al di fuori di un contesto specifico, ad esempio quando visualizza la Posta in arrivo di Gmail ma non ha aperto un messaggio o una bozza.

Le home page ti consentono di mostrare contenuti non contestuali, proprio come le app Google nel riquadro laterale di accesso rapido (Keep, Calendar e Tasks). Le home page possono anche fornire un punto di partenza iniziale quando un utente apre per la prima volta il componente aggiuntivo e sono utili per insegnare ai nuovi utenti come interagire con il componente aggiuntivo.

Puoi definire una home page per il tuo componente aggiuntivo specificandola nel manifest del progetto e implementando una o più funzioni homepageTrigger (vedi Configurazione della home page).

Puoi avere più home page, una per ogni applicazione host estesa dal tuo componente aggiuntivo. Puoi anche decidere di definire una singola home page predefinita comune che viene utilizzata negli host in cui non hai specificato una home page personalizzata.

La home page del componente aggiuntivo viene visualizzata quando si verifica una delle seguenti condizioni:

• Quando il componente aggiuntivo viene aperto per la prima volta nell'host (dopo l'autorizzazione).
• Quando l'utente passa da un contesto contestuale a uno non contestuale mentre il componente aggiuntivo è aperto. Ad esempio, dalla modifica di un evento di Calendar al calendario principale.
• Quando l'utente fa clic sul pulsante Indietro un numero sufficiente di volte per far uscire una scheda su due dalle pile interne.
• Quando un'interazione dell'interfaccia utente in una scheda non contestuale genera una chiamata Navigation.popToRoot().

La progettazione di una home page non è obbligatoria, ma è consigliata. Se non ne definisci una, viene utilizzata una scheda generica contenente il nome del componente aggiuntivo ogni volta che un utente dovrebbe altrimenti navigare alla home page.

Configurazione della home page

I componenti aggiuntivi di Google Workspace utilizzano il campo addOns.common.homepageTrigger per configurare i contenuti predefiniti (non contestuali) del componente aggiuntivo della home page per tutte le applicazioni host nel manifest del componente aggiuntivo:

    {
      // ...
      "addOns": {
        // ...
        "common": {
          // ...
          "homepageTrigger": {
            "runFunction": "myFunction",
            "enabled": true
          }
        }
      }
    }

• runFunction: il nome della funzione Apps Script che il framework dei componenti aggiuntivi di Google Workspace richiama per eseguire il rendering delle schede dei componenti aggiuntivi della home page. Questa funzione è la funzione di attivazione della home page. Questa funzione deve creare e restituire un array di oggetti Card che compongono l'interfaccia utente della home page. Se vengono restituite più schede, l'applicazione host mostra le intestazioni delle schede in un elenco che l'utente può selezionare (vedi Restituzione di più schede).

• enabled: indica se le schede della home page devono essere abilitate per questo ambito. Questo campo è facoltativo e il valore predefinito è true. Se imposti questo valore su false, le schede della home page vengono disattivate per tutti gli host (a meno che non venga eseguito l'override per l'host in questione; vedi di seguito).

Nota: affinché un host possa utilizzare la home page comune, sia addOns.common.homepageTrigger sia la risorsa di primo livello dell'host devono essere presenti nel manifest del componente aggiuntivo. Ad esempio, se addOns.gmail non è presente nel manifest, il componente aggiuntivo è disattivato per Gmail e non mostrerà una home page (o qualsiasi altra funzionalità nell'host).

Oltre alla configurazione comune, sono disponibili anche override per host con struttura identica nella configurazione di ogni applicazione host, in addOns.gmail.homepageTrigger, addOns.calendar.homepageTrigger e così via:

    {
      ...
      "addOns": {
        ...
        "common": {
          // By default, call 'buildHomePage' to render homepage content
          // in all hosts. Since calendar.homepageTrigger below overrides
          // this in Calendar and Drive and the homepageTrigger is disabled
          // for Gmail, this homepage function never executes.
          "homepageTrigger": { "runFunction": "buildHomePage" }
        },
        "calendar": {
          // Show customized homepage content for Calendar only.
          "homepageTrigger": { "runFunction": "buildCalendarHomepage" }
        },
        "drive": {
          // Show customized homepage content for Drive only.
          "homepageTrigger": { "runFunction": "buildDriveHomepage" }
        }
        "gmail": {
          // Disable homepage add-on content in Gmail.
          "homepageTrigger": { "enabled": false }
        },
        ...
      }
    }

Tieni presente che questo è equivalente al seguente estratto del manifest:

    {
      ...
      "addOns": {
        ...
        "common": { /* ... */ }, // Omitted a default homepageTrigger specification.
        "calendar": {
          // Show customized homepage content for Calendar only.
          "homepageTrigger": { "runFunction": "myCalendarFunction" }
        },
        "drive": {
          // Show customized homepage content for Drive only.
          "homepageTrigger": { "runFunction": "myDriveFunction" }
        }
        "gmail": { /* ... */ },
        ...
      }
    }

Nessuna delle sezioni homepageTrigger è obbligatoria. Tuttavia, la UI mostrata per un componente aggiuntivo in un determinato prodotto host dipende dalla presenza del campo manifest corrispondente e dalla presenza di un homepageTrigger associato. Il seguente esempio mostra quali funzioni di attivazione dei componenti aggiuntivi vengono eseguite (se presenti) per creare una UI della home page per diverse configurazioni del file manifest:

Oggetti evento della home page

Quando viene chiamata, alla funzione di trigger della home page (runFunction) descritta sopra viene trasmesso un oggetto evento contenente i dati del contesto di chiamata.

Gli oggetti evento della home page non includono widget o informazioni contestuali; le informazioni trasmesse sono limitate ai seguenti campi dell'oggetto evento comune:

• commonEventObject.clientPlatform
• commonEventObject.hostApp
• commonEventObject.userLocale e commonEventObject.userTimezone (ma vedi Accesso a località e fuso orario dell'utente per informazioni sulle limitazioni).

Per maggiori dettagli, vedi Oggetto evento.

Altre schede non contestuali

L'interfaccia utente del componente aggiuntivo può contenere schede non contestuali aggiuntive che non sono home page. Ad esempio, la home page potrebbe avere un pulsante che apre una scheda "Impostazioni" in cui l'utente può regolare le impostazioni del componente aggiuntivo (queste impostazioni sarebbero, nella maggior parte dei casi, indipendenti dal contesto e quindi non contestuali).

Le schede non contestuali vengono create come qualsiasi altra scheda; l'unica differenza è l'azione o l'evento che genera e visualizza la scheda. Consulta Metodi di navigazione per informazioni dettagliate su come creare transizioni tra le schede.