Datastoret ja data

Näyttö ei puhu suoraan tietokannan kanssa: se puhuu datastorejen kanssa — näytön datasäiliöiden, jotka lataavat tietueita sovelluksen taulu-API:en kautta. Widgetit sidotaan datastoreihin: Taulukko näyttää listadatastoren rivit, lomakkeen kentät lukevat ja kirjoittavat tietuedatastoreen.

Tämä on kahden luvun välinen lenkki: taulu-API:t luodaan datamallin päälle (luku API:t & GraphQL); täällä näyttö sidotaan niihin.

#Datastoren kaksi tyyppiä

Tyyppi	Mitä se lataa	Mihin
Tietue	YHDEN tietueen (tai uuden, tyhjän tietueen)	Lomakkeet: kentät sidotaan tietueen kenttiin, ja lopuksi tallennetaan.
Lista	Kokoelman tietueita	Taulukot, listat, kortit, kaaviot, kanbanit, kalenterit.

Datastoret voivat asua kahdessa paikassa:

• Näytöllä — luotuina inspectorissa ilman valintaa, kategoriassa Data. Ne ovat jaettuja: useat widgetit voivat lukea samasta, ja tätä käytetään lomakkeisiin ja isäntä–detalji-suhteisiin.
• Widgetin sisällä — datawidgeteillä (Taulukko, Kaavio, KPI…) on oma datastorensa niiden omassa Data-kategoriassa. Tämä on yleisin tapaus itsenäisille ruudukoille ja kaavioille.

Moottori on sama molemmissa paikoissa; ainoa ero on suodattimissa käytettävissä olevissa arvolähteissä (katso sidonnat).

#Datastoren luominen näytölle

1. Napsauta canvasin tyhjää aluetta, jotta inspector näyttää näytön.
2. Napsauta kategoriassa Data kohtaa + tietue tai + lista.
3. Napsauta luotua datastorea avataksesi modaalin Määritä datastore.
4. Anna sille Datastoren nimi — tällä nimellä widgetit ja koodi löytävät sen (esim. conta, contas).
5. Valitse kohdassa Taulu-API se API, joka tarjoilee datan. API:n kentät tulevat käytettäviksi sarakkeisiin, sidontoihin ja suodattimiin.

#Tietuedatastore — mikä tietue ladataan

Tietuedatastore vastaa yhteen kysymykseen: mikä tietue? Vastaus annetaan kohdassa Mikä tietue ladataan (avain):

1. Napsauta + avainkenttä.
2. Valitse kenttä (oletuksena pääavain), operaattori ja arvo — tyypillisesti reitin Param: näyttö Ficha de Conta saa osoitteessa id:n ja lataa asiakkuuden, jolla on se id.
3. Useat ehdot muodostavat yhdistelmäavaimen — kaikkien on täsmättävä.

Ilman ehtoja datastore lataa uuden (tyhjän) tietueen — näin sama lomakenäyttö kelpaa luomiseen: ilman id:tä avattuna se alkaa tyhjänä; tallennettuna se tekee lisäyksen.

#Listadatastore — suodattimet ja lataus

#Suodattimet (where)

Suodattimet (where) ovat ehtoja, joita sovelletaan aina kun dataa luetaan — täällä rajataan se, mitä tietokannasta tulee. Jokainen ehto on kenttä / operaattori / arvo; + lisää suodatin lisää ehtoja ja + ryhmä luo sisäkkäisiä aliryhmiä, joissa Kaikki (AND) tai Mikä tahansa (OR) päättää, miten ne yhdistyvät.

Esimerkki Asiakashallinnasta: näyttö Contas suodattaa estado eq "activa"; paneeli ”omat asiakkuuteni” lisää gestor eq → Istunto ▸ username.

#Lataus ja sivu

Asetus	Mitä se tekee
Lataa kaikki	Tuo kaikki suodattimen tietueet kerralla — sivun vaihtaminen, järjestäminen ja suodattaminen näytöllä on välitöntä.
Sivu kerrallaan	Käy palvelimella jokaisella sivunvaihdolla — suurille tauluille, joissa kaiken tuominen ei ole järkevää.
Sivua kohden	Montako riviä näytöllä näkyy kerralla — ei pidä sekoittaa siihen, montako tietuetta luetaan.
Lataa automaattisesti	Lue data heti kun näyttö avautuu. Kytke pois, jos haluat ladata vasta toiminnon jälkeen (esimerkiksi ”Hae”-painike).

#Sidonnat — mistä arvo tulee

