Home page

Le home page sono una funzionalità dei componenti aggiuntivi Google Workspace che consente di definire una o più schede non contestuali. Le schede non contestuali mostrano 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 senza un messaggio o una bozza aperti.

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

Definisci 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 definire una singola home page predefinita comune da utilizzare negli host in cui non hai specificato una home page personalizzata.

La home page del componente aggiuntivo viene visualizzata nei seguenti casi:

• Quando il componente aggiuntivo viene aperto per la prima volta nell'host (dopo l'autorizzazione).
• Quando l'utente passa da un contesto contestuale a un contesto 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 ogni altra carta dalle pile interne.
• Quando un'interazione con l'interfaccia utente in una scheda non contestuale genera una chiamata Navigation.popToRoot.

È consigliabile progettare una home page. Se non ne definisci nessuna, viene utilizzata una scheda generica contenente il nome del componente aggiuntivo ogni volta che un utente naviga nella 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) dei componenti aggiuntivi per le applicazioni host nel manifest del componente aggiuntivo:

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

• runFunction: il nome della funzione Google 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 specifico; vedi la configurazione specifica dell'host).

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 viene disattivato per Gmail e non mostra una home page o altre funzionalità in questo host.

Oltre alla configurazione comune, in ogni configurazione dell'applicazione host sono disponibili override per host con struttura identica, in addOns.gmail.homepageTrigger, addOns.calendar.homepageTrigger e altri trigger specifici dell'host.

L'esempio seguente mostra un manifest in cui è definito un trigger della home page comune, ma viene sostituito da funzioni personalizzate per Calendar e Drive e disabilitato per Gmail. In questa configurazione, la funzione comune buildHomePage non viene mai eseguita perché è sovrascritta o l'host è disattivato.

{
  ...
  "addOns": {
    ...
    "common": {
      "homepageTrigger": { "runFunction": "buildHomePage" }
    },
    "calendar": {
      "homepageTrigger": { "runFunction": "buildCalendarHomepage" }
    },
    "drive": {
      "homepageTrigger": { "runFunction": "buildDriveHomepage" }
    },
    "gmail": {
      "homepageTrigger": { "enabled": false }
    },
    ...
  }
}

Il seguente estratto del manifest è equivalente all'esempio precedente, anche se homepageTrigger predefinito e la configurazione di Gmail sono omessi:

{
  "addOns": {
    "common": {},
    "calendar": {
      "homepageTrigger": { "runFunction": "myCalendarFunction" }
    },
    "drive": {
      "homepageTrigger": { "runFunction": "myDriveFunction" }
    },
    "gmail": {},
    ...
  }
}

Nessuna delle sezioni homepageTrigger è obbligatoria. L'interfaccia utente mostrata per un componente aggiuntivo in un prodotto host dipende dalla presenza del campo manifest corrispondente e dall'eventuale presenza di un homepageTrigger associato. L'esempio seguente mostra quali funzioni di attivazione dei componenti aggiuntivi vengono eseguite per creare un'interfaccia utente 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 in precedenza viene passato 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 (vedi Accesso alle impostazioni internazionali e al 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 aggiuntive non contestuali che non sono home page. Ad esempio, la home page potrebbe avere un pulsante che apre una scheda "Impostazioni" per regolare le impostazioni dei componenti aggiuntivi (queste impostazioni sono in genere indipendenti dal contesto).

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.