1. Šta je potok aplikacija
Poglavlje 1

Šta je potok aplikacija

Potok aplikacija je HTML koji živi u opisu jedne potok grupe. potok ga pokreće u zatvorenom okviru (iframe) i daje mu API za čitanje i upis podataka grupe. Ovo poglavlje objašnjava gde aplikacija radi, sa čim razgovara i šta sme.

1.1. Opis grupe je aplikacija

Svaka potok grupa ima opis. Kad u Uredi grupu, na kartici Opis, uključiš opciju „Opis je aplikacija (API)“, opis se više ne prikazuje kao formatiran tekst: potok ga pokreće kao program.

Taj program je jedan HTML fajl. Šablon potok-vite ga pravi iz Vite projekta (TypeScript i Tailwind), a ti ga otpremaš u opis dugmetom Otpremi ZIP (poglavlje 2).

Opis može biti podrazumevani ili jedan od alternativnih opisa grupe. Svaki opis sa uključenom opcijom je zasebna aplikacija sa svojim podacima, pa jedna grupa može imati više aplikacija (poglavlje 7).

1.2. Aplikacija radi u zatvorenom okviru

potok stavlja sadržaj tvog fajla u iframe. Dokument okvira izgleda ovako:

<head>
  <meta name="potok-app" content="">  <!-- "" za podrazumevani opis, inače id alternativnog opisa -->
  <!-- CSS stranice i potok_app_sdk.js -->
</head>
<body><div id="group-panel-description"><!-- sadržaj potok-build.html --></div></body>

Od toga zavisi šta aplikacija može:

Okvir ima sandbox="allow-scripts allow-forms allow-popups allow-popups-to-escape-sandbox allow-modals allow-downloads": skripte, forme, novi prozori i dijalozi rade, a poreklo ne postoji.

Napomena

Bez porekla okviru fale neki API-ji pregledača. Okvir nema ni Web Share ni clipboard, pa za deljenje postoji poziv shareGroup (poglavlje 11), a za prijavu gosta openLogin (poglavlje 6).

1.3. Dva API-ja: potok i window.potok

U kodu aplikacije postoje dva API-ja. Oba rade nad istim podacima, a tipovi oba su u src/potok.ts.

potok (legacy)window.potok (SDK)
Odakle dolazi#group-panel-description.potok; build ga daje kodu aplikacije kao lokalnu promenljivu potokskripta potok_app_sdk.js koju potok učitava u okvir
TipPotokApiPotokSdk
UpisinsertGroupValue(json), json je stringinsertValue(data), objekat ili JSON string
ČitanjegetGroupDataValues(): sve vrednosti, do 5000listValues(): strana po strana, do 200
UživosetNewValueCallback(fn), jedan callbackonNewValue(fn), više slušalaca, vraća odjavu
Ostaloprofil i opissve ostalo: kolekcije, procesi, podgrupe, mape, glasanja, lična memorija…
Pukne tek u potok-u

U dev mock-u su potok i window.potok isti objekat sa oba API-ja, a u potok-u nisu. Ne zovi metodu jednog API-ja na drugom: potok.insertValue radi u npm run dev, a u potok-u baca TypeError. Tipovi to čuvaju, pa ih ne zaobilazi sa any (poglavlje 4).

Za novu aplikaciju koristi window.potok: samo on ima kolekcije, procese, podgrupe, mape i glasanja. Legacy potok ostaje zbog postojećih aplikacija, i zbog potok.eventListenerOptions, koji svaka aplikacija koristi za svoje slušaoce (poglavlje 4).

1.4. Put jednog poziva

Poziv ne ide direktno na server. SDK u okviru šalje poruku stranici grupe (postMessage), stranica je prosleđuje serveru, a server svaki poziv ponovo proverava: da li gledalac sme to da uradi i da li je aplikacija i dalje na ekranu.

Aplikacija u okviru poziva SDK, SDK šalje poruku stranici grupe, stranica prosleđuje poziv serveru, a odgovor ide istim putem nazad. iframe bez porekla aplikacija tvoj kod SDK window.potok stranica grupe u pregledaču server proverava prava postMessage odgovor: {ok: true, …} ili {ok: false, error}
Poziv iz aplikacije prolazi kroz SDK i stranicu do servera; odgovor se vraća istim putem.

Svaki poziv vraća promise koji se ispunjava odgovorom: {ok: true, …} ili {ok: false, error, message?}. Neuspeh je običan odgovor, ne izuzetak. Ako stranica ne odgovori za 10 s, promise se odbija (reject).

async function load() {
  const reply = await window.potok.listValues({ limit: 20 });
  if (!reply.ok) {
    // message is set (localized) only by server-side checks
    console.error(reply.error, reply.message);
    return;
  }
  console.log(reply.values.length, reply.has_more);
}

void load();
Važno

Pozivi koji vraćaju ok mogu da ne uspeju. Proveri if (!reply.ok) pre nego što upotrebiš odgovor. TypeScript tu pomaže: dok ne proveriš ok, reply.values ne postoji u tipu.

1.5. Podaci: vrednosti i kolekcije

Aplikacija čuva podatke kao data vrednosti grupe: svaka vrednost nosi JSON objekat (data), autora i vreme. Svaka aplikacija ima svoje vrednosti, a oba API-ja vide samo vrednosti svoje aplikacije, osim kad zatraže vrednosti cele grupe (scope: "group"). Vrednosti se uglavnom samo dodaju, pa se stanje aplikacije računa iz svih vrednosti (poglavlje 5).

Kad aplikaciji treba više kontrole, vrednosti stoje u kolekcijama, pod pravilima koja urednici aplikacije drže u njenoj konfiguraciji (getConfig, saveConfig): ko piše, ko čita sve, a ko samo svoje. Vrednosti kolekcija dolaze samo kroz pozive koji imenuju kolekciju, nikad kroz onNewValue (poglavlje 9).

Osim vrednosti, aplikacija ima i ličnu memoriju gledaoca, svoj localStorage i adresu strane (poglavlje 8).

1.6. Druga mogućnost: sajt u okviru aplikacije

Opis koji je aplikacija može da drži i ceo sajt sa druge adrese, u svom okviru. Takav sajt nije pravljen šablonom potok-vite i ne otprema se u opis; u opisu stoji samo okvir sa adresom sajta i atributom data-potok-api.

<iframe src="https://adresa-sajta/" title="Naziv sajta" data-potok-api="current_profile list_values"
        style="width: 100%; height: 100vh; border: none;" loading="lazy"></iframe>

Ovaj priručnik je upravo takav sajt kad se prikaže u potok grupi. Za aplikaciju koja čuva podatke grupe koristi šablon potok-vite; sajt u okviru je za sadržaj koji već živi negde drugde.

1.7. Gde dalje

Pomoć u potok-u ima stranu Arhitektura Potok aplikacije, sa dijagramom ovog šablona, putem jednog upisa i limitima servera. Ostatak priručnika ide redom kojim praviš aplikaciju: prvi koraci, build, pravila, pa API po oblastima.