Aina kun suodatin, avain tai ominaisuus tarvitsee arvon, käytät samaa palasta: sidontaa. Ensimmäinen valitsin kertoo lähteen; loput muuttuvat sen mukaan:

Lähde	Mikä se on
Kiinteä	Siihen paikkaan kirjoitettu arvo, sama kaikille.
Param	Näytön reitin parametri (osio Reitin parametrit).
Istunto	Kirjautuneen käyttäjän kenttä (userId, username, name).
Tila	Sovelluksen muistiin komennolla keplin.state.set() tallennettu arvo — käytettävissä kaikilla näytöillä.
Datastore	Näytön toisen datastoren kenttä — isäntä–detaljin perusta.
Widget	Toisen input-widgetin nykyinen arvo — interaktiivisten suodattimien perusta.

Lähteet Datastore ja Widget ovat olemassa vain widgettien sisäisissä datastoreissa — ne riippuvat näytön muusta sisällöstä. Näytön datastoreille jäävät neljä ensimmäistä.

Näillä palasilla kootaan arjen mallit ilman koodia:

• Isäntä–detalji — asiakkuuden myyntimahdollisuuksien taulukko: taulukon datastoressa suodatin contaId eq → Datastore ▸ conta ▸ id. Toisen asiakkuuden valinta lataa detaljin uudelleen.
• Tekstisuodatin — Tekstikenttä ”hae” ja taulukon datastoressa nome contains → Widget ▸ kyseinen kenttä. (Jos haluat suodattaa vasta painiketta napsautettaessa, se tehdään tapahtumalla — katso Tapahtumat ja SDK.)

#Lomakekenttien sitominen tietueeseen

Jokaisella lomakekentällä on kategoriassa Data osio Datasidonta: valitse tietuedatastore ja kenttä. Siitä lähtien input näyttää ladatun arvon ja muutokset jäävät datastoreen — tallentamatta — kunnes joku tallentaa.

Viimeinen askel on painike, jonka tapahtuma tallentaa:

const ok = await keplin.data.store("conta").save();
if (ok) {
  keplin.ui.toast("Tallennettu.", "success");
}

Tämä koodi on täsmälleen se, minkä tapahtumaeditorin valmis toiminto Tallenna datastore kirjoittaa puolestasi. save() validoi ensin (pakolliset, säännöt, validointiskriptit) ja tallentaa vain jos kaikki menee läpi; se palauttaa true, jos tallennus tapahtui.

#Modaali Määritä datastore, kenttä kentältä

Kenttä	Tietue	Lista
Datastoren nimi	✓	✓
Taulu-API	✓	✓
Mikä tietue ladataan (avain)	✓	—
Suodattimet (where)	—	✓
Lataus / Sivua kohden	—	✓
Lataa automaattisesti	✓	✓

#Datastoret julkisilla näytöillä

Näytöllä, joka on merkitty Julkinen näyttö (ilman istuntoa), data tulee vain API:sta, joilla on julkinen luku: valitsin näyttää vain ne, ja jo valittu API, joka ei ole julkinen, saa merkinnän — Tällä API:lla ei ole julkista lukuoikeutta — istunnottomalla näytöllä se ei lataa dataa. Luku merkitään julkiseksi API:n editorissa.

#Data koodissa

Kaikki, mitä datastoret tekevät, on myös tapahtumien SDK:ssa — keplin.data.store("nimi") palauttaa datastoren nimellä, mukanaan reload(), setWhere(), get()/set()/save() ja kumppanit. Luku Tapahtumat ja SDK käy sen läpi.

#Miksi ei…?

• Miksi data ei lataudu? Tarkista järjestyksessä: onko Lataa automaattisesti päällä? Onko valittu API olemassa ja julkaistu? Onko julkisella näytöllä API:n luku julkinen? Eikö suodatin sulje kaikkea pois?
• Miksi aukeaa aina tyhjä tietue? Tietuedatastorella ei ole ehtoja kohdassa Mikä tietue ladataan (avain) — tai ehdossa käytetty parametri ei tule perille reitissä.
• Miksi muutin mallia eikä uusi sarake näy? Datastore säilyttää kuvan API:n kentistä siltä hetkeltä, kun valitsit sen. Avaa Määritä datastore uudelleen ja valitse API taas, niin kuva päivittyy.
• Miksi sivutus on hidas? Olet tilassa Sivu kerrallaan ja palvelimella käydään usein — tai tilassa Lataa kaikki ilman suodattimia valtavassa taulussa. Sovita tila datan todelliseen kokoon.