Layout Pagina

​

Panoramica

​

definePageLayout

import { definePageLayout, PageLayoutTabLayoutMode } from 'twenty-sdk/define';
import { EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER } from '../objects/example-object';
import { HELLO_WORLD_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER } from '../front-components/hello-world';

export default definePageLayout({
  universalIdentifier: '203aeb94-6701-46d6-9af1-be2bbcc9e134',
  name: 'Example Record Page',
  type: 'RECORD_PAGE',
  objectUniversalIdentifier: EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER,
  tabs: [
    {
      universalIdentifier: '6ed26b60-a51d-4ad7-86dd-1c04c7f3cac5',
      title: 'Hello World',
      position: 50,
      icon: 'IconWorld',
      layoutMode: PageLayoutTabLayoutMode.VERTICAL_LIST,
      widgets: [
        {
          universalIdentifier: 'aa4234e0-2e5f-4c02-a96a-573449e2351d',
          title: 'Hello World',
          type: 'FRONT_COMPONENT',
          heightBehavior: 'TAB_VIEWPORT',
          configuration: {
            configurationType: 'FRONT_COMPONENT',
            frontComponentUniversalIdentifier:
              HELLO_WORLD_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER,
          },
        },
      ],
    },
  ],
});

​

Punti chiave

• type è uno tra 'RECORD_INDEX', 'RECORD_PAGE', 'DASHBOARD', 'STANDALONE_PAGE' o 'RECORD_FORM'. Usa 'RECORD_PAGE' per personalizzare la vista dei dettagli di un oggetto specifico. 'RECORD_FORM' descrive il modulo di creazione di un oggetto e contiene widget FORM_FIELD, ognuno dei quali visualizza un singolo campo. Twenty fornisce un layout 'RECORD_FORM' per oggetto con un widget per ogni campo creabile, quindi raramente è necessario crearne uno; non esegue ancora il rendering dei moduli di record.
• objectUniversalIdentifier specifica a quale oggetto si applica questo layout.
• Ogni tab definisce una sezione della pagina con title, position e layoutMode: usa VERTICAL_LIST per le pagine dei record e le pagine autonome, e GRID per le dashboard. Una tab VERTICAL_LIST dispone i widget verticalmente. I widget integrati che gestiscono il proprio scorrimento, come timeline, file, note, attività, flussi di lavoro e conversazioni, riempiono un’area di visualizzazione per impostazione predefinita; i campi, i componenti front, i grafici e altri widget con adattamento al contenuto vengono visualizzati all’altezza del loro contenuto o all’altezza configurata. Una tab GRID dispone sempre i widget come schede su una griglia di 12 colonne.
• I widget in una tab VERTICAL_LIST ereditano la modalità di layout della tab e il loro ordine deriva dall’array widgets. Non impostare position; imposta l’opzionale heightBehavior di primo livello su 'TAB_VIEWPORT' quando un widget deve occupare una viewport completa della tab e gestire il proprio scorrimento, oppure su 'FIT_CONTENT' per sovrascrivere un’impostazione predefinita integrata a tutta altezza. I widget precedenti non riducono tale altezza. È consentito un solo widget TAB_VIEWPORT attivo per tab e deve trovarsi dopo i widget fit-content.
• I widget GRID continuano a utilizzare position: { layoutMode: PageLayoutTabLayoutMode.GRID, row, column, rowSpan, columnSpan }. heightBehavior di livello superiore è valido solo per le schede VERTICAL_LIST; utilizzarlo con GRID o CANVAS genera un errore di convalida.
• Le schede Canvas esistenti e le posizioni esplicite dei widget rimangono supportate. L’SDK mostra avvisi di deprecazione con le sostituzioni consigliate.
• Imposta esplicitamente layoutMode. Ometterlo imposta VERTICAL_LIST su una STANDALONE_PAGE e GRID altrove, il che raramente è ciò che vuoi per la pagina di un record.
• Ogni widget all’interno di una scheda può renderizzare un front component, un elenco di relazioni o altri tipi di widget integrati.
• Un widget FRONT_COMPONENT può impostare headerCommandMenuItemUniversalIdentifiers su un array ordinato di identificatori universali degli elementi del menu di comando della stessa app. Queste azioni vengono visualizzate come pulsanti con icona nell’intestazione della scheda del widget e mantengono la relativa disponibilità a livello di comando e i controlli delle autorizzazioni. Gli identificatori devono essere univoci e devono essere risolti quando l’app è installata.
• Un widget IFRAME può utilizzare il microfono o la videocamera per i siti web approvati tramite requestedIframeMediaPermissions dell’app proprietaria. I membri selezionano Abilita e approvano una conferma nativa del browser che mostra l’app, l’origine del sito web e l’accesso richiesto al microfono o alla videocamera prima che inizi l’accesso. Le approvazioni di sicurezza dell’area di lavoro e le autorizzazioni di altre app non si applicano ai widget definiti dall’app.
• position sulle schede controlla il loro ordine. Usa valori più alti (ad es., 50) per posizionare le schede personalizzate dopo quelle integrate.
• twenty app pull riscrive i layout di pagina con le relative schede e widget inclusi inline. Un widget che l’esportazione non può ancora includere, ad esempio uno che mostra il componente front della tua app o uno del tipo VIEW deprecato, viene segnalato da pull anziché scritto; consulta ciò che pull non scrive.

