# gizweb:table the typed table of a page. A route file declares `const todos = table("created desc");` and reads and writes it as the records of its type; the generated code calls this module. Every read and write goes through Data and its Gate, so a page shows and changes only what the person who asks may. The SQL of `where` and `count` is made at build time from the lambda; every value in it is a parameter, so a value cannot become SQL. ```gizlang import * as Table from "gizweb:table"; ``` ## Types ### `Meter` ```gizlang type Meter = { fault: Task.Cell; reads: Task.Atomic; writes: Task.Atomic; counted: Task.Cell>; } ``` What a request of a page leaves in its tables: the first refusal or failure (the status and reason of the answer; 200 when none), and how many reads and writes it made. A page reads a table as a list, so a failed read cannot be a value of the list: it is kept here, and the host answers with it instead of a list that looks empty. - `fault`: `gizlang_task.Cell` - `reads`: `gizlang_task.Atomic` - `writes`: `gizlang_task.Atomic` - `counted`: `gizlang_task.Cell>` ### `Focus` ```gizlang type Focus = { mode: Task.Atomic; only: Task.Atomic; table: string; keys: Vec; out: Option> } ``` What a live request of a page asks (web/region.giz): the table that changed and the keys of its rows that changed (none: any row may have), the patches that the ranges of the page made, and two switches. `mode` is 1 while the page is looked through for the ranges that read the table (nothing else is rendered), 0 while a range renders. `only` is 1 while the reads of the table are limited to the rows of those keys. An ordinary request has no patches (`out` is none) and its `mode` is 0. - `mode`: `gizlang_task.Atomic` - `only`: `gizlang_task.Atomic` - `table`: `string` - `keys`: `Vec` - `out`: `_gizlang_sdk_core.Option>` ### `Context` ```gizlang type Context = { scoped: Option; sys: System; me: string; live: bool; meter: Meter; focus: Focus; } ``` What a page needs of its host: the records as the person who asks may use them (none when the host has no database), who that is, and whether the client runs the kernel (`live`: only such a client polls, so only it gets a watch). - `scoped`: `_gizlang_sdk_core.Option` - `sys`: `gizlang_system.System` - `me`: `string` - `live`: `bool` - `meter`: `M68.Meter` - `focus`: `M68.Focus` ### `Table` ```gizlang type Table = { context: Context; shape: Model.Shape; order: string; orderText: string; } ``` The records of type T that the person may read and write; ORDER is the ORDER BY of every read. Opaque: create and use it through this module's functions. ## Functions ### `meter` ```gizlang function meter(): Meter ``` A meter of one request: no fault, no reads, no writes. Effects: fail, io. ### `quiet` ```gizlang function quiet(): Focus ``` The focus of an ordinary request. Effects: io. ### `seeking` ```gizlang function seeking(table: string, keys: Vec): Focus ``` The focus of the request that tells a page of the change of the rows KEYS of the table TABLE. Effects: fail, io. ### `context` ```gizlang function context(scoped: Option, sys: System, me: string, live: bool): Context ``` The context of an ordinary request. Effects: fail, io. ### `table` ```gizlang function table(context: Context, order: string): Table ``` The table of T, ordered by ORDER (field names, each with `asc` or `desc`: "created desc, id"; empty is by key). ### `tailOf` ```gizlang function tailOf(shape: Model.Shape, order: string, limit: i64): string ``` The ORDER BY and LIMIT of a read, from field names that the Shape holds. A name it does not hold is a defect of the page. Effects: fail. ### `keyText` ```gizlang function keyText(key: Value): Option ``` The text of a key value as a page writes it (the `data-k` of a row), or none for a type that a key text cannot stand for. Effects: fail. ### `rowsGrid` ```gizlang function rowsGrid(names: Vec, rows: Vec>>): Html ``` A query's answer as a read-only `grid()`: a column for each of NAMES, a row for each of ROWS, a NULL cell `data-null`. Effects: fail. ### `like` ```gizlang function like(value: string, before: bool, after: bool): string ``` The text of `LIKE` for a value that a text contains (BEFORE and AFTER), starts (AFTER) or ends with (BEFORE): `%` and `_` in the value are no wildcards. Effects: fail. ### `withKeys` ```gizlang function withKeys(shape: Model.Shape, sys: System, fields: Model.Fields): Model.Fields ``` FIELDS with a made key for each text key of SHAPE that is missing. Effects: fail, io. ## Methods ### `Table.key` ```gizlang function Table.key(self: Table, v: T): string ``` The key of a record as text (its first key field), or empty. ### `Table.rows` ```gizlang function Table.rows(self: Table): Vec ``` All the records, in the order of the table. ### `Table.where` ```gizlang function Table.where(self: Table, sql: string, fields: Vec, wires: Vec, order: string, limit: i64): Vec ``` The records that a condition selects: SQL over the columns, `$1..` its parameters; FIELDS[i] is the field that WIRES[i] is the value of (empty when WIRES[i] is `true` or `false`, the value of a part of the condition that names no field). ORDER is the order of this read (empty is the order of the table) and LIMIT its most rows (0 is the most a page reads). ### `Table.count` ```gizlang function Table.count(self: Table, sql: string, fields: Vec, wires: Vec): i64 ``` How many records a condition selects, counted by the database. ### `Table.total` ```gizlang function Table.total(self: Table): i64 ``` How many records the table holds that the person may read. ### `Table.grid` ```gizlang function Table.grid(self: Table): Html ``` The rows of the table as a `` around an HTML ``: a column for each field that is not hidden, headed by its label (`data-field` its name), each cell the field as a person reads it (`Model.display`). A row is `data-k` its key, so a page that reads the table with `grid()` is a range that renders again whole on a change. With the giz-grid enhancement (web/components/src/grid.js), RevoGrid Pro shows the same table: sort, filter, select, copy, export. ### `Table.editableGrid` ```gizlang function Table.editableGrid(self: Table, name: string): Html ``` `grid()` whose cells of the fields that are not keys are bound controls of the page (`_f.NAME.field.key`, with `_o.` what the cell showed), as `value={t.field}` in an `each`: a change is one update of that field through the Gate, and a field that another person changed meanwhile is a conflict. Without script the grid is a form of the page; with the enhancement, an edit, a paste or a fill in RevoGrid changes these controls. NAME is the table's name in the page (the GHTML compiler gives it). ### `Table.add` ```gizlang function Table.add(self: Table, v: T): string ``` Add the record V; a text key that is empty is made. ### `Table.create` ```gizlang function Table.create(self: Table, posted: Http.Params, prefix: string): string ``` Add the record that a form posted: the controls PREFIX + field of the posted fields. ### `Table.set` ```gizlang function Table.set(self: Table, v: T): string ``` Replace the record with the key of V by V. ### `Table.remove` ```gizlang function Table.remove(self: Table, v: T): string ``` Delete the record with the key of V. ### `Table.removeWhere` ```gizlang function Table.removeWhere(self: Table, sql: string, fields: Vec, wires: Vec): string ``` Delete every record that a condition selects, as `where` selects them: it stops at the first refusal and gives its reason. A pass reads at most MOST_ROWS records, so it reads again until none is left. ### `Table.apply` ```gizlang function Table.apply(self: Table, name: string, posted: Http.Params): string ``` The changes that the page posted for the table NAME, as `_f.NAME.field.key` = value, in the order posted (the last value of a control counts). `_o.` + the same name is what the control showed: a control that shows what it posts did not change, and a change whose old value is gone is a conflict. ### `Table.watch` ```gizlang function Table.watch(self: Table): Html ``` The element that keeps a page current: the kernel long-polls the changes of the table (a watch on all its rows; the host tells a person only the changes of rows the person may read, Pages `told`) and gets the page again when one comes. Nothing leaves the server but that a change happened; the page reads its rows again under the same grants.