diff --git a/packages/twenty-docs/l/ar/developers/extend/apps/layout.mdx b/packages/twenty-docs/l/ar/developers/extend/apps/layout.mdx
index 284324a85b..6250bf3c0d 100644
--- a/packages/twenty-docs/l/ar/developers/extend/apps/layout.mdx
+++ b/packages/twenty-docs/l/ar/developers/extend/apps/layout.mdx
@@ -8,11 +8,12 @@ icon: table-columns
## مفاهيم التخطيط
-| المفهوم | ما الذي يتحكّم فيه | كيان |
-| ---------------------- | ------------------------------------------------------------------------------- | -------------------------- |
-| **عرض** | تكوين قائمة محفوظة لكائن — الحقول المرئية، والترتيب، وعوامل التصفية، والمجموعات | `defineView` |
-| **عنصر قائمة التنقّل** | عنصر في الشريط الجانبي الأيسر يرتبط بعرض أو بعنوان URL خارجي | `defineNavigationMenuItem` |
-| **تخطيط الصفحة** | علامات التبويب وعناصر الواجهة التي تشكّل صفحة تفاصيل السجل | `definePageLayout` |
+| المفهوم | ما الذي يتحكّم فيه | كيان |
+| ---------------------------- | ------------------------------------------------------------------------------- | -------------------------- |
+| **عرض** | تكوين قائمة محفوظة لكائن — الحقول المرئية، والترتيب، وعوامل التصفية، والمجموعات | `defineView` |
+| **عنصر قائمة التنقّل** | عنصر في الشريط الجانبي الأيسر يرتبط بعرض أو بعنوان URL خارجي | `defineNavigationMenuItem` |
+| **تخطيط الصفحة** | علامات التبويب وعناصر الواجهة التي تشكّل صفحة تفاصيل السجل | `definePageLayout` |
+| **علامة تبويب تخطيط الصفحة** | علامة تبويب مستقلة مرفقة بتخطيط صفحة موجودة (قياسي أو خاص بتطبيقك) | `definePageLayoutTab` |
تشير العروض، وعناصر التنقّل، وتخطيطات الصفحات إلى بعضها البعض عبر `universalIdentifier`:
@@ -127,5 +128,51 @@ export default definePageLayout({
* يمكن لكل `widget` داخل لسان أن يعرض مكوّنًا أماميًا أو قائمة علاقات أو أنواع ويدجت مدمجة أخرى.
* `position` على الألسنة يتحكّم في ترتيبها. استخدم قيمًا أعلى (مثل 50) لوضع الألسنة المخصّصة بعد الألسنة المدمجة.
+
+
+
+`definePageLayoutTab` lets your app attach a single tab — with optional widgets — to an **existing** page layout. The most common use case is adding a custom tab (for example, an analytics or AI summary tab) to one of Twenty's built-in record pages, or to a page layout your own app already ships.
+
+The targeted page layout must be either a **standard** Twenty page layout or one defined by **your own app**; cross-app references to page layouts owned by another installed app are not supported today.
+
+```ts src/page-layouts/example-extra-tab.ts
+import {
+ definePageLayoutTab,
+ PageLayoutTabLayoutMode,
+} from 'twenty-sdk/define';
+import { HELLO_WORLD_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER } from '../front-components/hello-world';
+
+const COMPANY_RECORD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIER =
+ '20202020-ab01-4001-8001-c0aba11c0100';
+
+export default definePageLayoutTab({
+ universalIdentifier: 'b1b2b3b4-b5b6-4000-8000-000000000001',
+ pageLayoutUniversalIdentifier:
+ COMPANY_RECORD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIER,
+ title: 'Hello World',
+ position: 1000,
+ icon: 'IconWorld',
+ layoutMode: PageLayoutTabLayoutMode.CANVAS,
+ widgets: [
+ {
+ universalIdentifier: 'b1b2b3b4-b5b6-4000-8000-000000000002',
+ title: 'Hello World',
+ type: 'FRONT_COMPONENT',
+ configuration: {
+ configurationType: 'FRONT_COMPONENT',
+ frontComponentUniversalIdentifier:
+ HELLO_WORLD_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER,
+ },
+ },
+ ],
+});
+```
+
+النقاط الرئيسية:
+* `pageLayoutUniversalIdentifier` is **required** when using `definePageLayoutTab` and must point to a page layout that already exists at install time (standard or your app's). When the parent page layout is missing, installation fails with a clear validation error.
+* `widgets` are scoped to this tab only — they reference front components, views, etc. exactly like widgets defined inline in `definePageLayout`.
+* `position` controls ordering against existing tabs on the targeted layout. Pick a value that places your tab where you want it relative to built-in tabs.
+* Use this instead of `definePageLayout` when you only want to **add** to an existing layout. Use `definePageLayout` when you own the entire layout (typically a `RECORD_PAGE` for an object you ship in your app, or a `STANDALONE_PAGE`).
+
diff --git a/packages/twenty-docs/l/cs/developers/extend/apps/layout.mdx b/packages/twenty-docs/l/cs/developers/extend/apps/layout.mdx
index 6fb8e639a4..a15ab99379 100644
--- a/packages/twenty-docs/l/cs/developers/extend/apps/layout.mdx
+++ b/packages/twenty-docs/l/cs/developers/extend/apps/layout.mdx
@@ -8,11 +8,12 @@ Prvky rozvržení řídí, jak se vaše aplikace zobrazuje v uživatelském rozh
## Pojmy rozvržení
-| Pojem | Co řídí | Entita |
-| ----------------------------- | ------------------------------------------------------------------------------ | -------------------------- |
-| **Pohled** | Uložené nastavení seznamu pro objekt — viditelná pole, pořadí, filtry, skupiny | `defineView` |
-| **Položka navigační nabídky** | Položka v levém postranním panelu, která odkazuje na pohled nebo externí URL | `defineNavigationMenuItem` |
-| **Rozvržení stránky** | Karty a widgety, které tvoří stránku s podrobnostmi záznamu | `definePageLayout` |
+| Pojem | Co řídí | Entita |
+| ----------------------------- | --------------------------------------------------------------------------------- | -------------------------- |
+| **Pohled** | Uložené nastavení seznamu pro objekt — viditelná pole, pořadí, filtry, skupiny | `defineView` |
+| **Položka navigační nabídky** | Položka v levém postranním panelu, která odkazuje na pohled nebo externí URL | `defineNavigationMenuItem` |
+| **Rozvržení stránky** | Karty a widgety, které tvoří stránku s podrobnostmi záznamu | `definePageLayout` |
+| **Page Layout Tab** | A standalone tab attached to an existing page layout (standard or your own app's) | `definePageLayoutTab` |
Pohledy, položky navigační nabídky a rozvržení stránek se na sebe odkazují pomocí `universalIdentifier`:
@@ -127,5 +128,51 @@ Hlavní body:
* Každý `widget` uvnitř karty může vykreslit frontendovou komponentu, seznam relací nebo jiné vestavěné typy widgetů.
* `position` na kartách určuje jejich pořadí. Použijte vyšší hodnoty (např. 50) pro umístění vlastních karet za vestavěné.
+
+
+
+`definePageLayoutTab` lets your app attach a single tab — with optional widgets — to an **existing** page layout. The most common use case is adding a custom tab (for example, an analytics or AI summary tab) to one of Twenty's built-in record pages, or to a page layout your own app already ships.
+
+The targeted page layout must be either a **standard** Twenty page layout or one defined by **your own app**; cross-app references to page layouts owned by another installed app are not supported today.
+
+```ts src/page-layouts/example-extra-tab.ts
+import {
+ definePageLayoutTab,
+ PageLayoutTabLayoutMode,
+} from 'twenty-sdk/define';
+import { HELLO_WORLD_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER } from '../front-components/hello-world';
+
+const COMPANY_RECORD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIER =
+ '20202020-ab01-4001-8001-c0aba11c0100';
+
+export default definePageLayoutTab({
+ universalIdentifier: 'b1b2b3b4-b5b6-4000-8000-000000000001',
+ pageLayoutUniversalIdentifier:
+ COMPANY_RECORD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIER,
+ title: 'Hello World',
+ position: 1000,
+ icon: 'IconWorld',
+ layoutMode: PageLayoutTabLayoutMode.CANVAS,
+ widgets: [
+ {
+ universalIdentifier: 'b1b2b3b4-b5b6-4000-8000-000000000002',
+ title: 'Hello World',
+ type: 'FRONT_COMPONENT',
+ configuration: {
+ configurationType: 'FRONT_COMPONENT',
+ frontComponentUniversalIdentifier:
+ HELLO_WORLD_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER,
+ },
+ },
+ ],
+});
+```
+
+Hlavní body:
+* `pageLayoutUniversalIdentifier` is **required** when using `definePageLayoutTab` and must point to a page layout that already exists at install time (standard or your app's). When the parent page layout is missing, installation fails with a clear validation error.
+* `widgets` are scoped to this tab only — they reference front components, views, etc. exactly like widgets defined inline in `definePageLayout`.
+* `position` controls ordering against existing tabs on the targeted layout. Pick a value that places your tab where you want it relative to built-in tabs.
+* Use this instead of `definePageLayout` when you only want to **add** to an existing layout. Use `definePageLayout` when you own the entire layout (typically a `RECORD_PAGE` for an object you ship in your app, or a `STANDALONE_PAGE`).
+
diff --git a/packages/twenty-docs/l/de/developers/extend/apps/layout.mdx b/packages/twenty-docs/l/de/developers/extend/apps/layout.mdx
index 8eb041390e..c56b8d9fe1 100644
--- a/packages/twenty-docs/l/de/developers/extend/apps/layout.mdx
+++ b/packages/twenty-docs/l/de/developers/extend/apps/layout.mdx
@@ -13,6 +13,7 @@ Layout-Entitäten steuern, wie Ihre App innerhalb der Benutzeroberfläche von Tw
| **Ansicht** | Eine gespeicherte Listen-Konfiguration für ein Objekt — sichtbare Felder, Reihenfolge, Filter, Gruppen | `defineView` |
| **Navigationsmenüeintrag** | Ein Eintrag in der linken Seitenleiste, der auf eine Ansicht oder eine externe URL verweist | `defineNavigationMenuItem` |
| **Seitenlayout** | Die Tabs und Widgets, aus denen die Detailseite eines Datensatzes besteht | `definePageLayout` |
+| **Page Layout Tab** | A standalone tab attached to an existing page layout (standard or your own app's) | `definePageLayoutTab` |
Ansichten, Navigationsmenüeinträge und Seitenlayouts verweisen über `universalIdentifier` aufeinander:
@@ -127,5 +128,51 @@ Hauptpunkte:
* Jedes `widget` innerhalb eines Tabs kann eine Frontend-Komponente, eine Relationenliste oder andere eingebaute Widget-Typen rendern.
* `position` auf Tabs steuert deren Reihenfolge. Verwenden Sie höhere Werte (z. B. 50), um benutzerdefinierte Tabs hinter den integrierten zu platzieren.
+
+
+
+`definePageLayoutTab` lets your app attach a single tab — with optional widgets — to an **existing** page layout. The most common use case is adding a custom tab (for example, an analytics or AI summary tab) to one of Twenty's built-in record pages, or to a page layout your own app already ships.
+
+The targeted page layout must be either a **standard** Twenty page layout or one defined by **your own app**; cross-app references to page layouts owned by another installed app are not supported today.
+
+```ts src/page-layouts/example-extra-tab.ts
+import {
+ definePageLayoutTab,
+ PageLayoutTabLayoutMode,
+} from 'twenty-sdk/define';
+import { HELLO_WORLD_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER } from '../front-components/hello-world';
+
+const COMPANY_RECORD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIER =
+ '20202020-ab01-4001-8001-c0aba11c0100';
+
+export default definePageLayoutTab({
+ universalIdentifier: 'b1b2b3b4-b5b6-4000-8000-000000000001',
+ pageLayoutUniversalIdentifier:
+ COMPANY_RECORD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIER,
+ title: 'Hello World',
+ position: 1000,
+ icon: 'IconWorld',
+ layoutMode: PageLayoutTabLayoutMode.CANVAS,
+ widgets: [
+ {
+ universalIdentifier: 'b1b2b3b4-b5b6-4000-8000-000000000002',
+ title: 'Hello World',
+ type: 'FRONT_COMPONENT',
+ configuration: {
+ configurationType: 'FRONT_COMPONENT',
+ frontComponentUniversalIdentifier:
+ HELLO_WORLD_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER,
+ },
+ },
+ ],
+});
+```
+
+Hauptpunkte:
+* `pageLayoutUniversalIdentifier` is **required** when using `definePageLayoutTab` and must point to a page layout that already exists at install time (standard or your app's). When the parent page layout is missing, installation fails with a clear validation error.
+* `widgets` are scoped to this tab only — they reference front components, views, etc. exactly like widgets defined inline in `definePageLayout`.
+* `position` controls ordering against existing tabs on the targeted layout. Pick a value that places your tab where you want it relative to built-in tabs.
+* Use this instead of `definePageLayout` when you only want to **add** to an existing layout. Use `definePageLayout` when you own the entire layout (typically a `RECORD_PAGE` for an object you ship in your app, or a `STANDALONE_PAGE`).
+
diff --git a/packages/twenty-docs/l/it/developers/extend/apps/layout.mdx b/packages/twenty-docs/l/it/developers/extend/apps/layout.mdx
index bb43c2724b..73026a2a33 100644
--- a/packages/twenty-docs/l/it/developers/extend/apps/layout.mdx
+++ b/packages/twenty-docs/l/it/developers/extend/apps/layout.mdx
@@ -13,6 +13,7 @@ Le entità di layout controllano come la tua app si presenta all'interno dell'in
| **Vista** | Una configurazione di elenco salvata per un oggetto — campi visibili, ordine, filtri, gruppi | `defineView` |
| **Voce del menu di navigazione** | Una voce nella barra laterale sinistra che collega a una vista o a un URL esterno | `defineNavigationMenuItem` |
| **Layout di pagina** | Le schede e i widget che compongono la pagina dei dettagli di un record | `definePageLayout` |
+| **Page Layout Tab** | A standalone tab attached to an existing page layout (standard or your own app's) | `definePageLayoutTab` |
Le viste, le voci del menu di navigazione e i layout di pagina fanno riferimento tra loro tramite `universalIdentifier`:
@@ -127,5 +128,51 @@ Punti chiave:
* Ogni `widget` all'interno di una scheda può renderizzare un componente front-end, un elenco di relazioni o altri tipi di widget integrati.
* `position` sulle schede controlla il loro ordine. Usa valori più alti (ad es., 50) per posizionare le schede personalizzate dopo quelle integrate.
+
+
+
+`definePageLayoutTab` lets your app attach a single tab — with optional widgets — to an **existing** page layout. The most common use case is adding a custom tab (for example, an analytics or AI summary tab) to one of Twenty's built-in record pages, or to a page layout your own app already ships.
+
+The targeted page layout must be either a **standard** Twenty page layout or one defined by **your own app**; cross-app references to page layouts owned by another installed app are not supported today.
+
+```ts src/page-layouts/example-extra-tab.ts
+import {
+ definePageLayoutTab,
+ PageLayoutTabLayoutMode,
+} from 'twenty-sdk/define';
+import { HELLO_WORLD_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER } from '../front-components/hello-world';
+
+const COMPANY_RECORD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIER =
+ '20202020-ab01-4001-8001-c0aba11c0100';
+
+export default definePageLayoutTab({
+ universalIdentifier: 'b1b2b3b4-b5b6-4000-8000-000000000001',
+ pageLayoutUniversalIdentifier:
+ COMPANY_RECORD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIER,
+ title: 'Hello World',
+ position: 1000,
+ icon: 'IconWorld',
+ layoutMode: PageLayoutTabLayoutMode.CANVAS,
+ 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` is **required** when using `definePageLayoutTab` and must point to a page layout that already exists at install time (standard or your app's). When the parent page layout is missing, installation fails with a clear validation error.
+* `widgets` are scoped to this tab only — they reference front components, views, etc. exactly like widgets defined inline in `definePageLayout`.
+* `position` controls ordering against existing tabs on the targeted layout. Pick a value that places your tab where you want it relative to built-in tabs.
+* Use this instead of `definePageLayout` when you only want to **add** to an existing layout. Use `definePageLayout` when you own the entire layout (typically a `RECORD_PAGE` for an object you ship in your app, or a `STANDALONE_PAGE`).
+
diff --git a/packages/twenty-docs/l/pt/developers/extend/apps/layout.mdx b/packages/twenty-docs/l/pt/developers/extend/apps/layout.mdx
index 40b46abc7c..b0a367d7b8 100644
--- a/packages/twenty-docs/l/pt/developers/extend/apps/layout.mdx
+++ b/packages/twenty-docs/l/pt/developers/extend/apps/layout.mdx
@@ -13,6 +13,7 @@ As entidades de layout controlam como seu app aparece na UI do Twenty — o que
| **Vista** | Uma configuração de lista salva para um objeto — campos visíveis, ordem, filtros, grupos | `defineView` |
| **Item do menu de navegação** | Uma entrada na barra lateral esquerda que aponta para uma vista ou uma URL externa | `defineNavigationMenuItem` |
| **Layout da Página** | As abas e widgets que compõem a página de detalhes de um registro | `definePageLayout` |
+| **Page Layout Tab** | A standalone tab attached to an existing page layout (standard or your own app's) | `definePageLayoutTab` |
Vistas, itens de navegação e layouts de página referenciam-se mutuamente por `universalIdentifier`:
@@ -127,5 +128,51 @@ Pontos-chave:
* Cada `widget` dentro de uma aba pode renderizar um componente de front-end, uma lista de relações ou outros tipos de widget incorporados.
* `position` nas abas controla sua ordem. Use valores mais altos (por exemplo, 50) para colocar abas personalizadas após as nativas.
+
+
+
+`definePageLayoutTab` lets your app attach a single tab — with optional widgets — to an **existing** page layout. The most common use case is adding a custom tab (for example, an analytics or AI summary tab) to one of Twenty's built-in record pages, or to a page layout your own app already ships.
+
+The targeted page layout must be either a **standard** Twenty page layout or one defined by **your own app**; cross-app references to page layouts owned by another installed app are not supported today.
+
+```ts src/page-layouts/example-extra-tab.ts
+import {
+ definePageLayoutTab,
+ PageLayoutTabLayoutMode,
+} from 'twenty-sdk/define';
+import { HELLO_WORLD_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER } from '../front-components/hello-world';
+
+const COMPANY_RECORD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIER =
+ '20202020-ab01-4001-8001-c0aba11c0100';
+
+export default definePageLayoutTab({
+ universalIdentifier: 'b1b2b3b4-b5b6-4000-8000-000000000001',
+ pageLayoutUniversalIdentifier:
+ COMPANY_RECORD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIER,
+ title: 'Hello World',
+ position: 1000,
+ icon: 'IconWorld',
+ layoutMode: PageLayoutTabLayoutMode.CANVAS,
+ widgets: [
+ {
+ universalIdentifier: 'b1b2b3b4-b5b6-4000-8000-000000000002',
+ title: 'Hello World',
+ type: 'FRONT_COMPONENT',
+ configuration: {
+ configurationType: 'FRONT_COMPONENT',
+ frontComponentUniversalIdentifier:
+ HELLO_WORLD_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER,
+ },
+ },
+ ],
+});
+```
+
+Pontos-chave:
+* `pageLayoutUniversalIdentifier` is **required** when using `definePageLayoutTab` and must point to a page layout that already exists at install time (standard or your app's). When the parent page layout is missing, installation fails with a clear validation error.
+* `widgets` are scoped to this tab only — they reference front components, views, etc. exactly like widgets defined inline in `definePageLayout`.
+* `position` controls ordering against existing tabs on the targeted layout. Pick a value that places your tab where you want it relative to built-in tabs.
+* Use this instead of `definePageLayout` when you only want to **add** to an existing layout. Use `definePageLayout` when you own the entire layout (typically a `RECORD_PAGE` for an object you ship in your app, or a `STANDALONE_PAGE`).
+
diff --git a/packages/twenty-docs/l/ru/developers/extend/apps/layout.mdx b/packages/twenty-docs/l/ru/developers/extend/apps/layout.mdx
index d1043a2740..0cc574acb0 100644
--- a/packages/twenty-docs/l/ru/developers/extend/apps/layout.mdx
+++ b/packages/twenty-docs/l/ru/developers/extend/apps/layout.mdx
@@ -13,6 +13,7 @@ icon: table-columns
| **Представление** | Сохранённая конфигурация списка для объекта — видимые поля, порядок, фильтры, группы | `defineView` |
| **Пункт меню навигации** | Элемент в левой боковой панели, который ссылается на представление или внешний URL | `defineNavigationMenuItem` |
| **Макет страницы** | Вкладки и виджеты, из которых состоит страница сведений о записи | `definePageLayout` |
+| **Page Layout Tab** | A standalone tab attached to an existing page layout (standard or your own app's) | `definePageLayoutTab` |
Представления, пункты меню навигации и макеты страниц ссылаются друг на друга по `universalIdentifier`:
@@ -127,5 +128,51 @@ export default definePageLayout({
* Каждый `widget` внутри вкладки может отображать компонент фронтенда, список связей или другие встроенные типы виджетов.
* `position` у вкладок управляет их порядком. Используйте большие значения (например, 50), чтобы разместить пользовательские вкладки после встроенных.
+
+
+
+`definePageLayoutTab` lets your app attach a single tab — with optional widgets — to an **existing** page layout. The most common use case is adding a custom tab (for example, an analytics or AI summary tab) to one of Twenty's built-in record pages, or to a page layout your own app already ships.
+
+The targeted page layout must be either a **standard** Twenty page layout or one defined by **your own app**; cross-app references to page layouts owned by another installed app are not supported today.
+
+```ts src/page-layouts/example-extra-tab.ts
+import {
+ definePageLayoutTab,
+ PageLayoutTabLayoutMode,
+} from 'twenty-sdk/define';
+import { HELLO_WORLD_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER } from '../front-components/hello-world';
+
+const COMPANY_RECORD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIER =
+ '20202020-ab01-4001-8001-c0aba11c0100';
+
+export default definePageLayoutTab({
+ universalIdentifier: 'b1b2b3b4-b5b6-4000-8000-000000000001',
+ pageLayoutUniversalIdentifier:
+ COMPANY_RECORD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIER,
+ title: 'Hello World',
+ position: 1000,
+ icon: 'IconWorld',
+ layoutMode: PageLayoutTabLayoutMode.CANVAS,
+ widgets: [
+ {
+ universalIdentifier: 'b1b2b3b4-b5b6-4000-8000-000000000002',
+ title: 'Hello World',
+ type: 'FRONT_COMPONENT',
+ configuration: {
+ configurationType: 'FRONT_COMPONENT',
+ frontComponentUniversalIdentifier:
+ HELLO_WORLD_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER,
+ },
+ },
+ ],
+});
+```
+
+Основные моменты:
+* `pageLayoutUniversalIdentifier` is **required** when using `definePageLayoutTab` and must point to a page layout that already exists at install time (standard or your app's). When the parent page layout is missing, installation fails with a clear validation error.
+* `widgets` are scoped to this tab only — they reference front components, views, etc. exactly like widgets defined inline in `definePageLayout`.
+* `position` controls ordering against existing tabs on the targeted layout. Pick a value that places your tab where you want it relative to built-in tabs.
+* Use this instead of `definePageLayout` when you only want to **add** to an existing layout. Use `definePageLayout` when you own the entire layout (typically a `RECORD_PAGE` for an object you ship in your app, or a `STANDALONE_PAGE`).
+
diff --git a/packages/twenty-docs/l/tr/developers/extend/apps/layout.mdx b/packages/twenty-docs/l/tr/developers/extend/apps/layout.mdx
index 9771ac090f..2bafd07333 100644
--- a/packages/twenty-docs/l/tr/developers/extend/apps/layout.mdx
+++ b/packages/twenty-docs/l/tr/developers/extend/apps/layout.mdx
@@ -13,6 +13,7 @@ Düzen varlıkları, uygulamanızın Twenty arayüzünde nasıl göründüğün
| **Görünüm** | Bir nesne için kaydedilmiş liste yapılandırması — görünür alanlar, sıralama, filtreler, gruplar | `defineView` |
| **Gezinme Menüsü Öğesi** | Sol kenar çubuğunda, bir görünüme veya harici bir URL'ye bağlanan bir öğe | `defineNavigationMenuItem` |
| **Sayfa Düzeni** | Bir kaydın ayrıntı sayfasını oluşturan sekmeler ve widget'lar | `definePageLayout` |
+| **Page Layout Tab** | A standalone tab attached to an existing page layout (standard or your own app's) | `definePageLayoutTab` |
Görünümler, gezinme menüsü öğeleri ve sayfa düzenleri birbirlerine `universalIdentifier` ile başvurur:
@@ -127,5 +128,51 @@ export default definePageLayout({
* Bir sekmenin içindeki her `widget`, bir ön uç bileşeni, bir ilişki listesi veya diğer yerleşik widget türlerini oluşturabilir.
* Sekmelerdeki `position`, sıralarını kontrol eder. Özel sekmeleri yerleşik olanların sonrasına yerleştirmek için daha yüksek değerler kullanın (ör. 50).
+
+
+
+`definePageLayoutTab` lets your app attach a single tab — with optional widgets — to an **existing** page layout. The most common use case is adding a custom tab (for example, an analytics or AI summary tab) to one of Twenty's built-in record pages, or to a page layout your own app already ships.
+
+The targeted page layout must be either a **standard** Twenty page layout or one defined by **your own app**; cross-app references to page layouts owned by another installed app are not supported today.
+
+```ts src/page-layouts/example-extra-tab.ts
+import {
+ definePageLayoutTab,
+ PageLayoutTabLayoutMode,
+} from 'twenty-sdk/define';
+import { HELLO_WORLD_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER } from '../front-components/hello-world';
+
+const COMPANY_RECORD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIER =
+ '20202020-ab01-4001-8001-c0aba11c0100';
+
+export default definePageLayoutTab({
+ universalIdentifier: 'b1b2b3b4-b5b6-4000-8000-000000000001',
+ pageLayoutUniversalIdentifier:
+ COMPANY_RECORD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIER,
+ title: 'Hello World',
+ position: 1000,
+ icon: 'IconWorld',
+ layoutMode: PageLayoutTabLayoutMode.CANVAS,
+ widgets: [
+ {
+ universalIdentifier: 'b1b2b3b4-b5b6-4000-8000-000000000002',
+ title: 'Hello World',
+ type: 'FRONT_COMPONENT',
+ configuration: {
+ configurationType: 'FRONT_COMPONENT',
+ frontComponentUniversalIdentifier:
+ HELLO_WORLD_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER,
+ },
+ },
+ ],
+});
+```
+
+Önemli noktalar:
+* `pageLayoutUniversalIdentifier` is **required** when using `definePageLayoutTab` and must point to a page layout that already exists at install time (standard or your app's). When the parent page layout is missing, installation fails with a clear validation error.
+* `widgets` are scoped to this tab only — they reference front components, views, etc. exactly like widgets defined inline in `definePageLayout`.
+* `position` controls ordering against existing tabs on the targeted layout. Pick a value that places your tab where you want it relative to built-in tabs.
+* Use this instead of `definePageLayout` when you only want to **add** to an existing layout. Use `definePageLayout` when you own the entire layout (typically a `RECORD_PAGE` for an object you ship in your app, or a `STANDALONE_PAGE`).
+
diff --git a/packages/twenty-docs/l/zh/developers/extend/apps/layout.mdx b/packages/twenty-docs/l/zh/developers/extend/apps/layout.mdx
index 93677c8468..bc4c3f0d2b 100644
--- a/packages/twenty-docs/l/zh/developers/extend/apps/layout.mdx
+++ b/packages/twenty-docs/l/zh/developers/extend/apps/layout.mdx
@@ -8,11 +8,12 @@ icon: table-columns
## 布局概念
-| 概念 | 控制内容 | 实体 |
-| --------- | -------------------------- | -------------------------- |
-| **视图** | 对象的已保存列表配置——可见字段、顺序、筛选器、分组 | `defineView` |
-| **导航菜单项** | 左侧侧边栏中的一项，链接到某个视图或外部 URL | `defineNavigationMenuItem` |
-| **页面布局** | 构成记录详情页的选项卡和小部件 | `definePageLayout` |
+| 概念 | 控制内容 | 实体 |
+| ----------- | ----------------------------------- | -------------------------- |
+| **视图** | 对象的已保存列表配置——可见字段、顺序、筛选器、分组 | `defineView` |
+| **导航菜单项** | 左侧侧边栏中的一项，链接到某个视图或外部 URL | `defineNavigationMenuItem` |
+| **页面布局** | 构成记录详情页的选项卡和小部件 | `definePageLayout` |
+| **页面布局选项卡** | 附加到现有页面布局（标准页面布局或你自己的应用的页面布局）的独立选项卡 | `definePageLayoutTab` |
视图、导航菜单项和页面布局通过 `universalIdentifier` 相互引用：
@@ -127,5 +128,51 @@ export default definePageLayout({
* 选项卡内的每个 `widget` 可以渲染一个前端组件、关系列表或其他内置小部件类型。
* 选项卡上的 `position` 控制其顺序。 使用更高的值（例如 50）可将自定义选项卡放在内置选项卡之后。
+
+
+
+`definePageLayoutTab` lets your app attach a single tab — with optional widgets — to an **existing** page layout. The most common use case is adding a custom tab (for example, an analytics or AI summary tab) to one of Twenty's built-in record pages, or to a page layout your own app already ships.
+
+The targeted page layout must be either a **standard** Twenty page layout or one defined by **your own app**; cross-app references to page layouts owned by another installed app are not supported today.
+
+```ts src/page-layouts/example-extra-tab.ts
+import {
+ definePageLayoutTab,
+ PageLayoutTabLayoutMode,
+} from 'twenty-sdk/define';
+import { HELLO_WORLD_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER } from '../front-components/hello-world';
+
+const COMPANY_RECORD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIER =
+ '20202020-ab01-4001-8001-c0aba11c0100';
+
+export default definePageLayoutTab({
+ universalIdentifier: 'b1b2b3b4-b5b6-4000-8000-000000000001',
+ pageLayoutUniversalIdentifier:
+ COMPANY_RECORD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIER,
+ title: 'Hello World',
+ position: 1000,
+ icon: 'IconWorld',
+ layoutMode: PageLayoutTabLayoutMode.CANVAS,
+ widgets: [
+ {
+ universalIdentifier: 'b1b2b3b4-b5b6-4000-8000-000000000002',
+ title: 'Hello World',
+ type: 'FRONT_COMPONENT',
+ configuration: {
+ configurationType: 'FRONT_COMPONENT',
+ frontComponentUniversalIdentifier:
+ HELLO_WORLD_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER,
+ },
+ },
+ ],
+});
+```
+
+关键点：
+* `pageLayoutUniversalIdentifier` is **required** when using `definePageLayoutTab` and must point to a page layout that already exists at install time (standard or your app's). When the parent page layout is missing, installation fails with a clear validation error.
+* `widgets` are scoped to this tab only — they reference front components, views, etc. exactly like widgets defined inline in `definePageLayout`.
+* `position` controls ordering against existing tabs on the targeted layout. Pick a value that places your tab where you want it relative to built-in tabs.
+* Use this instead of `definePageLayout` when you only want to **add** to an existing layout. Use `definePageLayout` when you own the entire layout (typically a `RECORD_PAGE` for an object you ship in your app, or a `STANDALONE_PAGE`).
+