Diseños de Página

​

Resumen

​

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,
          },
        },
      ],
    },
  ],
});

​

Puntos clave

• type es uno de 'RECORD_INDEX', 'RECORD_PAGE', 'DASHBOARD', 'STANDALONE_PAGE' o 'RECORD_FORM'. Use 'RECORD_PAGE' para personalizar la vista de detalles de un objeto específico. 'RECORD_FORM' describe el formulario de creación de un objeto y contiene widgets FORM_FIELD, cada uno de los cuales representa un único campo. Twenty proporciona un diseño 'RECORD_FORM' por objeto con un widget por campo que se puede crear, por lo que rara vez necesita crear uno; aún no representa formularios de registros.
• objectUniversalIdentifier especifica a qué objeto se aplica este diseño.
• Cada tab define una sección de la página con un title, position y layoutMode: use VERTICAL_LIST para páginas de registros y páginas independientes, y GRID para paneles. Una pestaña VERTICAL_LIST apila los widgets verticalmente. Los widgets integrados que gestionan su propio desplazamiento, como líneas de tiempo, archivos, notas, tareas, flujos de trabajo y conversaciones, ocupan una ventana gráfica de forma predeterminada; los campos, los componentes frontales, los gráficos y otros widgets de ajuste al contenido se representan con la altura de su contenido o la configurada. Una pestaña GRID siempre distribuye sus widgets como tarjetas en una cuadrícula de 12 columnas.
• Los widgets de una pestaña VERTICAL_LIST heredan el modo de diseño de la pestaña, y su orden proviene de la matriz widgets. No establezca position; establezca el heightBehavior opcional de nivel superior en 'TAB_VIEWPORT' cuando un widget deba ocupar una ventana gráfica completa de la pestaña y gestionar su propio desplazamiento, o en 'FIT_CONTENT' para anular un valor predeterminado integrado de altura completa. Los widgets anteriores no reducen esa altura. Solo se permite un widget TAB_VIEWPORT activo por pestaña, y debe ir después de los widgets de ajuste al contenido.
• Los widgets GRID siguen usando position: { layoutMode: PageLayoutTabLayoutMode.GRID, row, column, rowSpan, columnSpan }. heightBehavior de nivel superior solo es válido para las pestañas VERTICAL_LIST; usarlo con GRID o CANVAS produce un error de validación.
• Las pestañas de Canvas existentes y las posiciones explícitas de los widgets siguen siendo compatibles. El SDK muestra advertencias de desuso con los reemplazos recomendados.
• Establece layoutMode explícitamente. Omitirlo te da VERTICAL_LIST en una STANDALONE_PAGE y GRID en todos los demás casos, lo cual rara vez es lo que quieres en una página de registro.
• Cada widget dentro de una pestaña puede renderizar un componente de frontend, una lista de relaciones u otros tipos de widget integrados.
• Un widget FRONT_COMPONENT puede establecer headerCommandMenuItemUniversalIdentifiers en una matriz ordenada de identificadores universales de elementos de menú de comandos de la misma aplicación. Estas acciones aparecen como botones de icono en el encabezado de la tarjeta del widget y conservan sus comprobaciones de disponibilidad y permisos a nivel de comando. Los identificadores deben ser únicos y deben resolverse cuando se instale la aplicación.
• Un widget de IFRAME puede usar el micrófono o la cámara en sitios web aprobados mediante requestedIframeMediaPermissions de la aplicación a la que pertenece. Los miembros seleccionan Habilitar y aprueban una confirmación nativa del navegador que muestra la aplicación, el origen del sitio web y el acceso solicitado al micrófono o a la cámara antes de que comience el acceso. Las aprobaciones de seguridad del espacio de trabajo y las concesiones de otras aplicaciones no se aplican a los widgets definidos por la aplicación.
• position en las pestañas controla su orden. Usa valores más altos (p. ej., 50) para colocar pestañas personalizadas después de las integradas.
• twenty app pull vuelve a escribir los diseños de página con sus pestañas y widgets integrados. Un widget que la exportación todavía no puede incluir, como uno que muestra el propio componente frontal de su aplicación o uno del tipo VIEW obsoleto, se informa mediante pull en lugar de escribirse; consulte lo que pull no escribe.

​

Widgets de campos

