Zrozum, jak układy widoku łączą formularze, wersje robocze, opublikowany runtime i zapisy rekordów.

Układy widoku

Układy widoku określają, jak ułożony jest ekran Opero albo formularz obiektu własnego. Układ decyduje, które pola, sekcje, zakładki, tabele relacji, przyciski i inne bloki są dostępne, gdy klient tworzy, wyświetla albo edytuje rekord.

Dla obiektów własnych zacznij od formularza obiektu własnego. Formularz decyduje, kiedy można go użyć. Układ widoku należący do tego formularza decyduje, co formularz pokazuje i które pola można wysłać przez endpointy runtime.

Typowy przebieg pracy

Dla większości prac z formularzem obiektu własnego:

Utwórz albo wybierz obiekt własny, na przykład support.ticket.
Utwórz formularz obiektu własnego z jednym lub kilkoma typami: CREATE, VIEW i EDIT.
Odczytaj viewLayoutId z odpowiedzi formularza.
Zapytaj katalog układów widoku, które bloki można użyć dla tego formularza i trybu.
Zbuduj pełną wersję roboczą z regionami, blokami i opcjonalnymi zmianami pól własnych.
Zapisz wersję roboczą na układzie należącym do formularza.
Opublikuj wersję roboczą.
Rozwiąż opublikowany układ podczas renderowania albo zapisywania rekordów.
Utwórz albo zaktualizuj rekordy przez endpointy runtime.

Nie twórz ręcznie drugiego układu widoku dla formularza obiektu własnego. Gdy tworzysz formularz, Opero tworzy układ należący do tego formularza.

Kluczowe pojęcia

Pojęcie	Znaczenie
Formularz obiektu własnego	Formularz do tworzenia, wyświetlania albo edytowania rekordów jednego obiektu własnego.
Układ widoku	Wizualny i runtime kontrakt pól oraz bloków.
Powierzchnia	Rodzina strony, na przykład `DYNAMIC_OBJECT`, `CONTRACTOR`, `ORGANIZATION` albo `DASHBOARD`.
Tryb	Użycie układu w runtime: `CREATE`, `VIEW`, `EDIT` albo `WORKSPACE`.
Target	Dodatkowy kontekst dla powierzchni. Układy obiektów dynamicznych używają `moduleKey`, `objectKey` i zwykle `formId`.
Region	Nazwany obszar układu, na przykład `main` albo `sidebar`. Bloki są umieszczane w regionach.
Blok	Jeden element układu, na przykład pole, sekcja, grupa zakładek, tabela relacji albo blok własnego HTML.
Wersja robocza	Edytowalna wersja układu. Zapis wersji roboczej nie zmienia działania runtime.
Opublikowana wersja	Wersja używana przez endpoint rozwiązywania runtime i endpointy zapisu rekordów.

Uprawnienia

Każde zapytanie używa tokenu API:

Authorization: Bearer ek_...
Content-Type: application/json

Użyj tokenu organizacji do konfiguracji układów View Layout i formularzy obiektów własnych. Odczyty i zapisy rekordów w runtime używają kontekstu przestrzeni firmy przeznaczonego dla integracji.

Nadaj tokenowi najmniejszy zestaw uprawnień pasujący do integracji.

Uprawnienie	Potrzebne do
`api.custom_forms.read`	Listowania formularzy, odczytu szczegółów formularza, listowania dostępnych formularzy i odczytu dostępu do formularzy.
`api.custom_forms.manage`	Tworzenia, aktualizacji i usuwania formularzy, aktualizacji domyślnych formularzy oraz zastępowania dostępu.
`api.view_layouts.read`	Odczytu metadanych układów, endpointów odkrywania, wersji, rozwiązywania runtime i danych runtime.
`api.view_layouts.manage`	Tworzenia kontenerów układów, aktualizacji metadanych, zapisu wersji roboczych, archiwizacji układów, przywracania wersji roboczych i zastępowania przypisań.
`api.view_layouts.publish`	Publikowania zapisanej wersji roboczej.
`api.custom_records.read`	Rozwiązywania i ładowania danych runtime obiektów dynamicznych.
`api.custom_records.write`	Tworzenia i aktualizacji rekordów obiektów dynamicznych przez opublikowany układ.

Wybór pierwszego endpointu

Zacznij od celu, a potem wybierz endpoint.

Cel	Zacznij od
Utworzenie formularza obiektu własnego	`POST /v1/custom-modules/:moduleKey/objects/:objectKey/forms`
Znalezienie układu istniejącego formularza	`GET /v1/custom-modules/:moduleKey/objects/:objectKey/forms/:formId`
Sprawdzenie dostępnych bloków	`GET /v1/view-layouts/catalog`
Zapis zmienionego układu	`PUT /v1/view-layouts/:layoutId/draft`
Opublikowanie wersji roboczej	`POST /v1/view-layouts/:layoutId/publish`
Renderowanie opublikowanego formularza	`GET /v1/view-layouts/resolve`
Zapis rekordu przez układ	`POST /v1/view-layouts/runtime/dynamic-object/records` albo `PATCH /v1/view-layouts/runtime/dynamic-object/records/:recordId`

Kolejność czytania

Formularze obiektów własnych wyjaśniają pracę zaczynającą się od formularza.
Odkrywanie bloków pokazuje, jak zapytać API, co można umieścić w układzie.
Budowanie układów opisuje wersje robocze, publikowanie, wersje, przypisania i archiwizację.
Typy bloków opisują strukturę bloków i zagnieżdżanie.
Pola własne opisują istniejące i przygotowywane pola.
Przewodnik po runtime opisuje rozwiązywanie układów i zapisywanie rekordów.
Przykłady pokazują pełny przepływ do skopiowania.
Rozwiązywanie problemów opisuje częste błędy.

Zasady do zapamiętania

Formularz obiektu własnego ma jeden układ widoku.
Zmiany w wersji roboczej nie są widoczne w runtime, dopóki wersja robocza nie zostanie opublikowana.
Używaj endpointów odkrywania przed budowaniem bloków.
Traktuj wartości defaultBlock z katalogu jako szablony. Przed zapisem dodaj stabilne ID i umieść bloki w regionach.
Zapisy rekordów obiektów własnych w runtime muszą spełniać wymagania opublikowanego układu oraz zewnętrznego profilu obiektu własnego.
Konfiguracja organizacji i dane runtime firmy używają różnych zakresów tokenów API.

Przegląd