11. Podgrupe i navigacija
Poglavlje 11

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 beforeId sa id-jem poslednje grupe prethodne.
from, to
Trenuci u ISO 8601 sa zonom; ostaju grupe objavljene u tom periodu. from ulazi u period, to ne. Šalji ih uz svaku stranu. Loš trenutak daje invalid_date.
aroundId
Umesto prve strane, grupe oko te jedne, ma koliko duboko stajala: do limit sa svake strane, a has_newer kaže da iznad njih ima još. Grupa koje nema u listi daje prvu stranu, pa proveri da li je njen id u groups.

11.2. Šta podgrupa nosi

PoljeZnačenje
id, name, picture_url, is_public, inherits_membersgrupa, slika (bez sesije, i za privatnu grupu), javnost, nasleđivanje članova
description_htmlopis 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_atnapravljena, poslednji put otvorena (ili null), najnovija poruka u chatu
comment_countbroj 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_idautor; 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);
Napomena

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 daje invalid_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

shareGroup(id, {inApp?}) otvara način deljenja koji ima stranica, sa linkom grupe do koje stiže openGroup. Okvir nema ni Web Share ni clipboard, pa sam ne može. Sa inApp: true link vodi na ovu aplikaciju otvorenu na toj grupi, koja mora biti ispod nje.

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: description je null za grupu koju gledalac ne sme da menja i za aplikaciju. Uz polja podgrupe ima description_format, can_edit, inherit_role_keys, member_count, updated_at, key, lat, lng i pin.
createChild(attrs)
Nova podgrupa; gledalac postaje njen admin. Bez isPublic ili inheritsMembers grupu 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 sa invalid_group i njenim index-om; više od 100 je too_large. Podgrupa čiji key već 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 (null za prazan tekst). Troši limit upisa, pa ga zovi sa pauzom.

attrs su {name, description, descriptionFormat, isPublic, inheritsMembers, inheritRoleKeys, picture, lat, lng, pin}:

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.

Dev mock

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.