{
  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 toma el identificador universal de un campo en el objeto del layout.
• fieldDisplayMode es uno de 'FIELD', 'CARD', 'EDITOR', 'VIEW' o 'TABLE'. TABLE incrusta una vista que lista los registros de un campo de relación de uno a muchos.
• isUIEditable se aplica a los campos de relación en el modo de visualización TABLE. De forma predeterminada, es true; configúrelo como false para impedir la edición de registros desde la tabla o el kanban incrustados.
• nestedRelationFieldMetadataId es opcional y toma el identificador universal de un campo de relación de uno a muchos en el objeto de destino de la relación, para enumerar registros a dos saltos de relación (por ejemplo, una página de Company que enumera las oportunidades de las personas de la compañía, o una página de Person que enumera las oportunidades de la compañía de la persona). El primer salto puede ser un campo de relación de uno a muchos o de muchos a uno, el segundo debe ser de uno a muchos (las relaciones de unión no son compatibles) y requiere fieldDisplayMode: 'TABLE' — combinarlo con cualquier otro modo de visualización es un error de validación, ya que un widget anidado siempre se representa como una vista incrustada.

​

Widgets de tabla de registros

{
  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 que se mostrará.
• recordLimit es opcional y limita la cantidad de registros que muestra el widget.
• isUIEditable se aplica a las vistas de tabla y kanban. Habilita la edición de celdas de tabla o la edición, el movimiento y la creación de tarjetas kanban. De forma predeterminada, es true en los diseños RECORD_PAGE y false en otros diseños.
• isUIEditable controla únicamente las acciones de la interfaz de usuario. Los permisos de los registros siguen aplicándose, y la configuración de la vista solo se puede editar en el editor de diseño de página.

​

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,
      },
    },
  ],
});

​

Puntos clave

• pageLayoutUniversalIdentifier es obligatorio y debe apuntar a un page layout que ya exista en el momento de la instalación, ya sea un layout estándar de Twenty o uno definido por tu propia app. Las referencias entre apps a layouts que pertenecen a otra app instalada no son compatibles hoy en día. Cuando falta el layout padre, la instalación falla con un error de validación claro.
• Para los diseños estándar de Twenty, importa los identificadores desde 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
  // …
  
  Cada entrada de diseño también expone sus tabs y sus widgets, para que puedas hacer referencia a cualquier nivel:
  STANDARD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIERS.taskRecordPage.tabs.home
    .universalIdentifier;
  STANDARD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIERS.taskRecordPage.tabs.home.widgets
    .fields.universalIdentifier;
  
  También hay disponible un alias corto STANDARD_PAGE_LAYOUT:
  import { STANDARD_PAGE_LAYOUT } from 'twenty-sdk/define';
  
  STANDARD_PAGE_LAYOUT.companyRecordPage.universalIdentifier;
  
• widgets están limitados solo a esta pestaña: hacen referencia a componentes de frontend, vistas, etc., exactamente igual que los widgets definidos en línea en definePageLayout.
• position controla el orden con respecto a las pestañas existentes en el diseño de página de destino. Elige un valor que sitúe tu pestaña donde la quieras, en relación con las pestañas integradas.
• Usa esto en lugar de definePageLayout cuando solo quieras agregar a un layout existente. Usa definePageLayout cuando eres propietario de todo el layout.
• twenty app pull vuelve a escribir una pestaña que añadiste a un diseño de página que no posees como un archivo definePageLayoutTab(), con sus widgets integrados, bajo los mismos límites que los widgets de 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,
  },
});

​

Puntos clave

• pageLayoutTabUniversalIdentifier es obligatorio y debe apuntar a una pestaña que ya exista en el momento de la instalación: una pestaña estándar de Twenty (STANDARD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIERS.\<object>RecordPage.tabs.\<tab>.universalIdentifier), una pestaña de uno de tus propios layouts o una pestaña de la página de registro que Twenty genera para uno de tus objetos. Las pestañas generadas tienen identificadores deterministas, por lo que puedes calcularlos:
  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 es obligatorio, ya que la pestaña no forma parte de tu manifiesto y no se puede inferir su modo de layout. Haz coincidir el modo de layout de la pestaña: las pestañas de las páginas de registro son listas verticales, así que usa { layoutMode: PageLayoutTabLayoutMode.VERTICAL_LIST, index } con un índice superior al de los widgets integrados (el widget Fields está en 0).
• Para una lista vertical, establezca position.heightBehavior en PageLayoutWidgetVerticalListHeightBehavior.TAB_VIEWPORT para ocupar el área visible de una pestaña, o en PageLayoutWidgetVerticalListHeightBehavior.FIT_CONTENT para usar el contenido o la altura configurada del widget. Importe esta enumeración desde twenty-sdk/define, como en el ejemplo anterior. Si se omite, el widget conserva su valor predeterminado integrado. Solo un widget activo por pestaña puede ocupar el área visible, y su índice debe colocarlo después de todos los widgets con ajuste al contenido. heightBehavior no es compatible con las posiciones GRID ni CANVAS.
• configuration funciona exactamente como un widget definido en línea en definePageLayout o definePageLayoutTab: hace referencia a front components, vistas, campos, etc.
• Usa esto en lugar de definePageLayoutTab cuando la pestaña ya exista y solo quieras colocar un widget en ella. Usa definePageLayoutTab cuando quieras una pestaña propia.
• twenty app pull vuelve a escribir un widget que añadiste a una pestaña que no posees como un archivo definePageLayoutWidget(), bajo los mismos límites que los widgets de un definePageLayout().