12. Mape i glasanja
Poglavlje 12

Mape i glasanja

Dve oblasti u kojima aplikacija koristi ono što potok već ima: mesta na mapi (podgrupe sa lokacijom, njihove pinove, oblasti i rute) i glasanja grupe. U obe aplikacija čita, a za ono što zahteva potok-ov interfejs (glasanje, forma za novo glasanje, mapa korena) otvara potok-ov dijalog ili stranu.

12.1. Pre prvog pina: getMapConfig

getMapConfig() vraća sve što mapi treba pre prvog pina:

tiles
{url, attribution, max_zoom}. Pločice idu preko potok-a: url ima {z}, {x} i {y}, a attribution je HTML koji se prikazuje.
default_bounds
[[jug, zapad], [sever, istok]], kao što ih prima Leaflet: gde se mapa otvara dok urednici ne sačuvaju svoj pogled.
pins
Crteži pinova: drop (kapljica kao SVG putanja na polju 32×40, vrh u (16, 39)), glyph_transform i mark_transform (gde idu znak i oznaka vrste), tones (boja svakog tona, #rrggbb), kinds (izgled po vrsti grupe) i icons (ikonice koje grupa može da izabere). Svaki izgled ima key, title na jeziku gledaoca, tone i paths.
place_kinds, can_create_places, can_edit_view
Vrste za createPlace; da li gledalac sme da pravi mesta; da li sme da sačuva pogled mape u konfiguraciji.

Crteži dolaze sa stranice, pa nov pin ne traži novu aplikaciju.

12.2. Mesta: listPlaces

listPlaces() vraća podgrupe direktno ispod ove grupe koje gledalac vidi i koje imaju mesto, do 2000: {ok: true, places, truncated}. Dublje grupe nisu na mapi.

Polje mestaZnačenje
id, name, lat, lnggrupa i tačka pina; za oblast tačka u njoj, za rutu njen početak
kind, pin, picture_url, is_publicključ iz pins.kinds; ključ iz pins.icons, "picture" za sliku grupe ili null za izgled vrste
shape"point", "area" (grupa pokriva oblast) ili "route" (grupa ide duž linije, npr. staza)
areasoblasti među mestima koje sadrže ovo, od najmanje
bbox, v, lengthokvir oblasti ili rute [zapad, jug, istok, sever]; broj koji se menja sa oblikom; dužina rute u metrima

12.3. Velike mape: listPlaces(view)

Sa pogledom {bbox, zoom, search?, pins?, extent?, counts?}, mapa do 2000 mesta dobija sva mesta, kao bez pogleda, sa mode: "all", i sama ih filtrira. Veća mapa dobija ono što pogled prikazuje, a potok mesta skuplja u ćelije od oko 64 piksela (mode: "view"):

Kad se pogled pomeri, pitaj ponovo. Pogled sporiji od 4 s daje timeout. Stariji potok, od pre pogleda, ne šalje mode.

async function draw(bbox: [number, number, number, number], zoom: number) {
  const reply = await window.potok.listPlaces({ bbox, zoom, counts: true });
  if (!reply.ok) return console.error(reply.error);

  if (reply.mode === 'view') {
    console.log(reply.places.length, 'pinova,', reply.clusters.length, 'grupa od', reply.total);
  } else {
    // up to 2000 places: all of them; filter and gather in the app
    console.log(reply.places.length, 'mesta', reply.truncated ? '(skraćeno)' : '');
  }
}

void draw([19.7, 45.2, 20.0, 45.3], 13);
listPlacesAt(bounds, {search?, pins?})
Mesta čiji su pinovi u bounds (ivice uključene), po imenu, najviše 50, sa has_more: ono što klaster drži, a mapa ne može dalje da raširi.
placeShapes(ids, zoom)
Granice oblasti i linije ruta (najviše 100 id-jeva), pojednostavljene za zoom: {ok: true, level, shapes: [{id, v, geojson}]}, gde je level jedan od 6, 8, 10, 12, 14, 16, a geojson MultiPolygon ili MultiLineString. Čuvaj ih po id, v i level.
import type { PotokPlace, PotokPlaceShape } from './potok';

const shapes = new Map<string, PotokPlaceShape>();

async function shapesFor(places: PotokPlace[], zoom: number) {
  const missing = places.filter((p) => p.shape !== 'point').map((p) => p.id).slice(0, 100);
  if (!missing.length) return;
  const reply = await window.potok.placeShapes(missing, zoom);
  if (!reply.ok) return console.error(reply.error);
  for (const shape of reply.shapes) shapes.set(`${shape.id}:${shape.v}:${reply.level}`, shape);
}

void shapesFor([], 12);

12.4. Nova mesta i mapa korena

createPlace({name, kind, lat, lng, isPublic?, pin?})
Pravi podgrupu tamo gde je gledalac dodirnuo, kao potok-ov meni „Napravi podgrupu“: kind je jedan od place_kinds, a isPublic i pin mogu da se izostave. Traži can_create_places; ime, vrsta, mesto ili pin koje ne prima daju invalid_place.
openMap({lat, lng, label?})
Vodi gledaoca, na istoj strani, na mapu korena, na tu tačku: pin sa slikom ove grupe i kartica sa njenim imenom i oznakom label (jedan red, do 80 znakova). Za mesto koje aplikacija čuva u svojim podacima; mesto same grupe ostaje kakvo jeste. Tačka van opsega daje invalid_place, a gost forbidden. Aplikacija se gasi sa stranicom.

Podgrupa kojoj aplikacija da mesto (createChild, createChildren ili updateChild sa lat i lng) takođe je mesto na mapi (poglavlje 11).

Aplikacija Mapa u potok-u (šablon „Mapa“, sa Leaflet-om) napravljena je na ovim pozivima: gusta mesta, velike mape, oblasti i rute. Njen opis u dokumentaciji potok-ide pokazuje kako se delovi slažu.

Dev mock

Mesta stoje pod ključem potok-dev:places, oblici pod potok-dev:place-shapes, a odgovor getMapConfig pod potok-dev:map-config. Aplikacija sa mapom ih sama puni u dev-u, sa shape, areas, bbox i length, jer mock ne računa geometriju. Bez sačuvane konfiguracije pločice su OpenStreetMap-ove, direktno iz pregledača, i nema pinova. Preko 2000 mesta mock ih skuplja u ćelije kao potok.

12.5. Glasanja

Aplikacija čita glasanja grupe i nudi glasanje, ali ne glasa sama: radi za svakog gledaoca, a glas može biti konačan, pa nema poziva koji glasa, završava ili menja glasanje.

listPolls({status?, beforeId?})
Glasanja ove grupe, od najnovijeg, po 30, koliko njihova pravila pokazuju gledaocu: {ok: true, polls, has_more}. status je "open", "closed" ili "waiting" (ona u kojima gledalac još može da glasa, bez strana).
getPoll(id)
{ok: true, poll}; broj koji gledalac ne sme da vidi je null.
openPoll(id)
Otvara glasanje u potok-ovom dijalogu, preko aplikacije, gde gledalac glasa.
openPollForm()
Otvara potok-ovu formu za novo glasanje, ako can_start_polls iz getGroup to dozvoljava.
onPollChange(listener)
Javlja id glasanja koje se promenilo, dobilo glas ili je obrisano, po nekoliko odjednom. Pročitaj ga ponovo sa getPoll; obrisano daje not_found. Vraća funkciju za odjavu.

Glasanje (PotokPoll) ima question, description (markdown), kind ("single" ili "multiple", uz max_choices), rokove (closes_at, closed_at, open), secret, public, šta gledalac sme (can_vote, voted, can_see_results, can_see_details, can_manage), voters_count, ishod (outcome, winner_option_id) i options: [{id, text, votes_count, mine}], gde je votes_count null dok ga pravila kriju.

import type { PotokPoll } from './potok';

const polls = new Map<number, PotokPoll>();

async function loadWaiting() {
  const reply = await window.potok.listPolls({ status: 'waiting' });
  if (!reply.ok) return console.error(reply.error);
  for (const poll of reply.polls) polls.set(poll.id, poll);
}

const stop = window.potok.onPollChange(async (id) => {
  const reply = await window.potok.getPoll(id);
  if (reply.ok) polls.set(id, reply.poll);
  else if (reply.error === 'not_found') polls.delete(id);
});

async function vote(id: number) {
  await window.potok.openPoll(id);   // Potok's dialog: the viewer votes there
}

void loadWaiting();
void vote(3);
window.addEventListener('pagehide', stop, potok.eventListenerOptions);
Dev mock

Glasanja stoje pod ključem potok-dev:polls, kao PotokPoll[]. Potok-ove forme i glasanja ovde nema: openPollForm dodaje glasanje, a openPoll glasa za prvi odgovor.