Tapahtumat ja SDK

Moni näyttö syntyy ilman riviäkään koodia: datastore sidotaan, widgetit vedetään, painike osoitetaan toiselle näytölle. Mutta ennemmin tai myöhemmin vastaan tulee ”kun tämä tapahtuu, tee tuo” — tallenna ja palaa, lataa taulukko uudelleen suodattimen jälkeen, vahvista ennen poistamista, avaa modaali ja käytä sen palauttamaa arvoa.

Sitä varten ovat tapahtumat: näytön kohdat, joissa suoritetaan omaa koodiasi, kirjoitettuna TypeScriptillä, SDK:n kanssa — keplin-objekti — joka antaa pääsyn kaikkeen, mitä näytöllä on.

#Missä tapahtumat ovat

Inspectorissa widgetin (ja itse näytön) viimeinen kategoria on nimeltään Tapahtumat. Siinä on rivi jokaista käytettävissä olevaa tapahtumaa kohden, ja jokaisella rivillä:

• piste vasemmalla: täytetty, kun tapahtumalla on jo koodia, tyhjä kun ei ole;
• painike … oikealla, joka avaa editorin.

Tapahtumien nimiä ei käännetä — ne ovat samat kaikilla kielillä (onClick, onRowClick, onLoad), koska ne ovat myös ne nimet, jotka näkyvät koodissa ja Radarin merkinnöissä.

#Näytön tapahtumat

Napsauta canvasin tyhjää aluetta, jotta inspector näyttää näytön. Kategoriassa Tapahtumat on kolme:

Tapahtuma	Milloin se laukeaa	Mihin
onLoad	Kerran, kun näyttö avautuu.	Tilan valmistelu, sellaisen lataaminen mitä datastoret eivät lataa, tervetulotoivotukset.
onParamsChange	Aina kun reitin parametrit muuttuvat — ja ei ensimmäisellä avauksella.	Tietueen vaihtoon reagointi avaamatta näyttöä uudelleen.
onUnload	Kun näytöltä poistutaan.	Tilan siivoaminen, luonnosten tallentaminen.

#Kunkin widgetin tapahtumat

Jokainen widgettityyppi ilmoittaa omansa. Nimen lisäksi kiinnostaa payload — data, jonka tapahtuma tuo mukanaan ja jonka koodi lukee kohteesta keplin.event.

#Lomakekentät

Widgetti	Tapahtumat	keplin.event
Tekstikenttä, Tekstialue, Numero, Kyllä/Ei, Pudotusvalikko, Päivämäärä, Väri	onChange	{ value }
Tiedosto	onChange, onUpload	onUpload: { file, name }

#Toiminnot ja navigointi

Widgetti	Tapahtumat	keplin.event
Painike	onClick	{}
Valikkopainike	onClick, onMenuItem	onMenuItem: { id, label }
Linkki	onClick	{}
Vie	onExport, onDataLoaded	onExport: { rows, filename }

#Rakenne ja sisältö

Widgetti	Tapahtumat	keplin.event
Välilehdet	onTabChange	{ tab }
Raportti	onLoad	{ report }

#Datawidgetit

Widgetti	Tapahtumat	keplin.event
Taulukko	onRowClick, onRowDoubleClick, onSelectionChange, onDataLoaded	{ row, index } · onSelectionChange: { row, rows }
Lista, Kortit	onRowClick, onDataLoaded	{ row, index }
Kaavio	onClick	{ name, seriesName, value, dataIndex }
KPI	onClick, onDataLoaded	{ value, indicatorId }

#Taulut ja suunnittelu

Widgetti	Tapahtumat	keplin.event
Kanban	onCardClick, onCardCreate, onCardMoved, onDataLoaded	{ row } · { column } · { row, from, to, index }
Kalenteri	onEventClick, onDayClick, onRangeSelect, onRangeChange, onDataLoaded	{ row } · { date } · { start, end } · { start, end, view }
Gantt	onBarClick, onEmptyClick, onDataLoaded	{ row } · { date }

#Prosessit

Widgetti	Tapahtumat	keplin.event
Prosessin tila	onDecide	{ task, outcome }
Omat tehtävät	onOpen, onDecide	{ task, screenId }

#Koodieditori

Tapahtuman painike … avaa editorin modaalissa. Otsikko kertoo, missä olet: widgetin id (tai näytön nimi) ja tapahtuman nimi — w_fic_sav1 · onClick.

