# gizweb:pages

File-system routing: a folder of pages is a site. `giz` writes the module `PAGES/.routes` for it (a program imports `site` from it); this file serves what that module declares. A route file is a .ghtml file in lower case (index.ghtml, [slug].ghtml), a .md file (rendered by Markdown) or a .html file (sent as it is). `[name]` in a path is a parameter, `index` is its folder, `_layout.ghtml` wraps the pages of its folder and below, `404.*` is the not-found page.

```gizlang
import * as Pages from "gizweb:pages";
```

## Types

### `Props`

```gizlang
type Props = { params: Http.Params; request: Http.Request; context: Table.Context; form: Http.Params; locale: Locale; languages: Vec<Locale>; }
```

What a route file reads: `params` and `request` by name, `me` (who asks), the tables through `context`, the fields that the
page posted (`form`: the action, the state and the bound controls, written by the generated code of the page), and `locale`, the
language the page is answered in (web/i18n.giz), by which its text and its numbers and dates show, among the `languages` of the site (its
source language first; a language picker lists them).

- `params`: `gizlang_http.Params`
- `request`: `gizlang_http.Request`
- `context`: `M68.Context`
- `form`: `gizlang_http.Params`
- `locale`: `gizlang_locale.Locale`
- `languages`: `Vec<gizlang_locale.Locale>`

### `Route`

```gizlang
type Route = { pattern: string; kind: string; render: Render; text: string; style: string; }
```

A page: how it renders, and the scoped style of its file. `kind` is "view" (a .ghtml file), "markdown" or "file".

- `pattern`: `string`
- `kind`: `string`
- `render`: `(props: M67.Props, children: gizlang_html.Html) => gizlang_html.Html`
- `text`: `string`
- `style`: `string`

### `Layout`

```gizlang
type Layout = { prefix: string; render: Render; style: string; }
```

A layout wraps the pages whose pattern starts with `prefix`.

- `prefix`: `string`
- `render`: `(props: M67.Props, children: gizlang_html.Html) => gizlang_html.Html`
- `style`: `string`

### `Site`

```gizlang
type Site = { router: Http.Router<i64>; routes: Vec<Route>; layouts: Vec<Layout>; missing: Vec<Route>; speaking: I.Speaking; }
```

A site: its routes, layouts and not-found page, and the languages it speaks (web/i18n.giz).

- `router`: `gizlang_http.Router<i64>`
- `routes`: `Vec<M67.Route>`
- `layouts`: `Vec<M67.Layout>`
- `missing`: `Vec<M67.Route>`
- `speaking`: `_gizlang_lib_web__i18n.Speaking`

### `Host`

```gizlang
type Host = { context: (request: Http.Request) => Table.Context; db: Option<Data.Db>; shapes: Vec<Model.Shape>; }
```

What a site runs on: the tables of a request as the person who asks may use them, and the database whose changes pages follow.

- `context`: `(request: gizlang_http.Request) => M68.Context`
- `db`: `_gizlang_sdk_core.Option<M49.Db>`
- `shapes`: `Vec<M48.Shape>`

## Functions

### `standalone`

```gizlang
function standalone(sys: System): Host
```

A host with no database: a page that declares a table shows an empty one.

### `hosted`

```gizlang
function hosted(sys: System, db: Data.Db, space: string, shapes: Vec<Model.Shape>, actor: (request: Http.Request) => Security.Principal): Host
```

A host over the database DB of the Space SPACE: ACTOR names the person of a request, and the Gate judges every read and write of a page.
SHAPES are the tables of the pages (the ones the Space is provisioned with): the long poll of a page tells a person of the changes of rows that
the person may read, and of no other.

### `view`

```gizlang
function view(pattern: string, render: Render, style: string): Route
```

A page at PATTERN that RENDER draws, with its STYLE.

### `markdown`

```gizlang
function markdown(pattern: string, text: string): Route
```

A page at PATTERN made from the Markdown TEXT.

### `file`

```gizlang
function file(pattern: string, text: string): Route
```

A file at PATTERN that is served as TEXT.

### `layout`

```gizlang
function layout(prefix: string, render: Render, style: string): Layout
```

