Strani

Kako strani delujejo v arhitekturi Orb - usmerjanje, vezava lastnosti, rezine in navigacija.

Povezano:

Pregled

V jeziku Orb je Stran pot, ki sestavlja lastnosti za upodabljanje UI. Temeljni sestav je:

Orbital = Entiteta + Lastnosti + Strani

Medtem ko Entitete definirajo podatke in Lastnosti definirajo obnasanje, Strani definirajo, kje uporabniki komunicirajo s sistemom. Strani so vodene z lastnostmi - ne vsebujejo UI neposredno, ampak se sklicujejo na lastnosti, katerih ucinki render-ui zapolnijo stran.

Definicija strani

Stran je definirana v .orb programu z naslednjo strukturo:

{
  "name": "TaskListPage",
  "path": "/tasks",
  "viewType": "list",
  "primaryEntity": "Task",
  "traits": [
    { "ref": "TaskBrowser", "linkedEntity": "Task" },
    { "ref": "FilterPanel", "linkedEntity": "Task" }
  ]
}

Lastnosti strani

Lastnost	Obvezno	Opis
`name`	Da	Identifikator v PascalCase (npr. `TaskListPage`)
`path`	Da	URL pot, ki se zacne z `/`
`viewType`	Ne	Semanticni namig: `list`, `detail`, `create`, `edit`, `dashboard`, `custom`
`primaryEntity`	Ne	Glavna entiteta, na kateri ta stran deluje
`traits`	Da	Seznam referenc na lastnosti, ki poganjajo UI
`isInitial`	Ne	Ali je to vstopna stran

Poti in vzorci poti

Poti strani definirajo URL poti za vaso aplikacijo.

Pravila poti

Mora se zaceti z /
Veljavni znaki: crke, stevilke, pomisljaji, podcrke, dvopicja, posevnice
Mora biti edinstvena med vsemi stranmi v programu

Staticne poti

Preproste poti brez dinamicnih segmentov:

{ "path": "/tasks" }
{ "path": "/dashboard" }
{ "path": "/settings/profile" }

Dinamicni segmenti

Uporabite sintakso z dvopicjem za dinamicne parametre:

{ "path": "/tasks/:id" }
{ "path": "/users/:userId/tasks/:taskId" }
{ "path": "/projects/:projectId/members/:memberId" }

Dinamicni segmenti so izvleceni in na voljo v:

Obremenitvah dogodkov (@payload.id)
Ucinkih navigacije
Iskanju entitet

Primeri poti

Pot	Opis
`/tasks`	Stran seznama nalog
`/tasks/:id`	Podrobnosti posamezne naloge
`/tasks/create`	Ustvarjanje nove naloge
`/tasks/:id/edit`	Urejanje obstojece naloge
`/users/:id/profile`	Uporabniski profil
`/dashboard`	Pregledna plosca

Tipi pogledov

Tipi pogledov so semanticni namigi o namenu strani:

Tip	Namen	Tipicni vzorci
`list`	Prikaz zbirke entitet	`entity-table`, `entity-cards`, `entity-list`
`detail`	Prikaz posamezne entitete	`entity-detail`, `stats`
`create`	Ustvarjanje nove entitete	`form`
`edit`	Urejanje obstojece entitete	`form`
`dashboard`	Pregled z vec razdelki	`dashboard-grid`, `stats`
`custom`	Prilagojena postavitev	Katerikoli vzorci

Pomembno: Tipi pogledov ne omejujejo UI - dejansko upodabljanje nadzirajo ucinki render-ui v lastnostih. Tipi pogledov so metapodatki za:

Dokumentacijo
Namige za generiranje kode
Ogrodje UI

Vezava Stran-Lastnost

Strani se sklicujejo na lastnosti, ki zagotavljajo njihovo obnasanje in UI.

Reference na lastnosti

{
  "pages": [
    {
      "name": "TaskListPage",
      "path": "/tasks",
      "traits": [
        { "ref": "TaskBrowser", "linkedEntity": "Task" },
        { "ref": "QuickActions", "linkedEntity": "Task", "config": { "showCreate": true } }
      ]
    }
  ]
}

Struktura PageTraitRef

Lastnost	Obvezno	Opis
`ref`	Da	Ime lastnosti ali pot (npr. `"TaskBrowser"`, `"Std.traits.CRUD"`)
`linkedEntity`	Ne	Entiteta, na kateri ta lastnost deluje
`config`	Ne	Konfiguracija, specificna za lastnost

Vec lastnosti na stran

Stran ima lahko vec lastnosti, od katerih vsaka prispeva UI v razlicne rezine:

{
  "name": "DashboardPage",
  "path": "/dashboard",
  "traits": [
    { "ref": "StatsSummary", "linkedEntity": "Analytics" },
    { "ref": "RecentActivity", "linkedEntity": "Activity" },
    { "ref": "QuickActions", "linkedEntity": "Task" }
  ]
}

