Š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 nema
allow-same-origin. Aplikacija ne vidi stranicu grupe, kolačiće ni sesiju; sa potok-om razgovara samo preko API-ja. - Okvir učitava CSS stranice (Tailwind i daisyUI) i prati njenu temu (
data-theme). Zato daisyUI klase poputbtnrade u potok-u, iako ih ne pišeš u svom CSS-u. localStorageradi: stranica čuva posebnu kopiju za svaku aplikaciju, najviše 256 KB.sessionStorageživi samo u memoriji (poglavlje 8).- Aplikacija se ponovo učitava posle prekida i obnove veze, kad se promeni opis grupe i kad se promeni pristup korisnika (članstvo, uloge).
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.
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 potok | skripta potok_app_sdk.js koju potok učitava u okvir |
| Tip | PotokApi | PotokSdk |
| Upis | insertGroupValue(json), json je string | insertValue(data), objekat ili JSON string |
| Čitanje | getGroupDataValues(): sve vrednosti, do 5000 | listValues(): strana po strana, do 200 |
| Uživo | setNewValueCallback(fn), jedan callback | onNewValue(fn), više slušalaca, vraća odjavu |
| Ostalo | profil i opis | sve ostalo: kolekcije, procesi, podgrupe, mape, glasanja, lična memorija… |
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.
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();
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>
- Sajt se javlja roditelju porukom
{potok: 1, event: "hello"}, a SDK mu odgovara temom, jezikom i listom dozvoljenih poziva. Pozivi su poruke sa imenima koja SDK šalje stranici (current_profile,list_values…); poziv koji nije na listi dobijanot_listed. - Sajt nasleđuje zatvoren okvir: nema porekla, pa ni
localStorage. - Kod sajta se ne čuva u grupi kao otpremljena aplikacija: okvir prikazuje ono što ta adresa servira u tom trenutku.
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.