A layout that RENDER draws around each page under PREFIX, with its STYLE.

### `site`

```gizlang
function site(routes: Vec<Route>, layouts: Vec<Layout>, missing: Vec<Route>): Site
```

The site of ROUTES. MISSING holds the not-found page, if the folder has one. A failing declaration (two files for one address) stops the program at start.

Effects: fail.

### `speaking`

```gizlang
function speaking(site: Site, source: string, tags: Vec<string>): Site
```

SITE in its source language SOURCE and the languages TAGS of its catalogs (`locales/ko.json` beside its pages; the `.routes` module
passes them), each at its own address (`/ko/…`).

Effects: fail.

### `byCookie`

```gizlang
function byCookie(site: Site): Site
```

SITE with its languages chosen by the person and the browser at every address, for an application behind a sign-in.

Effects: fail.

### `handle`

```gizlang
function handle(site: Site, shell: App.Shell, host: Host, request: Http.Request): Http.Response
```

The response for REQUEST: the page of its address, the not-found page for an address without one, and for SUBSCRIPTIONS the long poll of a
table that the page follows (`t` the table, `p` the position, `u` the address of the page): it answers the patches of the parts of the page that read
the table, after a change that the person may see.

Effects: fail, read, write, console, io.

### `shell`

```gizlang
function shell(tailwind: string): App.Shell
```

The page shell of a site of pages: the design system (`uiStyle`) and the kernel. TAILWIND is the style sheet of `Tailwind.stylesheet` (empty for
none), whose `@theme` is `Tokens.css([...uiTheme(), own overlays], true)`: the components then sit in its `components` layer, so a utility
class on an element beats the defaults of a component while the component's own scoped `<style>` still beats the utility.

Effects: fail.

### `handler`

```gizlang
function handler(site: Site, shell: App.Shell, host: Host): (request: Http.Request) => Http.Response
```

The handler of SITE in SHELL on HOST, for the application host: the shell, ETags, compression, security headers and automatic HTTPS
come from `Web.listen`.

    return Web.listen(sys, 8080, Pages.shell(""), Web.serving(), (own: System) => Pages.handler(site(), Pages.shell(""), Pages.standalone(own)));

### `positionOf`

```gizlang
function positionOf(page: string): string
```

The follow id in `data-pos="…"` of the first watch of PAGE.

Effects: fail.

### `poll`

```gizlang
function poll(site: Site, shell: App.Shell, host: Host, headers: Vec<Http.Header>, table: string, id: string, address: string, state: string): string
```

The answer of the long poll of the page ADDRESS (a path, no `&`) for TABLE after the follow ID, with the state STATE (the fields of `#_g`) that the page posts;
HEADERS are the headers of the person (its session). It waits for a change.

Effects: fail, read, write, console, io.

### `nextOf`

```gizlang
function nextOf(told: string): string
```

The follow id that an answer of the poll gives for the next one.

Effects: fail.

### `address`

```gizlang
function address(request: Http.Request, names: Vec<string>, values: Vec<string>, initials: Vec<string>): string
```

The address of the page for the state NAMES = VALUES: its path, and `?name=value` for each state that is not its INITIAL.

Effects: fail.

### `field`

```gizlang
function field(form: Http.Params, name: string): string
```

The last value posted under NAME, or empty.

Effects: fail.

### `text`

```gizlang
function text(form: Http.Params, name: string, initial: string): string
```

The state NAME of a page: what the form posted, else INITIAL. The state is in the page (hidden fields and bound controls), not in the server.

Effects: fail.

### `integer`

```gizlang
function integer(form: Http.Params, name: string, initial: i64): i64
```

The integer state NAME of a page: what the form posted, else INITIAL (also when the posted text is not an integer).

Effects: fail.

### `number`

```gizlang
function number(form: Http.Params, name: string, initial: f64): f64
```

The number state NAME of a page: what the form posted, else INITIAL (also when the posted text is not a number).

Effects: fail.

### `flag`

```gizlang
function flag(form: Http.Params, name: string, initial: bool): bool
```

The flag state NAME of a page: what the form posted, else INITIAL.

Effects: fail.