Ucinki render-ui vsake lastnosti ciljajo dolocene rezine.

linkedEntity na lastnostih

Lastnost linkedEntity veze lastnost na doloceno entiteto:

{ "ref": "StatusManager", "linkedEntity": "Task" }

To pomeni:

Vezave @entity v lastnosti se razresijo na podatke Task
Ucinki, kot je persist, delujejo na zbirki Task
Avtomat stanj lastnosti upravlja primerke Task

Glej Vezava Lastnost-Entiteta za podrobnosti.

Primarna entiteta

Lastnost primaryEntity oznacuje glavno entiteto, na kateri stran deluje:

{
  "name": "TaskDetailPage",
  "path": "/tasks/:id",
  "primaryEntity": "Task",
  "traits": [
    { "ref": "TaskViewer" },
    { "ref": "CommentList", "linkedEntity": "Comment" }
  ]
}

Uporaba:

Privzeta entiteta za lastnosti brez eksplicitnega linkedEntity
Preverjanje, da entiteta obstaja
Namigi za generiranje kode
Ni obvezno, ce vse lastnosti eksplicitno dolocijo svojo entiteto

Rezine in upodabljanje UI

Lastnosti upodabljajo UI prek ucinkov render-ui, ki ciljajo rezine - poimenovana podrocja na strani.

Razpolozljive rezine

Rezina	Namen
`main`	Primarno podrocje vsebine
`sidebar`	Stranski panel
`modal`	Modalno prekrivanje
`drawer`	Predalni panel
`overlay`	Celozaslonsko prekrivanje
`center`	Srediscna vsebina
`toast`	Obvestila toast
`hud-top`	Zgornji HUD (igralni UI)
`hud-bottom`	Spodnji HUD (igralni UI)
`floating`	Plavajoci element
`system`	Nevidne sistemske komponente

Ucinek render-ui

Lastnosti zapolnijo rezine z ucinkom render-ui:

["render-ui", "main", {
  "type": "entity-table",
  "entity": "Task",
  "columns": ["title", "status", "dueDate"],
  "itemActions": [
    { "event": "VIEW", "label": "View" },
    { "event": "EDIT", "label": "Edit" }
  ]
}]

Tok rezin

┌─────────────────────────────────────────────────────────────┐
│  Stran: TaskListPage                                        │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  Rezina: main                                        │   │
│  │  ┌─────────────────────────────────────────────┐    │   │
│  │  │  Vzorec: entity-table (iz TaskBrowser)      │    │   │
│  │  │  - Stolpci: title, status, dueDate          │    │   │
│  │  │  - Akcije: VIEW, EDIT                       │    │   │
│  │  └─────────────────────────────────────────────┘    │   │
│  └─────────────────────────────────────────────────────┘   │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  Rezina: sidebar                                     │   │
│  │  ┌─────────────────────────────────────────────┐    │   │
│  │  │  Vzorec: filter-panel (iz FilterPanel)      │    │   │
│  │  └─────────────────────────────────────────────┘    │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

Vec upodobitev v isto rezino

Ce vec lastnosti upodablja v isto rezino, se zlagajo (kasnejsi nadomesti ali doda, odvisno od tipa vzorca):

// Lastnost A
["render-ui", "main", { "type": "stats", ... }]

// Lastnost B (kasneje na strani)
["render-ui", "main", { "type": "entity-table", ... }]

Navigacija

Navigacija med stranmi se izvaja prek ucinka navigate v lastnostih.

Ucinek navigate

["navigate", "/tasks/:id", { "id": "@payload.taskId" }]

Format: ["navigate", pot, parametri?]

Argument	Opis
`pot`	Ciljna pot strani (lahko vkljucuje dinamicne segmente)
`parametri`	Neobvezni objekt za zapolnitev dinamicnih segmentov

Primeri navigacije

Preprosta navigacija:

["navigate", "/dashboard"]

Z ID-jem entitete:

["navigate", "/tasks/@entity.id"]

Z obremenitvijo:

["navigate", "/tasks/:id", { "id": "@payload.taskId" }]

Gnezdena pot:

["navigate", "/users/:userId/tasks/:taskId", {
  "userId": "@entity.assigneeId",
  "taskId": "@entity.id"
}]

Navigacija v prehodih

Navigacija se tipicno zgodi po spremembi stanja:

{
  "from": "editing",
  "to": "saved",
  "event": "SAVE",
  "effects": [
    ["persist", "update", "Task", "@entity.id", "@payload"],
    ["notify", "Task saved!", "success"],
    ["navigate", "/tasks/@entity.id"]
  ]
}

Glej Ucinki za vec podrobnosti.

Zacetna stran

Oznacite stran kot vstopno tocko z isInitial:

