Kolekcije i pravila
Obične vrednosti aplikacije čitaju svi članovi. Kad aplikaciji treba više (anketa u kojoj svako vidi samo svoj odgovor, prijava sa fajlovima, kviz sa bodovima), vrednosti stoje u kolekcijama, pod pravilima koja potok drži pri svakom pozivu.
9.1. Šta je kolekcija
Kolekcija je imenovan skup vrednosti aplikacije. Pravila za nju urednici aplikacije pišu u njenu konfiguraciju: ko piše, ko čita sve, a ko samo svoje. Vrednosti kolekcija dolaze samo kroz pozive koji imenuju kolekciju ({collection: "…"}), nikad kroz onNewValue.
- Ime kolekcije počinje malim slovom, ima do 40 malih slova, cifara,
_i-, i nijeconfig,notifynifiles, koje su rezervisane. Ostalo dajeinvalid_collection. - Kolekcija bez pravila je zatvorena: članovi pišu, a čitaju samo autor i urednici.
- Oni koji smeju da menjaju grupu (
edit_group) uvek čitaju sve, jer bi ionako mogli da promene pravila.
9.2. Konfiguracija
window.potok.getConfig()- Konfiguracija i, po svakoj kolekciji sa pravilom, šta gledalac sme tu. Odgovor:
config:{id, revision, data, updated_at}ilinulldok je niko nije sačuvao;caps: šta gledalac sme, po kolekciji (odeljak 9.4);manage: gledalac uređuje aplikaciju;can_create_groups: sme i da napravi njene grupe za fajlove;files: za urednike, stanje grupa za fajlove ("ok","missing","exposed");process_warnings: za urednike, šta fali procesima (poglavlje 10);visible_role_keys: uloge na koje je opis ograničen,[]za sve;viewer:{signed_in, member, profile_id, username}.
window.potok.saveConfig(data, {revision})- Za urednike. Pošalji
revisionod koje si krenuo (0za prvo čuvanje). Ako je neko drugi sačuvao u međuvremenu, odgovor jeconflictsacurrent, onim što je sada tamo. Pravila koja ne mogu da važe dajuinvalid_rulessareason.
data konfiguracije drži ono što aplikacija hoće (naslov, rok, izgled), a potok iz njega čita tri dela:
rules: pravilo za svaku kolekciju, po imenu;secret: čitaju ga samo urednici; u njemu je ključ kviza (secret.score);files: grupe u kojima su fajlovi aplikacije; piše ga potok.
import type { PotokConfigData } from './potok';
async function setupSurvey() {
const current = await window.potok.getConfig();
if (!current.ok) return console.error(current.error);
if (!current.manage) return; // only the app's editors save the config
const data: PotokConfigData = {
...(current.config?.data ?? {}),
title: 'Anketa o parku',
rules: { answers: { write: ['everyone'], read: [], once: true } },
};
const reply = await window.potok.saveConfig(data, { revision: current.config?.revision ?? 0 });
if (!reply.ok && reply.error === 'conflict') console.warn('someone saved first', reply.current);
else if (!reply.ok) console.error(reply.error, reply.reason);
}
void setupSurvey();
9.3. Pravilo
Pravilo imenuje ključeve uloga: "everyone", "admin" ili UUID posebne uloge. Spisak uloga grupe daje listRoles(): {ok: true, roles: [{key, name, builtin}]}.
write- Ko dodaje vrednosti.
read- Ko čita sve vrednosti; svi ostali čitaju samo svoje.
summary- Ko vidi samo brojeve (
summarizeValues), bez pojedinačnih vrednosti. once- Jedna vrednost po osobi; druga daje
already_answered. edit_own- Autori smeju da menjaju svoju vrednost (
updateValue). anonymous- Vrednost napisana dok je kolekcija anonimna nikome osim autora ne pokazuje autora:
creator_idicreator_usernamesunull, aanonymousjetrue. public- Prijavljeni nečlanovi javne grupe pišu i čitaju svoje.
open,closes_atopen: falseili prošaocloses_at(ISO 8601 sa zonom): kolekcija više ne prima vrednosti (closed).under- Putanja do mape odgovora u svakoj vrednosti (
["a"]); iz nje čitaju fajlovi, kviz i zbirovi. uploads- Mesta za fajlove (odeljak 9.7).
score- Kolekcija je kviz (odeljak 9.8).
process- Proces za svaku novu vrednost (poglavlje 10).
once važi po nalogu, bez obzira na profil. public postavlja write na ["everyone"]. Anonimna kolekcija ne prima fajlove, jer fajl čuva pošiljaoca.
9.4. Šta gledalac sme: caps
caps iz getConfig kaže, po kolekciji, šta gledalac sme, pa aplikacija može da prikaže formu samo onome ko sme da piše.
| Polje | Značenje |
|---|---|
write, write_block | sme da piše; ako ne sme, zašto: "closed", "role", "blocked", "members_only", "not_permitted" |
read | "all" ili "own" |
summary | sme da vidi zbirove |
edit_own, manage | menja svoje; uređuje kolekciju |
ruled, open, once, anonymous, public, released | osobine pravila: postoji li, je li otvoreno, jedan odgovor, anonimno, javno, objavljeni bodovi |
written | gledalac već ima vrednost tu |
notify | gledalac dobija obaveštenje za svaku novu vrednost |
async function showForm(form: HTMLFormElement) {
const reply = await window.potok.getConfig();
if (!reply.ok) return console.error(reply.error);
const caps = reply.caps['answers'];
form.hidden = !caps?.write || (caps.once && caps.written);
if (caps?.write_block === 'closed') console.log('Anketa je zatvorena.');
}
const form = document.querySelector<HTMLFormElement>('.app-form');
if (form) void showForm(form);
9.5. Upis i čitanje
insertValue(data, {collection})- Upis u kolekciju, kako pravilo dozvoljava. Vraća
{ok: true, value}, gde jevaluePotokCollectionValue: obična vrednost pluscollection,anonymous,revisionimanaged(ocena kviza). listValues({collection, limit, offset, afterId, beforeId, orderDir, mine, total, match})- Strana kolekcije, po
id-ju, najviše 100: sve vrednosti za one koji čitaju sve, inače samo gledaočeve.mine: trueostavlja samo gledaočeve;matchrade samo oni koji čitaju sve.
type Answer = { a: { park: string; comment: string } };
async function answer(park: string, comment: string) {
const reply = await window.potok.insertValue<Answer>({ a: { park, comment } }, { collection: 'answers' });
if (!reply.ok) return console.error(reply.message ?? reply.error);
console.log('revision', reply.value.revision, 'anonymous', reply.value.anonymous);
}
async function myAnswers() {
const reply = await window.potok.listValues<Answer>({ collection: 'answers', mine: true, total: true });
if (!reply.ok) return console.error(reply.error);
console.log(reply.total, reply.values.map((v) => v.data?.a.park));
}
void answer('Dunavski park', 'Više klupa');
void myAnswers();
9.6. Izmena, brisanje i promene uživo
updateValue(id, data, {revision?})- Menja gledaočevu vrednost, gde pravilo daje
edit_own. Pošaljirevisionvrednosti koju menjaš: ako se ona u međuvremenu promenila, odgovor jeconflictsacurrent. Posle objave bodova kviza vrednost se više ne menja (released). deleteValue(id),deleteValues(collection)- Za urednike: jedna vrednost, odnosno cela kolekcija, zajedno sa fajlovima.
onValues(listener, {collection?})- Promene u kolekcijama aplikacije koje gledalac sme da vidi; vraća funkciju za odjavu. Događaji su:
created,updated:{event, collection, value};deleted:{event, collection, id};cleared: cela kolekcija obrisana (collection: nullza sve podatke aplikacije);regraded: bodovi kviza ponovo izračunati;config: konfiguracija je promenjena; pročitaj je ponovo;process: instanca procesa se pomerila (poglavlje 10).
type Answer = { a: { park: string } };
const answers = new Map<number, Answer>();
const stop = window.potok.onValues<Answer>((change) => {
if (change.event === 'created' || change.event === 'updated') {
if (change.value.data) answers.set(change.value.id, change.value.data);
} else if (change.event === 'deleted') {
answers.delete(change.id);
} else if (change.event === 'cleared') {
answers.clear();
}
console.log(answers.size);
}, { collection: 'answers' });
window.addEventListener('pagehide', stop, potok.eventListenerOptions);
9.7. Fajlovi
Kolekcija prima fajlove samo na mestima (uploads) koja pravilo navodi. Svako mesto ima target ("private" ili "public": privatna ili javna grupa za fajlove aplikacije), i po želji max_files, max_bytes i types (document, presentation, spreadsheet, drawing, pdf, image, video, audio).
- Urednik jednom pozove
ensureFileGroups(): pravi grupe „Files“ i „Private files“ ako ne postoje i upisuje ih ufileskonfiguracije. Bez konfiguracije poziv vraćano_config. - Aplikacija šalje fajl sa
uploadFile(file, {collection, slot, onProgress}); poziv čeka koliko traje slanje i vraća{ok: true, file: {file, name, size, type}}. - Vrednost navodi fajl pod svojim mestom (u mapi odgovora,
under):{file: <id>, …}. - Za prikaz,
fileUrl(id)daje adresu koja važi deset minuta:{ok: true, url, name, type, size}.
async function attach(input: HTMLInputElement) {
const file = input.files?.[0];
if (!file) return;
const sent = await window.potok.uploadFile(file, {
collection: 'applications',
slot: 'cv',
onProgress: (percent) => console.log(`${percent}%`),
});
if (!sent.ok) return console.error(sent.message ?? sent.error);
const saved = await window.potok.insertValue(
{ a: { name: 'Ana', cv: [{ file: sent.file.file, name: sent.file.name }] } },
{ collection: 'applications' },
);
if (!saved.ok) console.error(saved.message ?? saved.error);
}
const input = document.querySelector<HTMLInputElement>('.app-cv');
input?.addEventListener('change', () => void attach(input), potok.eventListenerOptions);
uploadImage(file, {onProgress?})je za urednike: slika same aplikacije (logo, naslovna), sa adresom ufile.urlkoju otvara svako ko vidi aplikaciju.invalid_files: fajl ne postoji ili ne odgovara mestu;files_missing: grupa za fajlove je nestala;files_exposed: privatna grupa za fajlove više nije zatvorena.- Fajl mora biti pošiljaočev, poslat za to mesto, i ne sme pripadati drugoj vrednosti. Fajl koji nijedna vrednost ne preuzme briše se posle dan. Fajlovi aplikacije zauzimaju najviše 1 GB.
9.8. Kvizovi
Pravilo sa score čini kolekciju kvizom: potok svaku vrednost boduje po ključu iz secret.score i u vrednost upisuje managed.
- Ključ:
secret.score[kolekcija][pitanje] - Za svako pitanje
{points, …}sa jednom proverom:eq(jedan izbor),set(tačno ti izbori),text(bilo koji od tih tekstova; uzothers_wrongostali su netačni, inače čekaju urednika),rowsirow_sets(tabele),manual(boduje urednik). Opcionookibad: poruke za tačan i netačan odgovor. score.release,score.released,score.show"immediate"ili"manual";released: trueobjavljuje bodove;showbira šta autor vidi (missed,correct,points).managed- Ocena vrednosti, koliko je gledalac sme da vidi:
score,max,pending(odgovori koji čekaju urednika) iitemspo pitanju (ok,points,graded,feedback,expected). gradeValue(id, items)- Bodovi i reči urednika:
{pitanje: {points, feedback}};points: nullvraća odgovor ključu. summarizeValues(collection, {under?, keys?, score?})- Brojevi nad odgovorima:
{ok: true, summary: {total, keys, score}}. Za svaki ključ koliko je odgovorilo i najveće grupe odgovora;score: truedodaje prosek, medijanu, raspodelu i rezultate po pitanju. Kolekcija bez kviza dajenot_scored, a bezunderinvalid_summary.
import type { PotokConfigData } from './potok';
const quiz: PotokConfigData = {
rules: {
quiz: { write: ['everyone'], once: true, under: ['a'], score: { release: 'immediate', show: { correct: true, points: true } } },
},
secret: { score: { quiz: { q1: { points: 2, eq: 'o3', ok: 'Tačno!', bad: 'Pogledaj poglavlje 3.' } } } },
};
async function results() {
const reply = await window.potok.summarizeValues('quiz', { keys: ['q1'], score: true });
if (!reply.ok) return console.error(reply.error);
console.log(reply.summary.total, reply.summary.score?.average);
}
console.log(Object.keys(quiz.rules ?? {}));
void results();
Nov ključ ponovo boduje sve, a ocene urednika ostaju. "immediate" ne ide uz edit_own, i posle objave niko ne menja vrednost.
9.9. Obaveštenja
setNotifications(collection, on) uključuje ili isključuje gledaočevo obaveštenje (push) za svaku novu vrednost kolekcije; vraća {ok: true, on}. Stanje se vidi u caps[kolekcija].notify.
Obaveštenje dobija samo onaj ko čita celu kolekciju, samo za nove vrednosti (ne za izmene), nikad autor, i bez imena kad je kolekcija anonimna.
9.10. Greške i granice
| Kod | Kada |
|---|---|
closed | pravilo više ne prima vrednosti (zatvoreno ili posle roka) |
already_answered | once: osoba već ima vrednost |
released | bodovi su objavljeni, vrednost se više ne menja |
conflict | neko je sačuvao u međuvremenu; current je ono što je sada tamo |
too_large | vrednost preko 64 KB ili konfiguracija preko 512 KB kao JSON |
invalid_collection | loše ili rezervisano ime kolekcije |
invalid_rules | pravila koja ne mogu da važe; reason kaže koje |
invalid_files, files_missing, files_exposed | fajlovi (odeljak 9.7) |
no_config | poziv traži konfiguraciju, a nje nema |
not_scored, invalid_summary | zbirovi kviza (odeljak 9.8) |
Strana kolekcije ima najviše 100 vrednosti; vrednost najviše 64 KB, a konfiguracija 512 KB kao JSON.
Dev mock drži pravila kao server, za gledaoca koga glumi ?viewer=: editor (podrazumevano, admin), reader (uloga „pregled“), member (uloga „ispitanik“), outsider (prijavljen, nije član) ili guest. Konfiguracija svake aplikacije je u potok-dev:config, uključena obaveštenja u potok-dev:notify, a fajlovi poslati iz okvira žive do osvežavanja.
Aplikacija Forma u potok-u (šablon „Forma“) napravljena je na kolekcijama: pitanja, prava, fajlovi, kviz i proces za svaki odgovor. Njen opis u dokumentaciji potok-ide je dobar primer celine.