Cílení na systémová metadata

Vyřešte deterministické univerzální identifikátory metadat, která Twenty automaticky zřizuje u každého objektu, aby se na ně vaše aplikace mohla odkazovat bez hardcodování.

Každý objekt v Twenty má systémová metadata, která sami nedefinujete, například sadu polí a hlavní zobrazení seznamu s jeho sloupci. Server všechno vytvoří při zřízení objektu a tato sada roste spolu s tím, jak roste Twenty.

Protože je nedefinujete, neexistuje žádná konstanta universalIdentifier, kterou byste mohli importovat. Místo toho server každý identifikátor odvozuje deterministicky a twenty-sdk zpřístupňuje stejné odvozování, takže váš manifest může zjistit přesnou hodnotu, kterou server používá.

​

Systémová pole

Skalární pole přítomná na každém objektu, z nichž žádné nedefinujete pomocí defineField():

id, createdAt, updatedAt, deletedAt, createdBy, updatedBy, position, searchVector

Jak tedy odkážete na createdAt jako na sloupec ve zobrazení?

​

Problém

Od Twenty 2.19 je univerzální identifikátor systémového pole deterministicky odvozován serverem ze tří vstupů: univerzálního identifikátoru aplikace, univerzálního identifikátoru objektu a názvu pole. Vymyslet si id a natvrdo ho zapsat nebude fungovat: neshoduje se s ničím na serveru a synchronizace zamítne osiřelý odkaz:

Dev sync failed: viewField: INVALID_VIEW_DATA: Field metadata not found

​

Řešení

getFieldUniversalIdentifier je k dispozici od twenty-sdk verze 2.21 a vyšší.

Použijte getFieldUniversalIdentifier k odvození přesně stejné hodnoty, jakou používá server. Funkce přijímá tři vstupy a vrací univerzální identifikátor pole:

import { getFieldUniversalIdentifier } from 'twenty-sdk/define';

const createdAtFieldId = getFieldUniversalIdentifier({
  applicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER,
  objectUniversalIdentifier: MY_OBJECT_UNIVERSAL_IDENTIFIER,
  name: 'createdAt',
});

• applicationUniversalIdentifier je identifikátor vaší aplikace, ten, který předáváte do defineApplication().
• objectUniversalIdentifier je identifikátor objektu, ke kterému pole patří.
• name je název systémového pole, jedna z výše uvedených hodnot.

​

Příklad: sloupec createdAt v zobrazení

Typickým případem je přidání sloupce createdAt do zobrazení některého z vašich vlastních objektů. Odvoďte identifikátor pole a odkažte na něj stejně jako na jakýkoli jiný fieldMetadataUniversalIdentifier:

src/views/example-view.ts

import {
  defineView,
  getFieldUniversalIdentifier,
} from 'twenty-sdk/define';

const APPLICATION_UNIVERSAL_IDENTIFIER =
  '0b04e15c-27b2-4741-9046-b32e07469072';
const MY_OBJECT_UNIVERSAL_IDENTIFIER =
  'c782b61c-70fd-4c88-9cd6-4e61ab8d7591';

export default defineView({
  universalIdentifier: '70f10d44-144a-4da8-8c6f-3ec2422138c0',
  name: 'All records',
  objectUniversalIdentifier: MY_OBJECT_UNIVERSAL_IDENTIFIER,
  icon: 'IconList',
  position: 0,
  fields: [
    {
      universalIdentifier: '75a90bc4-d901-4df4-85e0-af29db5e0104',
      fieldMetadataUniversalIdentifier: getFieldUniversalIdentifier({
        applicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER,
        objectUniversalIdentifier: MY_OBJECT_UNIVERSAL_IDENTIFIER,
        name: 'createdAt',
      }),
      position: 0,
      isVisible: true,
      size: 200,
    },
  ],
});

Tentýž odvozený identifikátor funguje všude tam, kde se očekává fieldMetadataUniversalIdentifier: pole zobrazení, filtry, řazení, seskupování a widgety rozložení stránky.

Identifikátor odvozujte, neukládejte ho natvrdo. Protože server odvozuje hodnotu z ID aplikace, ID objektu a názvu pole, volání getFieldUniversalIdentifier udržuje odkaz správný i v případě, že se tyto vstupy změní, a předchází odchylkám, pokud se samotný způsob odvozování někdy změní.

​

Systémová relační pole

getSystemRelationFieldUniversalIdentifier je k dispozici od verze twenty-sdk 2.23 a vyžaduje server Twenty ve verzi 2.23 nebo novější.

Kromě výše uvedených skalárních systémových polí server také na každém objektu poskytuje čtyři systémová relační pole: timelineActivities, attachments, noteTargets a taskTargets, z nichž každé ukazuje na odpovídající standardní relační objekt.

Tato pole nejsou řešena pomocí getFieldUniversalIdentifier: jejich identifikátor je odvozen bez ohledu na název z objektu, který pole obsahuje, a z objektu, na který pole odkazuje. Tím pádem přejmenování objektu nikdy nezmění identifikátory jeho relačních polí.

Použijte getSystemRelationFieldUniversalIdentifier k jejich vyřešení:

import {
  getSystemRelationFieldUniversalIdentifier,
  STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS,
} from 'twenty-sdk/define';