{
  "name": "HomePage",
  "path": "/",
  "isInitial": true,
  "traits": [
    { "ref": "WelcomeBanner" }
  ]
}

Obnasanje:

Aplikacija najprej nalozi to stran
Preusmeritve iz korena (/) vodijo sem
Samo ena stran naj bo oznacena kot zacetna na Orbital enoto

Preverjanje strani

Strani se preverjajo ob prevajanju s temi pravili:

Obvezna polja

name - Mora biti v PascalCase
path - Mora se zaceti z /, samo veljavni znaki
traits - Mora imeti vsaj eno referenco na lastnost

Napake pri preverjanju

Napaka	Opis
`PageMissingName`	Ime strani je obvezno
`PageMissingPath`	Pot strani je obvezna
`PageInvalidPath`	Pot ne ustreza vzorcu
`PageEmptyTraits`	Seznam lastnosti ne sme biti prazen
`PageInvalidTraitRef`	Referencirana lastnost ne obstaja
`PageInvalidViewType`	viewType ni na veljavnem seznamu
`PageDuplicatePath`	Druga stran uporablja isto pot

Celoten primer

Celoten primer strani z vec lastnostmi:

orbital TaskManagement {
  entity Task {
    id : string!
    title : string!
    status : string
    assigneeId : string
  }
  trait TaskBrowser -> Task {
    initial: idle
    state idle {
      INIT -> viewing
        (fetch Task {  })
        (render-ui main { type: "entity-table", entity: "Task", fields: ["title", "status", "assigneeId"], columns: ["title", "status", "assigneeId"], itemActions: [{ event: "VIEW", label: "View" }] })
    }
    state viewing {
      VIEW -> viewing
        (navigate "/tasks/@payload.id" { id: "@entity.id" })
    }
  }
  trait TaskViewer -> Task {
    initial: loading
    state loading {
      INIT -> viewing
        (fetch Task { id: "@payload.id" })
        (render-ui main { type: "detail-panel", entity: "Task", fields: ["title", "status", "assigneeId"] })
    }
    state viewing {
      EDIT -> viewing
        (navigate "/tasks/@entity.id/edit")
      BACK -> viewing
        (navigate "/tasks" { id: "@entity.id" })
    }
  }
  page "/tasks" -> TaskBrowser
  page "/tasks/:id" -> TaskViewer
}

Kljucna nacela

Strani vodene z lastnostmi - Strani so vsebniki za reference na lastnosti. UI izhaja iz ucinkov render-ui v lastnostih, ne iz definicij strani.
Arhitektura rezin - UI tece skozi standardizirane rezine (main, sidebar, modal), kar omogoca sestavo postavitev brez trdega kodiranja.
Pot kot pogodba - Pot strani je primarni vmesnik - definira URL, na katerega uporabniki navigirajo.
Eksplicitna vezava entitete - linkedEntity na referencah lastnosti naredi relacije entitet eksplicitne.
Brez stanja strani - Strani so zgolj sestavne. Vse stanje zivi v avtomatih stanj lastnosti.
Navigacija vodena z ucinki - Navigacija je ucinek, ki ga sprozijo prehodi lastnosti, ne lastnost strani.

Povzetek

Sistem strani v Orb zagotavlja:

Usmerjanje - Navigacija na osnovi poti z dinamicnimi segmenti
Sestava lastnosti - Vec lastnosti na stran, vsaka prispeva UI
Rezine - Poimenovana podrocja za postavitev UI (main, sidebar, modal itd.)
Tipi pogledov - Semanticni namigi za namen strani (list, detail, dashboard)
Navigacija - Usmerjanje med stranmi, vodeno z ucinki
Vezava entitete - Eksplicitne relacije entitet prek linkedEntity
Preverjanje - Prevajalnik uveljavlja edinstvenost poti in obstoj lastnosti

Strani so plast za usmerjanje in sestavo - definirajo, kam uporabniki gredo, medtem ko lastnosti definirajo, kaj se dogaja, in entitete definirajo, kateri podatki so vpleteni.

Pregled​

Definicija strani​

Lastnosti strani​

Poti in vzorci poti​

Pravila poti​

Staticne poti​

Dinamicni segmenti​

Primeri poti​

Tipi pogledov​

Vezava Stran-Lastnost​

Reference na lastnosti​

Struktura PageTraitRef​

Vec lastnosti na stran​

linkedEntity na lastnostih​

Primarna entiteta​

Rezine in upodabljanje UI​

Razpolozljive rezine​

Ucinek render-ui​

Tok rezin​

Vec upodobitev v isto rezino​

Navigacija​

Ucinek navigate​

Primeri navigacije​

Navigacija v prehodih​

Zacetna stran​

Preverjanje strani​

Obvezna polja​

Napake pri preverjanju​

Celoten primer​

Kljucna nacela​

Povzetek​