Painike	Mitä se tekee
Lisää toiminto	Kirjoittaa puolestasi yleisen tehtävän koodin (alla).
Poista käsittelijä	Poistaa tämän tapahtuman koodin. Piste palaa tyhjäksi.
Peruuta	Sulkee tallentamatta.
Tallenna	Tarkistaa ja tallentaa.

Editorissa on ehdotukset kirjoittaessasi (Ctrl+Väli): koko keplin on esitelty oikeine tyyppeineen — ja mikä parasta, tämän näytön widgettien id:t ovat siellä sisällä. Kirjoittamalla keplin.widgets.get(" näet näytön widgettien listan, ja id, jota ei ole olemassa, merkitään virheeksi ennen tallennusta.

#Valmiit toiminnot

Lisää toiminto avaa listan yleisimmistä tehtävistä. Valitset yhden ja koodi kirjoitetaan jo olemassa olevan perään, valmiiksi näyttösi oikeilla nimillä — ensimmäinen tietuedatastore, ensimmäinen taulukko, ensimmäinen tekstikenttä.

Toiminto	Mitä se kirjoittaa
Tallenna datastore	Validoi ja tallentaa tietueen, onnistumisilmoituksella.
Lataa datastore uudelleen	Lukee datastoren datan uudelleen.
Suodata datastorea (tekstillä)	Lukee tekstin kentästä ja soveltaa sen suodattimena.
Siirry näytölle	Hyppää sovelluksen toiselle reitille.
Lataa taulukko uudelleen	Päivittää taulukkowidgetin datan.
Suodata taulukkoa tekstikentän arvolla	Klassinen interaktiivinen suodatin.
Näytä tai piilota widget	Vaihtaa widgetin näkyvyyttä.
Vahvista ja näytä ilmoitus	Kysyy ennen toimintaa ja ilmoittaa lopuksi.
Käynnistä työnkulku	Panee prosessin liikkeelle nykyisen tietueen päälle.
Näytä ja suorita tehtäviä	Listaa käyttäjän tehtävät ja päättää yhden.
Lähetä signaali työnkululle	Herättää odottamassa olleet prosessit.
Kirjaudu ulos	Poistuu sovelluksesta.

Lisätty koodi on lähtökohta: se on sinun, ja sitä on tarkoitus muokata. Sitä ei luoda uudelleen.

#Miten koodi suoritetaan

Jokainen tapahtuma on asynkroninen funktio, joka saa yhden ainoan asian: keplinin. Siitä seuraa kolme käytännön asiaa:

• await toimii koodin ylimmällä tasolla. Mitään ei tarvitse kääriä.
• return poistuu tapahtumasta. Se on normaali tapa luovuttaa kesken (esimerkiksi kun vahvistus hylättiin).
• Parametreja ei ole. Konteksti tulee itse keplinin sisällä: keplin.event tuo payloadin ja keplin.ctx kertoo, missä olet (ctx.widget on lauennut widgetti — null näytön tapahtumissa —, ctx.event on tapahtuman nimi ja ctx.screen näyttö).

Niin kauan kuin painikkeen koodi ei ole valmis, painike näyttää kolme animoitua pistettä: käyttäjä ymmärtää, että sovellus työskentelee. Jos koodi kaatuu, näyttö ei hajoa: näkyviin tulee varoitus ja virhe kirjataan Radariin, mukanaan näyttö, widgetti ja tapahtuma, jossa se tapahtui.

#keplin-SDK

Kaikki, mitä koodi voi tehdä, on keplinin alla. Nämä ovat alueet:

Alue	Mihin
keplin.event / keplin.ctx	Tapahtuman payload ja konteksti, jossa se suoritetaan.
keplin.widgets	Näytön widgettien kanssa puhuminen.
keplin.data	Datastoret: lukeminen, kirjoittaminen, suodattaminen, tallentaminen.
keplin.nav	Navigointi ja reitin parametrien lukeminen.
keplin.ui	Ilmoitukset, vahvistukset ja modaalit.
keplin.state	Näyttöjen välillä jaettu tila.
keplin.session	Kuka sovellusta käyttää, ja mitä hän saa tehdä.
keplin.auth	Kirjautuminen, rekisteröityminen ja salasanan palautus (järjestelmänäytöt).
keplin.i18n	Käännetyt lauseet.
keplin.storage	Laitteelle tallennetut asetukset.
keplin.api	Sovelluksen API:en kutsuminen suoraan.
keplin.reports	Raporttien avaaminen ja lataaminen.
keplin.workflow	Prosessien käynnistäminen, tehtävien listaaminen ja päättäminen.

#Widgetit

keplin.widgets.get("id") palauttaa widgetin handlen. Kaikilla handleilla on sama perusta:

const w = keplin.widgets.get("w_fic_tel1");
w.show();               // näytä
w.hide();               // piilota
w.setEnabled(false);    // poista käytöstä
w.set("label", "Matkapuhelin");   // muuta mitä tahansa inspectorin ominaisuutta
w.get("label");         // lue todellinen arvo
w.reset();              // unohda suorituksen aikana tehdyt muutokset

Ja sitten jokainen perhe lisää sen, mikä on sille ominaista:

Perhe	Mitä se lisää
Lomakekentät	getValue(), setValue(v), validate(), error
Datawidgetit (Taulukko, Lista, Kortit, Kaavio, KPI, Kanban, Kalenteri, Gantt)	rows, total, refresh(), setFilter(where), setSort(sort)
Taulukko	selectedRow, selectedRows, clearSelection()
KPI	value, values, valueOf(indicatorId)
Kanban	columns, moveCard(id, sarake, indeksi?)
Kalenteri	view, start, end, goTo(päivämäärä), setView(näkymä)
Gantt	zoom, setZoom(z)
Välilehdet	activeTab, tab("id") — ja välilehdellä activate(), show(), hide(), setEnabled()
Nimike / Painike / Linkki / Murupolku	setText(t) / setLabel(t)
Markdown	setContent(md)
Ulkoinen sivu	setUrl(url), reload()
Vie	export()
Raportti	url, download()

#Data

keplin.data.store("nimi") palauttaa näytön datastoren nimellä (katso Datastoret ja data).

Tietuedatastoressa:

const conta = keplin.data.store("conta");
conta.get("nome");                 // lue kenttä
conta.set("estado", "ativo");      // kirjoita kenttä (jää tallentamatta)
conta.record();                    // koko tietue
conta.isDirty();                   // onko tallentamattomia muutoksia?
conta.reset();                     // heitä muutokset pois
const ok = await conta.save();     // validoi ja tallentaa; true jos tallensi

Listadatastoressa:

const contas = keplin.data.store("contas");
contas.rows();                     // ladatut rivit
contas.total();                    // kokonaismäärä (kun palvelin antaa sen)
contas.reload();                   // lue uudelleen
contas.setWhere({ estado: { eq: "ativo" } });   // lisäsuodatin; null tyhjentää
contas.setSort([{ field: "nome", direction: "ASC" }]);
contas.goToPage(2);

Kummassakin status() kertoo, missä vaiheessa lataus on (idle, loading, ready, error).

#Navigointi

keplin.nav.go("/ficha-de-conta/17");   // siirry reitille (parametreineen)
keplin.nav.back();                      // palaa taaksepäin
keplin.nav.params;                      // nykyisen näytön parametrit nimeltä

#Ilmoitukset, vahvistukset ja modaalit

keplin.ui.toast("Tallennettu.", "success");    // "success" | "error" | "info"
const ok = await keplin.ui.confirm("Poistetaanko tietue?");
if (!ok) return;

Vahvistus on sovelluksen teemalla varustettu dialogi — ei koskaan selaimen harmaa laatikko.

#Tila, istunto ja asetukset

keplin.state.set("filtroContas", "activas");   // elää niin kauan kuin välilehti on auki
keplin.state.get("filtroContas");
keplin.state.remove("filtroContas");

keplin.session.user;              // { id, username, name } — null julkisilla näytöillä
keplin.session.roles;             // käyttäjän roolit
keplin.session.can("contas.editar");   // onko tämä toiminto? (Asetukset ▸ Käyttöoikeudet)
await keplin.session.logout();

keplin.storage.set("colunasContas", ["nome", "cidade"]);   // jää laitteelle
keplin.storage.get("colunasContas");

#API:t ja raportit

const linhas = await keplin.api.query("contas", { estado: "ativo" }, ["id", "nome"]);
await keplin.api.mutate("criarConta", { nome: "Nova" }, ["id"]);

keplin.reports.open("Contactos da conta", { contaId: 17 });
keplin.reports.download("Contactos da conta", { contaId: 17 }, "xlsx");

Kyselyssä kenttälista on pakollinen — juuri se kertoo, mitä haluat tuoda.

#Työnkulut

const registo = keplin.data.store("oportunidade").get("id");
await keplin.workflow.start("wf_aprovacao", registo);

const tarefas = await keplin.workflow.tasks();
await keplin.workflow.complete(tarefas[0].id, "aprovar");

const { woken } = await keplin.workflow.signal("documento-recebido", registo);

#Käännetyt lauseet

keplin.i18n.t("{n} contas activas", { n: linhas.length });
keplin.i18n.locale;

#Modaalinäytöt

Keplinin näyttö ei ole modaali koska se avattiin tietyllä tavalla — se on modaali koska se on määritetty sellaiseksi. Päätös on näytön inspectorissa, kategoriassa Esitystapa:

Asetus	Mitä se tekee
Tila	Näyttö (tavallinen sivu), Modaali (keskellä) tai Sivupaneeli (oikealla).
Leveys (px) / Korkeus (px)	Modaalin koko. Sivupaneeli käyttää koko korkeuden.
Sulkupainike	Näyttää ×:n kulmassa.
Napsautus ulkopuolelle sulkee / Esc sulkee	Kaksi tavanomaista poistumistietä.
Päivitä taustalla oleva näyttö suljettaessa	Suljettaessa kutsuneen näytön datastoret lukevat uudelleen.

Osion oma vihje tiivistää: Avautuu kutsuvan näytön PÄÄLLE (Linkki, tapahtumat tai keplin.ui.openModal). Ei mukana suorassa navigoinnissa.

#Avaaminen ja sulkeminen koodilla

const resultado = await keplin.ui.openModal("/nova-conta", { setor: "banca" });
if (resultado) {
  keplin.data.store("contas").reload();
}

• openModal saa näytön reitin (tai id:n) ja valinnaisesti parametrit.
• Lupaus ratkeaa vasta kun modaali sulkeutuu, ja tuo mukanaan arvon, jonka modaali palautti.
• Modaalin sisällä keplin.ui.closeModal(arvo) sulkee ja palauttaa sen arvon.
• Modaalit pinoutuvat: modaali voi avata toisen.

#Reseptejä

Tallenna ja palaa (Ficha de Contan Tallenna-painikkeen onClick):

const ok = await keplin.data.store("conta").save();
if (ok) {
  keplin.ui.toast("Asiakkuus tallennettu");
  keplin.nav.go("/contas");
}

Avaa napsautetun rivin tiedot (Taulukon onRowClick):

keplin.nav.go(`/ficha-de-conta/${keplin.event.row["id"]}`);

Suodata taulukkoa tekstikentällä (kentän onChange — korvaa id:t oman näyttösi id:illä):

const texto = keplin.widgets.get("w_pesquisa").getValue();
keplin.widgets.get("w_cta_tab1").setFilter(texto ? { nome: { contains: texto } } : null);

Vahvista ennen tuhoavaa toimintoa (painikkeen onClick):

if (!(await keplin.ui.confirm("Poistetaanko tämä asiakkuus?"))) return;

Piilota painike siltä, joka ei saa (näytön onLoad):

if (!keplin.session.can("contas.eliminar")) {
  keplin.widgets.get("w_apagar").hide();
}

#Miksi ei…?

• Miksi tapahtumaa ei anneta tallentaa? Koodi ei käänny. Ilmoitus on Tapahtumaa ei tallennettu: koodi ei ole suoritettavissa — korjaa ja tallenna.
• Miksi keplin.widgets.get("...") antaa virheen? Id:tä ei ole tällä näytöllä. Varmista se inspectorin yläreunasta widgetti valittuna; ja muista, että jokainen laite on oma puunsa (katso Layoutit ja laitekohtainen ulkoasu).
• Miksi onParamsChange ei lauennut avattaessa? Se on tarkoituksellista: se laukeaa vain muutoksista. Käytä käynnistykseen onLoadia.
• Miksi modaali ei palauta mitään? Joko kohdenäyttöä ei ole olemassa, tai käyttäjällä ei ole oikeutta avata sitä — molemmissa tapauksissa lupaus ratkeaa ilman arvoa. Varmista reitti ja käyttöoikeudet.
• Miksi raportin ikkuna ei avaudu? Panit openin awaitin jälkeen. Avaa ensin.
• Miksi tapahtumani ei näytä suorittuvan? Katso Radar: tapahtumien koodin virheet ovat siellä, näyttöineen, widgetteineen ja tapahtumineen — ja Radar vie sinut suoraan kyseisen tapahtuman editoriin.