// rocket.attachments — the relation field hosted on your custom object
const rocketAttachmentsFieldId = getSystemRelationFieldUniversalIdentifier({
  applicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER,
  objectUniversalIdentifier: ROCKET_OBJECT_UNIVERSAL_IDENTIFIER,
  relationTargetObjectUniversalIdentifier:
    STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.attachment.universalIdentifier,
});

• objectUniversalIdentifier je objekt, který toto pole obsahuje.
• relationTargetObjectUniversalIdentifier je objekt, na který toto pole ukazuje.

Směr je zakódovaný pořadím argumentů. Pro vyřešení opačné strany (např. attachment.targetRocket, morph pole, které server vytvoří na standardním relačním objektu), je prohoďte:

// attachment.targetRocket — the reverse morph field on Attachment
const attachmentTargetRocketFieldId =
  getSystemRelationFieldUniversalIdentifier({
    applicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER,
    objectUniversalIdentifier:
      STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.attachment.universalIdentifier,
    relationTargetObjectUniversalIdentifier: ROCKET_OBJECT_UNIVERSAL_IDENTIFIER,
  });

Stejně jako u skalárních systémových polí funguje vyřešené ID všude tam, kde je očekáváno fieldMetadataUniversalIdentifier.

​

Systémová zobrazení

getSystemViewUniversalIdentifier a getSystemViewFieldUniversalIdentifier jsou k dispozici od verze twenty-sdk 2.26 a vyžadují server Twenty ve verzi 2.26 nebo novější.

Server také pro každý objekt zřizuje systémové zobrazení: hlavní zobrazení seznamu (All {objectLabelPlural}, s klíčem ViewKey.INDEX) s jedním sloupcem pro každé zobrazitelné pole. Stejně jako u systémových relačních polí jsou jejich identifikátory odvozovány nezávisle na názvu, takže přejmenování objektu nebo pole je nikdy nezmění.

Použijte getSystemViewUniversalIdentifier k vyřešení zobrazení:

import { getSystemViewUniversalIdentifier, ViewKey } from 'twenty-sdk/define';

const rocketIndexViewId = getSystemViewUniversalIdentifier({
  objectMetadataApplicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER,
  objectUniversalIdentifier: ROCKET_OBJECT_UNIVERSAL_IDENTIFIER,
  viewKey: ViewKey.INDEX,
});

• objectMetadataApplicationUniversalIdentifier je aplikace, která vlastní objekt, podle které je zobrazení namespacované.
• objectUniversalIdentifier je objekt, který zobrazení vypisuje.
• viewKey je klíč systémového zobrazení, aktuálně ViewKey.INDEX.

Vyhodnocené ID funguje všude tam, kde se očekává viewUniversalIdentifier, například u položky postranního panelu NavigationMenuItemType.VIEW. Pro pouhé otevření hlavního seznamu objektu preferujte NavigationMenuItemType.OBJECT s targetObjectUniversalIdentifier: nevyžaduje žádné odvozování.

getSystemViewFieldUniversalIdentifier vyhodnotí jeden konkrétní sloupec v systémovém zobrazení na základě zobrazení a pole, které zobrazuje:

import { getSystemViewFieldUniversalIdentifier } from 'twenty-sdk/define';

const rocketNameColumnId = getSystemViewFieldUniversalIdentifier({
  fieldMetadataApplicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER,
  viewUniversalIdentifier: rocketIndexViewId,
  fieldMetadataUniversalIdentifier: ROCKET_NAME_FIELD_UNIVERSAL_IDENTIFIER,
});

Všimněte si prvního argumentu: sloupec je namespacován podle aplikace, která vlastní pole, které zobrazuje, nikoli podle aplikace, která vlastní zobrazení. Pole, které vaše aplikace přidá ke standardnímu objektu, má svůj sloupec odvozený pod vaší aplikací, a to v rámci zobrazení vlastněného Twenty.

Systémová zobrazení a jejich sloupce jsou vlastněna serverem: vyhodnocujte jejich identifikátory pro účely odkazování, nikdy pro jejich deklaraci. key u defineView() je zastaralý a ignorovaný, takže manifestové zobrazení nikdy nemůže nárokovat klíč INDEX a server už zřizuje sloupec pro každé pole, které přidáte, takže deklarovat vlastní defineViewField() pro stejné pole v systémovém zobrazení s tím bude v konfliktu.

​

Standardní objekty Twenty

U standardního objektu Twenty (Person, Company, Opportunity, …) nemusíte nic odvozovat: identifikátory jsou předpočítané konstanty, které můžete přímo importovat, a to jak pro pole, tak pro zobrazení.

import { STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS } from 'twenty-sdk/define';

// STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.fields.createdAt.universalIdentifier
// STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.person.fields.updatedAt.universalIdentifier
// STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.person.views.allPeople.universalIdentifier

Použijte pomocné funkce uvedené výše v případě, kdy je objekt definován vaší aplikací pomocí defineObject() a žádná taková konstanta neexistuje.

name je výchozí pole, nikoli systémové pole. Má svůj vlastní natvrdo daný univerzální identifikátor a neodvozuje se pomocí getFieldUniversalIdentifier. U objektů, které definujete, odkazujte na pole name pomocí identifikátoru, který jste mu dali v defineObject().