Podgrupe i navigacija
Grupe ispod grupe aplikacije mogu da budu njen sadržaj: objave u feed-u, događaji, mesta na mapi, zapisi. Ovo poglavlje pokriva čitanje podgrupa, vođenje gledaoca na njih, reakcije i deljenje, i pozive kojima aplikacija u ime gledaoca pravi i menja podgrupe.
11.1. Čitanje: listSubgroups
listSubgroups(name, options?) vraća grupe ispod direktne podgrupe sa tačnim imenom name, od najnovije: {ok: true, groups, has_more, has_newer}. Tako aplikacija na grupi „Vesti“ sa podgrupom „Objave“ čita objave.
limit,beforeId- Strana do 50 grupa (podrazumevano 20). Sledeća strana je
beforeIdsaid-jem poslednje grupe prethodne. from,to- Trenuci u ISO 8601 sa zonom; ostaju grupe objavljene u tom periodu.
fromulazi u period,tone. Šalji ih uz svaku stranu. Loš trenutak dajeinvalid_date. aroundId- Umesto prve strane, grupe oko te jedne, ma koliko duboko stajala: do
limitsa svake strane, ahas_newerkaže da iznad njih ima još. Grupa koje nema u listi daje prvu stranu, pa proveri da li je njenidugroups.
- Vidi ono što vidi i gledalac: bez niti, direktnih razgovora i privatnih grupa čiji gledalac nije član. Ako gledalac ne vidi ni samu podgrupu
name, odgovor jenot_found. - Imena nisu jedinstvena: od više podgrupa istog imena važi najstarija.
- Red je od najnovije, a zatvorena grupa (privatna, bez nasleđivanja) računa se od trenutka kad se otvorila, što je
published_at.
11.2. Šta podgrupa nosi
| Polje | Značenje |
|---|---|
id, name, picture_url, is_public, inherits_members | grupa, slika (bez sesije, i za privatnu grupu), javnost, nasleđivanje članova |
description_html | opis kao prečišćen HTML, bezbedan za stranicu aplikacije; element sa klasom rich-content oko njega daje stilove stranice grupe. null za grupu bez opisa, za aplikaciju (opis joj je izvorni kod) i, za gosta, za grupu koja opis krije od gostiju |
app_description, uses_api | šta aplikacija kaže o sebi u meta tagovima, kao običan tekst (poglavlje 3); null za grupe koje nisu aplikacije |
inserted_at, published_at, last_value_at | napravljena, poslednji put otvorena (ili null), najnovija poruka u chatu |
comment_count | broj poruka u chatu, bez niti |
reactions, can_react | [{emoji, count, mine}] redom kojim su emoji prvi put upotrebljeni; da li gledalac sme da reaguje |
creator_id | autor; null za gosta, koji ne saznaje ko je napravio grupu |
async function renderFeed(list: HTMLElement) {
const reply = await window.potok.listSubgroups('Objave', { limit: 20 });
if (!reply.ok) return console.error(reply.error);
list.replaceChildren(...reply.groups.map((group) => {
const article = document.createElement('article');
const title = document.createElement('h3');
title.textContent = group.name;
const body = document.createElement('div');
body.className = 'rich-content';
body.innerHTML = group.description_html ?? ''; // sanitized on the server
article.append(title, body);
return article;
}));
}
const list = document.querySelector<HTMLElement>('.app-feed');
if (list) void renderFeed(list);
11.3. Vođenje gledaoca
showGroup ostavlja aplikaciju na ekranu ispod lista, pa je dobar za „pogledaj pa se vrati“. openGroup menja stranu: posle njega tvoj kod više ne radi, a aplikacija se pokreće iznova kad se gledalac vrati.
11.4. Reakcije
toggleGroupReaction(id, emoji)- Dodaje gledaočevu reakciju na grupu ispod ove, ili je skida, kao klik na reakciju; vraća
{ok: true, reactions}. Troši limit upisa. Nešto što nije jedan emoji dajeinvalid_emoji. pickEmoji()- Gledalac bira bilo koji emoji u potok-ovom biraču:
{ok: true, emoji}. Poziv čeka koliko god treba; zatvoren birač daje{ok: false, error: "cancelled"}.
async function react(groupId: number) {
const picked = await window.potok.pickEmoji();
if (!picked.ok) return; // "cancelled": the viewer closed the picker
const reply = await window.potok.toggleGroupReaction(groupId, picked.emoji);
if (reply.ok) console.log(reply.reactions.map((r) => `${r.emoji} ${r.count}${r.mine ? ' (ti)' : ''}`));
}
void react(7);
11.5. Deljenje i link na stavku
linkGroup(id) upisuje grupu u adresu strane (?at=<id>), a getLinkedGroup() je čita. Adresu niko ne proverava, pa je aplikacija proverava sama, sa aroundId:
async function openLinked() {
const linked = await window.potok.getLinkedGroup();
const id = linked.ok ? linked.group_id : null;
const page = await window.potok.listSubgroups('Objave', id === null ? {} : { aroundId: id });
if (!page.ok) return console.error(page.error);
// A group the viewer cannot see gives the first page: look for the id.
const target = page.groups.find((group) => group.id === id);
console.log(target ? `otvori ${target.name}` : 'prva strana', page.has_newer);
}
async function select(groupId: number) {
await window.potok.linkGroup(groupId); // the address now opens the app on this post
}
void openLinked();
void select(7);
11.6. Podgrupe koje aplikacija drži
Ovi pozivi rade u ime gledaoca, pa traže gledaoca koji sme da menja grupu aplikacije (can_manage_children iz getGroup); ostali dobijaju forbidden. Dosežu samo direktne podgrupe. Pravljenje traži i create_subgroups (can_create_children), a izmena i edit_group u samoj podgrupi.
listChildren(options?)- Direktne podgrupe, istim redom i sa istim opcijama kao
listSubgroups. getChild(id){ok: true, group}sa izvorom opisa:descriptionjenullza grupu koju gledalac ne sme da menja i za aplikaciju. Uz polja podgrupe imadescription_format,can_edit,inherit_role_keys,member_count,updated_at,key,lat,lngipin.createChild(attrs)- Nova podgrupa; gledalac postaje njen admin. Bez
isPubliciliinheritsMembersgrupu vidi samo gledalac. createChildren(children, {onExisting?})- Do 100 podgrupa odjednom, sve ili nijedna, za jedan upis limita:
{ok: true, groups: [{id, key, created}]}. Podgrupa koja ne prolazi obara poziv sainvalid_groupi njenimindex-om; više od 100 jetoo_large. Podgrupa čijikeyveć postoji ne pravi se ponovo (created: false), pa se poziv koji je istekao šalje ponovo isti. updateChild(id, attrs)- Menja samo polja koja dobije. Grupu koja je aplikacija odbija sa
forbidden. Zatvorena grupa koja se otvori ide na vrh reda. withdrawChild(id)- Grupa ponovo postaje zatvorena: privatna, bez nasleđivanja, a nasleđeni članovi izlaze. Direktni članovi i gledalac ostaju.
previewDescription(text, {descriptionFormat?}){ok: true, html}: tekst onako kako će ga feed prikazati, prečišćen na serveru (nullza prazan tekst). Troši limit upisa, pa ga zovi sa pauzom.
attrs su {name, description, descriptionFormat, isPublic, inheritsMembers, inheritRoleKeys, picture, lat, lng, pin}:
inheritRoleKeysuzinheritsMemberssužava nasleđivanje na članove grupe aplikacije koji tu imaju neku od tih uloga (ključevi izlistRoles); prazan spisak ili"everyone"uzima sve članove.pictureje adresa slike ilidata:adresa, najviše 1.000.000 znakova; stiže napicture_url.latilngsu mesto na mapi, oba ili nijedno (obanulluupdateChildbrišu mesto);pinje ključ izpins.icons(poglavlje 12).key(samo ucreateChildren) je ključ aplikacije, od 1 do 64 znaka, jedinstven ispod ove grupe i upisan jednom. Grupe sa ključem su zapisi: vidi ih njihova mapa, a mapa korena ne.
import type { PotokNewChild } from './potok';
async function importShops(rows: { code: string; name: string; lat: number; lng: number }[]) {
const group = await window.potok.getGroup();
if (!group.ok || !group.group.can_create_children) return console.warn('nema prava');
const children: PotokNewChild[] = rows.map((row) => ({
key: `shop:${row.code}`, // the same key twice is not made twice
name: row.name,
isPublic: true,
lat: row.lat,
lng: row.lng,
}));
const reply = await window.potok.createChildren(children.slice(0, 100));
if (!reply.ok) return console.error(reply.error, reply.index);
console.log(reply.groups.filter((g) => g.created).length, 'novih');
}
void importShops([{ code: '001', name: 'Prodavnica kod mosta', lat: 45.25, lng: 19.85 }]);
Aplikacija ne može da postavi uses_api ni bilo šta drugo van attrs, i nema poziva za brisanje grupe: openGroup(id, {tab: "settings"}) vodi na stranu grupe za to.
11.7. Kad se podgrupe promene
onSubgroupsChange(listener) javlja da je podgrupa ove grupe napravljena, promenjena ili obrisana, i ništa više: pročitaj ponovo ono što aplikacija prikazuje. Vraća funkciju za odjavu.
Javljanje stiže svim gledaocima odjednom, pa čitaj u svom trenutku: aplikacija Mapa čeka nasumično 0–2 s.
let timer: ReturnType<typeof setTimeout> | undefined;
function reload() {
console.log('read the list again');
}
const stop = window.potok.onSubgroupsChange(() => {
clearTimeout(timer);
timer = setTimeout(reload, Math.random() * 2000); // not everyone at once
});
window.addEventListener('pagehide', stop, potok.eventListenerOptions);
Primer dve aplikacije na ovim pozivima, od kojih jedna piše ono što druga prikazuje (Feed i FeedCreator), opisan je u dokumentaciji potok-ide.
Grupe za listSubgroups stoje pod ključem potok-dev:subgroups, kao {"<ime podgrupe>": PotokSubgroup[]}, a puni ih sama aplikacija u dev-u. Podgrupe aplikacije su u potok-dev:children, a potok-dev:group menja polja koja vraća getGroup (npr. {"can_manage_children": false}). openGroup, openMap i shareGroup samo pišu u konzolu, toggleGroupReaction menja potok-dev:subgroups, a pickEmoji pita preko prompt-a.