​

Widget dei campi

{
  universalIdentifier: 'c1c2c3c4-c5c6-4000-8000-000000000003',
  title: 'People → Opportunities',
  type: 'FIELD',
  configuration: {
    configurationType: 'FIELD',
    fieldMetadataId: PEOPLE_FIELD_UNIVERSAL_IDENTIFIER,
    fieldDisplayMode: 'TABLE',
    nestedRelationFieldMetadataId: OPPORTUNITIES_FIELD_UNIVERSAL_IDENTIFIER,
  },
}

• fieldMetadataId accetta l’identificatore universale di un campo sull’oggetto del layout.
• fieldDisplayMode può essere uno tra 'FIELD', 'CARD', 'EDITOR', 'VIEW' o 'TABLE'. TABLE incorpora una vista che elenca i record di un campo di relazione uno-a-molti.
• isUIEditable si applica ai campi di relazione in modalità di visualizzazione TABLE. Per impostazione predefinita è true; impostalo su false per impedire la modifica dei record dalla tabella incorporata o dal kanban.
• nestedRelationFieldMetadataId è facoltativo e accetta l’identificatore universale di un campo di relazione uno-a-molti sull’oggetto di destinazione della relazione, per elencare i record a due salti di relazione di distanza (ad es. una pagina Company che elenca le opportunità delle persone dell’azienda, o una pagina Person che elenca le opportunità dell’azienda della persona). Il primo salto può essere un campo di relazione uno-a-molti o molti-a-uno, il secondo deve essere uno-a-molti (le relazioni di giunzione non sono supportate) e richiede fieldDisplayMode: 'TABLE' — combinarlo con qualsiasi altra modalità di visualizzazione genera un errore di convalida, poiché un widget annidato viene sempre renderizzato come una vista incorporata.

​

Widget della tabella dei record

{
  universalIdentifier: 'd1d2d3d4-d5d6-4000-8000-000000000004',
  title: 'Open opportunities',
  type: 'RECORD_TABLE',
  configuration: {
    configurationType: 'RECORD_TABLE',
    viewUniversalIdentifier: OPPORTUNITIES_VIEW_UNIVERSAL_IDENTIFIER,
    recordLimit: 8,
    isUIEditable: false,
  },
}

• viewUniversalIdentifier identifica la vista da visualizzare.
• recordLimit è facoltativo e limita il numero di record visualizzati dal widget.
• isUIEditable si applica alle viste tabella e kanban. Abilita la modifica delle celle della tabella o la modifica, lo spostamento e la creazione delle schede kanban. Per impostazione predefinita è true nei layout RECORD_PAGE e false negli altri layout.
• isUIEditable controlla solo le azioni dell’interfaccia utente. Le autorizzazioni dei record continuano ad applicarsi e le impostazioni della vista rimangono modificabili solo nell’editor del layout di pagina.

​

definePageLayoutTab

import {
  definePageLayoutTab,
  PageLayoutTabLayoutMode,
  STANDARD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIERS,
} from 'twenty-sdk/define';
import { HELLO_WORLD_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER } from '../front-components/hello-world';

export default definePageLayoutTab({
  universalIdentifier: 'b1b2b3b4-b5b6-4000-8000-000000000001',
  pageLayoutUniversalIdentifier:
    STANDARD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIERS.companyRecordPage
      .universalIdentifier,
  title: 'Hello World',
  position: 1000,
  icon: 'IconWorld',
  layoutMode: PageLayoutTabLayoutMode.VERTICAL_LIST,
  widgets: [
    {
      universalIdentifier: 'b1b2b3b4-b5b6-4000-8000-000000000002',
      title: 'Hello World',
      type: 'FRONT_COMPONENT',
      configuration: {
        configurationType: 'FRONT_COMPONENT',
        frontComponentUniversalIdentifier:
          HELLO_WORLD_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER,
      },
    },
  ],
});

​

Punti chiave

• pageLayoutUniversalIdentifier è obbligatorio e deve puntare a un layout di pagina che esiste già al momento dell’installazione — oppure un layout standard di Twenty o uno definito dalla tua app. I riferimenti tra app a layout di proprietà di un’altra app installata non sono attualmente supportati. Quando il layout di pagina padre manca, l’installazione non va a buon fine e restituisce un chiaro errore di validazione.
• Per i layout standard di Twenty, importa gli identificatori da twenty-sdk/define:
  import { STANDARD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIERS } from 'twenty-sdk/define';
  
  // STANDARD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIERS.companyRecordPage.universalIdentifier
  // STANDARD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIERS.personRecordPage.universalIdentifier
  // STANDARD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIERS.taskRecordPage.universalIdentifier
  // STANDARD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIERS.opportunityRecordPage.universalIdentifier
  // STANDARD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIERS.noteRecordPage.universalIdentifier
  // …
  
  Ogni voce di layout espone anche i propri tabs e i relativi widgets, così puoi fare riferimento a qualsiasi livello:
  STANDARD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIERS.taskRecordPage.tabs.home
    .universalIdentifier;
  STANDARD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIERS.taskRecordPage.tabs.home.widgets
    .fields.universalIdentifier;
  
  È disponibile anche un alias breve STANDARD_PAGE_LAYOUT:
  import { STANDARD_PAGE_LAYOUT } from 'twenty-sdk/define';
  
  STANDARD_PAGE_LAYOUT.companyRecordPage.universalIdentifier;
  
