docs(apps): document missing enum values and complete entity references (#22691)
Part 4 of the app-docs audit series (after #22688, #22689, #22690). Focus: values that exist in the SDK but never made it into the docs. All value lists were extracted from `twenty-shared` / `twenty-sdk` source. ## What this adds/fixes **data/objects.mdx** - New "Field types" section with the complete `FieldType` value set (24 values, grouped by category, with the composite/`SELECT` caveats and the lowercase `universalSettings.dataType` values for `NUMBER`). Previously no page listed the available field types — readers had to reverse-engineer them from scattered examples. **layout/views.mdx** - `ViewFilterOperand` was imported from `twenty-shared/types` in the example; it's re-exported from `twenty-sdk/define`, which is the supported import surface for apps. - New "Optional properties" table covering what the page omitted: `type` (`ViewType.TABLE`/`KANBAN`/`CALENDAR`), `visibility`, `openRecordIn`, `sorts`, kanban aggregate settings, and calendar settings. **getting-started/scaffolding.mdx** - The `dev:add` table listed 10 of 14 entity types; added `pageLayoutTab`, `commandMenuItem`, `viewField`, and `connectionProvider` (paths follow the CLI's kebab-case convention). **layout/navigation-menu-items.mdx** - Note about `NavigationMenuItemType.RECORD`: it exists in the enum but is internal (user favorites) and has no manifest field to reference a record, so apps can't use it — documented to prevent confusion about the "missing" value. Only English sources were touched; `l/<locale>` copies come from Crowdin. --- _Generated by [Claude Code](https://claude.ai/code/session_01ExboyDAT19khDuKXaYXETT)_ <!-- This is an auto-generated description by cubic. --> <a href="https://cubic.dev/pr/twentyhq/twenty/pull/22691?utm_source=github" target="_blank" rel="noopener noreferrer" data-no-image-dialog="true"><picture><source media="(prefers-color-scheme: dark)" srcset="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"><source media="(prefers-color-scheme: light)" srcset="https://www.cubic.dev/buttons/review-in-cubic-light.svg"><img alt="Review in cubic" src="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"></picture></a> <!-- End of auto-generated description by cubic. --> Co-authored-by: Martin <martin@twenty.com>
This commit is contained in:
@@ -86,6 +86,22 @@ export default defineObject({
|
||||
**Base fields are added automatically.** When you define a custom object, Twenty creates standard fields like `id`, `name`, `createdAt`, `updatedAt`, `createdBy`, `updatedBy`, and `deletedAt` for you. You don't need to declare them in your `fields` array — only your custom fields. You can override a default field by declaring one with the same name, but this is rarely a good idea.
|
||||
</Note>
|
||||
|
||||
## Field types
|
||||
|
||||
The full set of `FieldType` values, exported from `twenty-sdk/define`:
|
||||
|
||||
| Category | Types |
|
||||
|----------|-------|
|
||||
| Text | `TEXT`, `RICH_TEXT`, `ARRAY` (of strings), `RAW_JSON` |
|
||||
| Numeric | `NUMBER` (`universalSettings.dataType`: `'float'` / `'int'` / `'bigint'`), `NUMERIC` (arbitrary precision), `RATING`, `POSITION` |
|
||||
| Dates | `DATE`, `DATE_TIME` |
|
||||
| Choice | `BOOLEAN`, `SELECT`, `MULTI_SELECT` |
|
||||
| Composite | `FULL_NAME`, `ADDRESS`, `EMAILS`, `PHONES`, `LINKS`, `CURRENCY`, `ACTOR`, `FILES` |
|
||||
| Identifiers & relations | `UUID`, `RELATION`, `MORPH_RELATION` (see [Relations](/developers/extend/apps/data/relations)) |
|
||||
| System | `TS_VECTOR` (full-text search vector, managed by the server) |
|
||||
|
||||
Composite types store multiple sub-fields (e.g. `FULL_NAME` = first + last name; `CURRENCY` = `amountMicros` + `currencyCode`). `SELECT` and `MULTI_SELECT` require an `options` array as in the example above.
|
||||
|
||||
## Default values
|
||||
|
||||
Literal string defaults must be wrapped in single quotes **inside** the string — `defaultValue: "'Draft'"`, not `defaultValue: "Draft"`. That's why the `status` field above uses `` `'${PostCardStatus.DRAFT}'` ``.
|
||||
|
||||
@@ -34,6 +34,10 @@ yarn twenty dev:add frontComponent
|
||||
| View | `yarn twenty dev:add view` | `src/views/<name>.ts` |
|
||||
| Navigation menu item | `yarn twenty dev:add navigationMenuItem` | `src/navigation-menu-items/<name>.ts` |
|
||||
| Page layout | `yarn twenty dev:add pageLayout` | `src/page-layouts/<name>.ts` |
|
||||
| Page layout tab | `yarn twenty dev:add pageLayoutTab` | `src/page-layout-tabs/<name>.ts` |
|
||||
| Command menu item | `yarn twenty dev:add commandMenuItem` | `src/command-menu-items/<name>.ts` |
|
||||
| View field | `yarn twenty dev:add viewField` | `src/view-fields/<name>.ts` |
|
||||
| Connection provider | `yarn twenty dev:add connectionProvider` | `src/connection-providers/<name>.ts` |
|
||||
|
||||
## What the scaffolder generates
|
||||
|
||||
|
||||
@@ -34,6 +34,7 @@ export default defineNavigationMenuItem({
|
||||
| `NavigationMenuItemType.PAGE_LAYOUT` | Opens a standalone page layout | `pageLayoutUniversalIdentifier` |
|
||||
|
||||
- `position` controls ordering in the sidebar.
|
||||
- The enum also contains `NavigationMenuItemType.RECORD`, used internally for user-created record favorites — it isn't usable from an app manifest (there is no field to reference a record).
|
||||
- `icon` and `color` are optional and customize how the entry looks.
|
||||
- `folderUniversalIdentifier` is also available on any item to nest it inside a `FOLDER`-type parent.
|
||||
|
||||
|
||||
@@ -33,17 +33,32 @@ export default defineView({
|
||||
## Key points
|
||||
|
||||
- `objectUniversalIdentifier` specifies which object this view applies to. It can be a custom object you defined or a standard Twenty object.
|
||||
- `key` determines the view type — `ViewKey.INDEX` is the main list view for the object.
|
||||
- `key: ViewKey.INDEX` marks the view as the object's main list view (the one an `OBJECT` navigation item opens).
|
||||
- `fields` controls which columns appear and in what order. Each field references a `fieldMetadataUniversalIdentifier`.
|
||||
- You can also declare `filters`, `filterGroups`, `groups`, and `fieldGroups` for advanced configurations.
|
||||
- You can also declare `filters`, `filterGroups`, `sorts`, `groups`, and `fieldGroups` for advanced configurations.
|
||||
- `position` controls ordering when multiple views exist for the same object.
|
||||
|
||||
## Optional properties
|
||||
|
||||
| Property | Values | Description |
|
||||
|----------|--------|-------------|
|
||||
| `type` | `ViewType.TABLE` (default), `ViewType.KANBAN`, `ViewType.CALENDAR` | How records are laid out. (`FIELDS_WIDGET` / `TABLE_WIDGET` also exist but are used internally by page-layout widgets.) |
|
||||
| `visibility` | `ViewVisibility.WORKSPACE` (default), `ViewVisibility.UNLISTED` | Whether the view is listed for the whole workspace or hidden from pickers. |
|
||||
| `openRecordIn` | `ViewOpenRecordIn.SIDE_PANEL` (default), `ViewOpenRecordIn.RECORD_PAGE` | Where clicking a record opens it. |
|
||||
| `sorts` | `{ fieldMetadataUniversalIdentifier, direction: ViewSortDirection.ASC \| DESC }[]` | Default sort order. |
|
||||
| `isCompact` | `boolean` | Compact row display. |
|
||||
| `mainGroupByFieldMetadataUniversalIdentifier` + `shouldHideEmptyGroups` | — | Group records (e.g. kanban columns) by a field. |
|
||||
| `kanbanAggregateOperation`, `kanbanAggregateOperationFieldMetadataUniversalIdentifier`, `kanbanColumnWidth` | `AggregateOperations.*` | Kanban column aggregates and sizing. |
|
||||
| `calendarLayout`, `calendarFieldMetadataUniversalIdentifier` | `ViewCalendarLayout.DAY` / `WEEK` / `MONTH` | Calendar views: layout and the date field that positions records. |
|
||||
|
||||
All enums above are exported from `twenty-sdk/define`.
|
||||
|
||||
## Filters
|
||||
|
||||
A view can ship with pre-applied filters. Each filter has three coordinates: the **field** being filtered, the **operand** (how to compare), and the **value** (what to compare against). All three must line up — using an operand that doesn't apply to a field type will be rejected at sync time.
|
||||
|
||||
```ts
|
||||
import { ViewFilterOperand } from 'twenty-shared/types';
|
||||
import { ViewFilterOperand } from 'twenty-sdk/define';
|
||||
|
||||
filters: [
|
||||
{
|
||||
|
||||
Reference in New Issue
Block a user