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 API se API, joka tarjoilee datan. API:n kentät tulevat käytettäviksi sarakkeisiin, sidontoihin ja suodattimiin. Listatietovarastossa näkyvät myös pipeline-API:t, merkillä pipeline: ne palauttavat koko listan, ilman suodattimia tai sivutusta.

#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.

Jos ehdot eivät löydä yhtään tietuetta (id, jota ei enää ole tai joka on avaajan roolin ulottumattomissa), sovellus ilmoittaa, ettei pyydettyä tietuetta ole, eikä lomake tallenna. Vain näytön kenttään kirjoitettu avain (luonnollinen avain, kuten tuotekoodi) on edelleen uuden tietueen avain.

#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.

Operaattorit:

Operaattori	Mitä se vertaa
eq / neq	Yhtä suuri / eri kuin arvo. neq ottaa mukaan myös tietueet, joiden kenttä on tyhjä.
contains, startsWith, endsWith	Teksti, joka sisältää arvon, alkaa sillä tai päättyy siihen.
gt, gte, lt, lte	Suurempi, suurempi tai yhtä suuri, pienempi, pienempi tai yhtä suuri — luvut ja päivämäärät.
in / nin	Jokin näistä / ei mikään näistä arvolistasta. Arvo on lista: useita pilkuilla erotettuja arvoja, tai Widgetin kautta sidotun Monivalinta-Listan arvo — näin taulukko suodatetaan usean keskuksen tai usean tilan mukaan kerralla. nin ottaa mukaan myös tietueet, joiden kenttä on tyhjä.

Ehto, jonka arvo on tyhjä (tyhjä hakukenttä, lista ilman valintaa), ei suodata mitään — näyttö näyttää kaiken, kunnes henkilö valitsee.

Jokainen suodattimen arvo muunnetaan sarakkeen tyypin mukaan: tekstisarakkeessa henkilötunnus tai postinumero (”0012”) pysyvät tekstinä, ja desimaalisarakkeessa ”12,5” on luku.

#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).

Ilman asetusta Lataa automaattisesti lista lukee, kun joku pyytää: reload() (esimerkiksi painikkeessa ”Hae”), sivun tai järjestyksen vaihto tai käytetty suodatin. Näytön kentän muuttaminen ei saa sitä lukemaan itsestään.

Kun voimassa oleva suodatin muuttuu (näytön kenttä, parametri, sovelluksen tila), lista palaa ensimmäiselle sivulle. Jos sivua, jolla olit, ei enää ole (poistit esimerkiksi viimeisen sivun viimeisen tietueen), lista siirtyy viimeiselle olemassa olevalle sivulle.

#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.

Myös kenttä kirjoittaa tilaan: valitse kentän kohdassa Datasidonta vaihtoehto Tila ja kirjoita Avain. Suodatin, jonka lähde on Tila ja avain sama, lukee tiedot uudelleen, kun arvo muuttuu. Näin palkin widget-alue suodattaa sivut; katso Sovelluksen navigointi.

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.

Kun tallennat jo olemassa olleen tietueen, mukaan lähtevät vain kentät, jotka ovat muuttuneet lukemisen jälkeen. Tyhjennetty kenttä tallennetaan tyhjänä (null tietokannassa), ja desimaalikentässä ”12,5” luetaan lukuna.

Kun muutoksia ei ole tallennettu, sivulta poistuminen pyytää vahvistusta: valikoista, selaimen Takaisin-painikkeella tai välilehteä suljettaessa. Modaali kysyi jo sulkeutuessaan. Koodilla tehty siirtyminen (keplin.nav.go) ei kysy: kutsuja on jo päättänyt, ja on usein juuri tallentanut.

Uutta tietuetta tallennettaessa kenttää, jota näkymä ei näytä, ei lähetetä: sarakkeessa, jolla on oletusarvo tietokannassa tai jonka tietokanta tuottaa, jää voimaan se arvo; pakollisen sarakkeen, jolla ei ole oletusarvoa, on oltava näkymässä, ja lomake kertoo, mikä puuttuu. Näkymän kenttään kirjoitettu avain (luonnollinen avain, kuten nimikekoodi) kuuluu uudelle tietueelle; koodissa set()-kutsulla asetettuna se on yhä muutettavan tietueen avain. Tallennus tietueeseen, jota ei enää ole, antaa virheen eikä ilmoitusta "Tallennettu".

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

Kenttä	Tietue	Lista
Datastoren nimi	✓	✓
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. Se, mitä kukin jo valittu sarake on (tyyppi, pakollisuus, oletusarvo, päivämäärä), päivittyy itsestään näytön avautuessa; vain uudet sarakkeet on valittava.
• 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.