• I widgets sono limitati solo a questa scheda — fanno riferimento a front components, viste, ecc. esattamente come i widget definiti inline in definePageLayout.
• position controlla l’ordinamento rispetto alle schede esistenti nel layout di destinazione. Scegli un valore che collochi la tua scheda dove desideri rispetto alle schede integrate.
• Usa questo invece di definePageLayout quando vuoi solo aggiungere a un layout esistente. Usa definePageLayout quando possiedi l’intero layout.
• twenty app pull riscrive una scheda aggiunta a un layout di pagina di cui non sei proprietario come file definePageLayoutTab(), con i relativi widget inclusi inline, soggetti agli stessi limiti dei widget di un definePageLayout().

​

definePageLayoutWidget

import {
  definePageLayoutWidget,
  PageLayoutTabLayoutMode,
  PageLayoutWidgetVerticalListHeightBehavior,
  STANDARD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIERS,
} from 'twenty-sdk/define';
import { HELLO_WORLD_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER } from '../front-components/hello-world';

export default definePageLayoutWidget({
  universalIdentifier: 'b1b2b3b4-b5b6-4000-8000-000000000003',
  pageLayoutTabUniversalIdentifier:
    STANDARD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIERS.companyRecordPage.tabs.home
      .universalIdentifier,
  title: 'Hello World',
  type: 'FRONT_COMPONENT',
  position: {
    layoutMode: PageLayoutTabLayoutMode.VERTICAL_LIST,
    index: 1000,
    heightBehavior: PageLayoutWidgetVerticalListHeightBehavior.TAB_VIEWPORT,
  },
  configuration: {
    configurationType: 'FRONT_COMPONENT',
    frontComponentUniversalIdentifier:
      HELLO_WORLD_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER,
  },
});

​

Punti chiave

• pageLayoutTabUniversalIdentifier è obbligatorio e deve puntare a una scheda già esistente al momento dell’installazione: una scheda Twenty standard (STANDARD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIERS.\<object>RecordPage.tabs.\<tab>.universalIdentifier), una scheda di uno dei tuoi layout o una scheda della pagina del record che Twenty genera per uno dei tuoi oggetti. Le schede generate hanno identificatori deterministici, quindi puoi calcolarli:
  import {
    getSystemPageLayoutTabUniversalIdentifier,
    getSystemRecordPageLayoutUniversalIdentifier,
  } from 'twenty-sdk/define';
  
  const EXAMPLE_HOME_TAB_UNIVERSAL_IDENTIFIER =
    getSystemPageLayoutTabUniversalIdentifier({
      objectMetadataApplicationUniversalIdentifier:
        APPLICATION_UNIVERSAL_IDENTIFIER,
      pageLayoutUniversalIdentifier:
        getSystemRecordPageLayoutUniversalIdentifier({
          objectMetadataApplicationUniversalIdentifier:
            APPLICATION_UNIVERSAL_IDENTIFIER,
          objectUniversalIdentifier: EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER,
        }),
      title: 'Home',
    });
  
• position è obbligatorio, poiché la scheda non fa parte del tuo manifest e la sua modalità di layout non può essere dedotta. Abbina la modalità di layout della scheda: le schede della pagina del record sono elenchi verticali, quindi usa { layoutMode: PageLayoutTabLayoutMode.VERTICAL_LIST, index } con un indice superiore a quello dei widget integrati (il widget Fields è a 0).
• Per un elenco verticale, imposta position.heightBehavior su PageLayoutWidgetVerticalListHeightBehavior.TAB_VIEWPORT per riempire la viewport di una scheda, oppure su PageLayoutWidgetVerticalListHeightBehavior.FIT_CONTENT per utilizzare il contenuto o l’altezza configurata del widget. Importa questa enum da twenty-sdk/define, come nell’esempio precedente. Se omesso, il widget mantiene il valore predefinito integrato. Solo un widget attivo per scheda può riempire la viewport e il suo indice deve posizionarlo dopo tutti i widget con adattamento al contenuto. heightBehavior non è supportato nelle posizioni GRID o CANVAS.
• configuration funziona esattamente come un widget definito inline in definePageLayout o definePageLayoutTab: fa riferimento a componenti front, viste, campi e così via.
• Usa questa opzione invece di definePageLayoutTab quando la scheda esiste già e vuoi solo inserirvi un widget. Usa definePageLayoutTab quando vuoi una scheda tutta tua.
• twenty app pull riscrive un widget aggiunto a una scheda di cui non sei proprietario come file definePageLayoutWidget(), soggetto agli stessi limiti dei widget di un definePageLayout().