pico-engine 1.8.0 → 1.9.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +3 -1
- package/dist/RulesetRegistryLoaderFs.js +46 -4
- package/dist/cli.js +3 -1
- package/dist/engineConfig.js +11 -0
- package/dist/index.js +2 -5
- package/dist/logging.js +148 -4
- package/dist/server.js +206 -1
- package/dist/stageKrl.js +26 -0
- package/dist/xmluiRuntime.js +68 -0
- package/krl/io.picolabs.pico-engine-ui.krl +12 -77
- package/krl/io.picolabs.wrangler.krl +21 -4
- package/krl/io.picolabs.xmlui.krl +295 -0
- package/package.json +9 -6
- package/public/.DS_Store +0 -0
- package/public/docs/_sidebar.md +1 -0
- package/public/docs/llms-full.txt +154 -3
- package/public/docs/llms.txt +1 -0
- package/public/docs/pico-engine.md +7 -3
- package/public/docs/pico-views-xmlui.md +5 -0
- package/public/docs/pico-views.md +140 -0
- package/public/docs/rulesets/README.md +1 -0
- package/public/pico-engine-ui.css +1 -1
- package/public/pico-engine-ui.js +27 -25
- package/public/xmlui/0.12.7.js +419 -0
- package/public/xmlui/pico-view-boot.js +153 -0
- package/src/RulesetRegistryLoaderFs.ts +48 -4
- package/src/cli.ts +3 -1
- package/src/engineConfig.ts +18 -0
- package/src/index.ts +4 -6
- package/src/logging.ts +165 -4
- package/src/server.ts +250 -2
- package/src/stageKrl.ts +26 -0
- package/src/xmluiRuntime.ts +66 -0
|
@@ -210,6 +210,7 @@ Example templates: [`config.example.json`](../../config.example.json), [`config.
|
|
|
210
210
|
| `wildcardSkyRequireBearer` | boolean | Require OAuth bearer on `/sky/*` for channels with unrestricted `*.*` allow rules. Default `false` (1.8 opt-in hardening). |
|
|
211
211
|
| `logToStdout` | boolean | Log to stdout instead of a file. Use on Fargate (set `logToStdout: true` in config). |
|
|
212
212
|
| `logFile` | string | Absolute log path when `logToStdout` is false. Values `stdout`, `-`, or `0` force stdout. |
|
|
213
|
+
| `logMirror` | boolean | When **`logToStdout`** is true: also write structured JSON lines to **`$PICO_ENGINE_HOME/pico-engine.log`** for operators. Default **`true`**. Set **`false`** on EFS + Fargate to avoid mirror-file churn (then use CloudWatch from stdout, or set **`logFile`** to a writable path). The Developer UI **Logging** tab reads an in-memory ring and does not need this file. **Env:** `PICO_ENGINE_LOG_MIRROR` (`true`/`1` / `false`/`0`). |
|
|
213
214
|
| `defaultRootPolicyCeiling` | object | Max channel policy for new root picos (`eventPolicy` / `queryPolicy`). See policy example file. |
|
|
214
215
|
| `globalEventDeny` | array | Extra deny rules applied on **every** ECI before channel policy (e.g. block `engine:secret_ping`). |
|
|
215
216
|
| `globalQueryDeny` | array | Same for queries. |
|
|
@@ -223,7 +224,7 @@ Legacy top-level `rpID`, `rpName`, `origin` are still accepted if `webauthn` is
|
|
|
223
224
|
|
|
224
225
|
## Environment variables
|
|
225
226
|
|
|
226
|
-
These
|
|
227
|
+
These env overrides cover config path, data dir, port, public URL, and a few logging knobs; everything else (WebAuthn, signup, localhost bypass, policy ceiling, …) belongs in the **config file**. Maintainer registry of all env keys: engine repo `MEMORY.md` (Engine environment variables).
|
|
227
228
|
|
|
228
229
|
| Variable | Purpose |
|
|
229
230
|
|----------|---------|
|
|
@@ -231,6 +232,9 @@ These four env overrides cover config path, data dir, port, and public URL; ever
|
|
|
231
232
|
| `PICO_ENGINE_HOME` | Data directory |
|
|
232
233
|
| `PORT` | Listen port (if not in file) |
|
|
233
234
|
| `PICO_ENGINE_BASE_URL` | Public URL |
|
|
235
|
+
| `PICO_ENGINE_LOG_FILE` | Log file path, or `stdout` / `-` / `0` / empty for stdout-only |
|
|
236
|
+
| `PICO_ENGINE_LOG_MIRROR` | When stdout-only: `false` / `0` disables writing `$PICO_ENGINE_HOME/pico-engine.log` (config: **`logMirror`**). The Logging tab does not read that file |
|
|
237
|
+
| `PICO_ENGINE_LOG_RING` | How many recent transactions per pico the Logging tab keeps in memory. Default **200**. A restart clears the ring |
|
|
234
238
|
|
|
235
239
|
---
|
|
236
240
|
|
|
@@ -260,7 +264,7 @@ Mesh state lives under `home`:
|
|
|
260
264
|
| `rulesets/` | Compiled ruleset JS |
|
|
261
265
|
|
|
262
266
|
- One writer per data directory (LevelDB).
|
|
263
|
-
- **Fargate:** mount EFS at e.g. `/var/pico-image`, set `home` accordingly, `baseUrl` to public **HTTPS**, `logToStdout: true` in config.
|
|
267
|
+
- **Fargate:** mount EFS at e.g. `/var/pico-image`, set `home` accordingly, `baseUrl` to public **HTTPS**, `logToStdout: true` in config. Set **`logMirror: false`** if you do not want the engine writing `pico-engine.log` on EFS (stdout → CloudWatch only).
|
|
264
268
|
- Set `allowLocalhostChannelBypass` to **false** on public deployments.
|
|
265
269
|
|
|
266
270
|
Detailed checklists: package **README** § Containers / Fargate.
|
|
@@ -363,11 +367,157 @@ Logs: default `$home/pico-engine.log`, or stdout when configured. Engine logs **
|
|
|
363
367
|
|
|
364
368
|
## Related docs
|
|
365
369
|
|
|
366
|
-
- [Pico overview / philosophy](pico-overview.md) · [Bundled rulesets (wrangler, PDS, …)](rulesets/README.md) · [Manifold mesh framework](https://github.com/Picolab/manifold-api/blob/main/docs/llms.txt) · [KRL manual](krl/README.md)
|
|
370
|
+
- [Pico overview / philosophy](pico-overview.md) · [Pico views](pico-views.md) · [Bundled rulesets (wrangler, PDS, …)](rulesets/README.md) · [Manifold mesh framework](https://github.com/Picolab/manifold-api/blob/main/docs/llms.txt) · [KRL manual](krl/README.md)
|
|
367
371
|
- Package [README](../../README.md) — OAuth, authentication, full container checklist
|
|
368
372
|
- Release [1.8.0 notes](https://github.com/Picolab/pico-engine/blob/main/docs/release/1.8.0.md) — what changed in this line
|
|
369
373
|
|
|
370
374
|
|
|
375
|
+
---
|
|
376
|
+
|
|
377
|
+
# Pico views
|
|
378
|
+
|
|
379
|
+
# Pico views
|
|
380
|
+
|
|
381
|
+
A **view** is a shared function that returns [XMLUI](https://xmlui.org) markup. Install the ruleset, open it on a channel that may call that function, and the engine serves the page.
|
|
382
|
+
|
|
383
|
+
The engine ships the XMLUI runtime (`/xmlui/0.12.7.js`) and the optional ruleset `io.picolabs.xmlui`. That ruleset builds the app shell, navigation, and the markup helpers. It is not installed on every pico. Install it from the engine:
|
|
384
|
+
|
|
385
|
+
`/krl/io.picolabs.xmlui.krl`
|
|
386
|
+
|
|
387
|
+
Channel policy applies to views the same way it applies to any other query. A channel that cannot call the function does not get that page. Live data still comes from `/sky/query` and `/sky/event` on that same channel.
|
|
388
|
+
|
|
389
|
+
Examples live in `demos/xmlui/` in the pico-engine repository. The design record is `docs/design/pico-views-xmlui.md`.
|
|
390
|
+
|
|
391
|
+
## Write a view
|
|
392
|
+
|
|
393
|
+
Tag the function with `@view` and return one `<Component>`:
|
|
394
|
+
|
|
395
|
+
```krl
|
|
396
|
+
ruleset com.example.hello {
|
|
397
|
+
meta {
|
|
398
|
+
name "Hello"
|
|
399
|
+
shares hello
|
|
400
|
+
}
|
|
401
|
+
global {
|
|
402
|
+
/**
|
|
403
|
+
* A first view
|
|
404
|
+
* @view "Hello"
|
|
405
|
+
*/
|
|
406
|
+
hello = function() {
|
|
407
|
+
<<<Component name="Hello">
|
|
408
|
+
<H1>Hello</H1>
|
|
409
|
+
<Text>This view is a shared function in #{meta:rid}.</Text>
|
|
410
|
+
</Component>
|
|
411
|
+
>>
|
|
412
|
+
}
|
|
413
|
+
}
|
|
414
|
+
}
|
|
415
|
+
```
|
|
416
|
+
|
|
417
|
+
`@view "Title"` sets the navigation label. The shell turns the function name into the component tag by capitalizing the first letter (`hello` → `<Hello />`). The `<Component name>` in the markup has to be that same name.
|
|
418
|
+
|
|
419
|
+
Give the function a path when you want a specific URL:
|
|
420
|
+
|
|
421
|
+
```krl
|
|
422
|
+
@view "Settings" /settings
|
|
423
|
+
```
|
|
424
|
+
|
|
425
|
+
With one view and no path, the page is `/`. With several views and no path, each page is `/` plus the function name. A path that contains `:` is a detail page (`@view "Contact" /contact/:id`). It is left out of the navigation. The component reads `{$routeParams.id}`. Other views link to it with `<Link to="/contact/{$item.id}">`.
|
|
426
|
+
|
|
427
|
+
Do not name a view after a built-in XMLUI tag (`List`, `Table`, `Form`, `Text`, …). A function named `list` becomes `<List />`, which is the framework list, not your page. Name it `contactsPage` and, if you want the URL to be `/list`, set the path.
|
|
428
|
+
|
|
429
|
+
`#{}` runs in KRL while the page is generated. Use it for constants: `meta:rid`, labels, and the helpers below. Do not put entity variables or query results in `#{}`. Those values belong in a `DataSource`, which XMLUI renders as text. `krl check` warns when a `@view` function interpolates `ent:` and when the heredoc is not well-formed XML.
|
|
430
|
+
|
|
431
|
+
## Open it
|
|
432
|
+
|
|
433
|
+
| URL | What it serves |
|
|
434
|
+
|-----|----------------|
|
|
435
|
+
| `/ui/{eci}` | A list of rulesets on this channel that have a view the channel may call |
|
|
436
|
+
| `/ui/{eci}/{rid}/` | That ruleset's app. Routes are hash URLs under this path |
|
|
437
|
+
|
|
438
|
+
The shell (`index.html`), `Main.xmlui`, and `config.json` come from `io.picolabs.xmlui:file`. `components/<Name>.xmlui` is the view function itself, queried on the channel in the URL.
|
|
439
|
+
|
|
440
|
+
In the developer UI, a ruleset with at least one `@view` function has a **View** button on the Rulesets tab. Pick the channel, then open the app.
|
|
441
|
+
|
|
442
|
+
The channel must allow:
|
|
443
|
+
|
|
444
|
+
- `io.picolabs.xmlui` / `file`, or the shell does not load
|
|
445
|
+
- the view function, or that component is not found
|
|
446
|
+
- every query and event the page calls
|
|
447
|
+
|
|
448
|
+
A policy denial on these routes is HTTP 403. Anything else the route cannot serve is HTTP 404.
|
|
449
|
+
|
|
450
|
+
These `/ui/` files are the ruleset's markup plus the ECI and RID already in the URL. They are served without a bearer token. Pico data is not in them. When the engine requires a bearer on `/sky/*`, the shell signs in and sends that token as `appGlobals.auth` on each `DataSource` and `APICall`.
|
|
451
|
+
|
|
452
|
+
## Read and write
|
|
453
|
+
|
|
454
|
+
`use module io.picolabs.xmlui alias ui`. The helpers return markup, so they go in the heredoc with `#{}`.
|
|
455
|
+
|
|
456
|
+
| Call | Result |
|
|
457
|
+
|------|--------|
|
|
458
|
+
| `ui:query(id, name, opts)` | A `DataSource`. `opts.rid` defaults to this ruleset. `opts.args` is a map of query parameters (values may be XMLUI bindings such as `"{$routeParams.id}"`). `opts.select` sets `resultSelector`. |
|
|
459
|
+
| `ui:event(id, domain, type, opts)` | An `APICall` that posts the form body. `opts.refresh` is a list of `DataSource` ids to refetch. `opts.confirm` sets a confirmation message. |
|
|
460
|
+
| `ui:query_url(name, rid, eci)` | `/sky/query/…` for this channel, ruleset, and query. |
|
|
461
|
+
| `ui:event_url(domain, type, eci)` | `/sky/event/{eci}/xmlui/{domain}/{type}`. |
|
|
462
|
+
| `ui:app_url(tags, app_rid)` | `/ui/{eci}/{rid}/` for the newest channel with those tags, or `null`. |
|
|
463
|
+
| `ui:escape(s)` | Escape `&`, `<`, `>`, and `"` for text placed in markup. |
|
|
464
|
+
|
|
465
|
+
A guestbook view:
|
|
466
|
+
|
|
467
|
+
```krl
|
|
468
|
+
meta {
|
|
469
|
+
name "Guestbook"
|
|
470
|
+
use module io.picolabs.xmlui alias ui
|
|
471
|
+
shares entries, book
|
|
472
|
+
}
|
|
473
|
+
global {
|
|
474
|
+
/** Guestbook entries, newest first. @returns Array */
|
|
475
|
+
entries = function() {
|
|
476
|
+
ent:entries.defaultsTo([]).reverse()
|
|
477
|
+
}
|
|
478
|
+
|
|
479
|
+
/**
|
|
480
|
+
* Sign and read the guestbook
|
|
481
|
+
* @view "Guestbook"
|
|
482
|
+
*/
|
|
483
|
+
book = function() {
|
|
484
|
+
<<<Component name="Book">
|
|
485
|
+
#{ui:query("entries", "entries")}
|
|
486
|
+
#{ui:event("sign", "guestbook", "signed", {"refresh": ["entries"]})}
|
|
487
|
+
<Form onSubmit="(toSave) => sign.execute(toSave)">
|
|
488
|
+
<FormItem bindTo="name" label="Name" />
|
|
489
|
+
<FormItem bindTo="message" label="Message" type="textarea" />
|
|
490
|
+
</Form>
|
|
491
|
+
<Table data="{entries}">
|
|
492
|
+
<Column bindTo="name" header="Name" />
|
|
493
|
+
<Column bindTo="message" header="Message" />
|
|
494
|
+
</Table>
|
|
495
|
+
</Component>
|
|
496
|
+
>>
|
|
497
|
+
}
|
|
498
|
+
}
|
|
499
|
+
```
|
|
500
|
+
|
|
501
|
+
The matching rule selects `guestbook signed`. After it fires, `entries.refetch()` reloads the table. The full ruleset is `demos/xmlui/com.example.guestbook.krl`.
|
|
502
|
+
|
|
503
|
+
## App channel
|
|
504
|
+
|
|
505
|
+
`ui:create_app_channel(tags, domains, queries, app_rid)` creates a channel whose events are limited to `domains` (each name is `*`) and whose queries are `queries` on `app_rid`. When `queries` is `null`, every shared function of `app_rid` is allowed. The query policy always includes `io.picolabs.xmlui` / `file`.
|
|
506
|
+
|
|
507
|
+
```krl
|
|
508
|
+
rule create_app_channel {
|
|
509
|
+
select when wrangler ruleset_installed where event:attr("rids") >< meta:rid
|
|
510
|
+
ui:create_app_channel(["guestbook", "app"], ["guestbook"], null, meta:rid)
|
|
511
|
+
}
|
|
512
|
+
```
|
|
513
|
+
|
|
514
|
+
`ui:rotate_app_channel(tags)` creates a new channel with the same tags and policy as the newest channel that already has those tags.
|
|
515
|
+
|
|
516
|
+
## What a view does not do
|
|
517
|
+
|
|
518
|
+
A view does not subscribe to changes made somewhere else. It loads when the page opens and refetches the `DataSource`s named in `opts.refresh` after its own event. Another pico's data is reached by a query on this pico that calls out, not by pointing a `DataSource` at the other pico. See `demos/xmlui/com.example.temperature_sensors_view.krl`.
|
|
519
|
+
|
|
520
|
+
|
|
371
521
|
---
|
|
372
522
|
|
|
373
523
|
# Bundled rulesets
|
|
@@ -395,6 +545,7 @@ Shipped under `/krl/` on your engine; install from the Rulesets tab or `wrangler
|
|
|
395
545
|
|---------|-----|--------|
|
|
396
546
|
| **io.picolabs.oauth** | [oauth](io.picolabs.oauth.md) | **Root pico only** — optional mesh-wide OAuth on `/sky/*` |
|
|
397
547
|
| **io.picolabs.portable_subtree** | [portable_subtree](io.picolabs.portable_subtree.md) | Portable export/import of subtrees (identity-aware move) |
|
|
548
|
+
| **io.picolabs.xmlui** | [Pico views](../pico-views.md) | Optional. A `@view` function is a page at `/ui/{eci}/{rid}/` |
|
|
398
549
|
|
|
399
550
|
Application rulesets (Manifold, your apps) are not bundled; install their KRL URLs like any other ruleset.
|
|
400
551
|
|
package/public/docs/llms.txt
CHANGED
|
@@ -12,6 +12,7 @@ Machine-readable index for agents working with picos and KRL.
|
|
|
12
12
|
|
|
13
13
|
- Pico overview: pico-overview.md
|
|
14
14
|
- Pico engine operator guide: pico-engine.md
|
|
15
|
+
- Pico views: pico-views.md
|
|
15
16
|
- Bundled rulesets: rulesets/README.md
|
|
16
17
|
- KRL manual: krl/README.md
|
|
17
18
|
- Contributing: contributing.md
|
|
@@ -80,6 +80,7 @@ Example templates: [`config.example.json`](../../config.example.json), [`config.
|
|
|
80
80
|
| `wildcardSkyRequireBearer` | boolean | Require OAuth bearer on `/sky/*` for channels with unrestricted `*.*` allow rules. Default `false` (1.8 opt-in hardening). |
|
|
81
81
|
| `logToStdout` | boolean | Log to stdout instead of a file. Use on Fargate (set `logToStdout: true` in config). |
|
|
82
82
|
| `logFile` | string | Absolute log path when `logToStdout` is false. Values `stdout`, `-`, or `0` force stdout. |
|
|
83
|
+
| `logMirror` | boolean | When **`logToStdout`** is true: also write structured JSON lines to **`$PICO_ENGINE_HOME/pico-engine.log`** for operators. Default **`true`**. Set **`false`** on EFS + Fargate to avoid mirror-file churn (then use CloudWatch from stdout, or set **`logFile`** to a writable path). The Developer UI **Logging** tab reads an in-memory ring and does not need this file. **Env:** `PICO_ENGINE_LOG_MIRROR` (`true`/`1` / `false`/`0`). |
|
|
83
84
|
| `defaultRootPolicyCeiling` | object | Max channel policy for new root picos (`eventPolicy` / `queryPolicy`). See policy example file. |
|
|
84
85
|
| `globalEventDeny` | array | Extra deny rules applied on **every** ECI before channel policy (e.g. block `engine:secret_ping`). |
|
|
85
86
|
| `globalQueryDeny` | array | Same for queries. |
|
|
@@ -93,7 +94,7 @@ Legacy top-level `rpID`, `rpName`, `origin` are still accepted if `webauthn` is
|
|
|
93
94
|
|
|
94
95
|
## Environment variables
|
|
95
96
|
|
|
96
|
-
These
|
|
97
|
+
These env overrides cover config path, data dir, port, public URL, and a few logging knobs; everything else (WebAuthn, signup, localhost bypass, policy ceiling, …) belongs in the **config file**. Maintainer registry of all env keys: engine repo `MEMORY.md` (Engine environment variables).
|
|
97
98
|
|
|
98
99
|
| Variable | Purpose |
|
|
99
100
|
|----------|---------|
|
|
@@ -101,6 +102,9 @@ These four env overrides cover config path, data dir, port, and public URL; ever
|
|
|
101
102
|
| `PICO_ENGINE_HOME` | Data directory |
|
|
102
103
|
| `PORT` | Listen port (if not in file) |
|
|
103
104
|
| `PICO_ENGINE_BASE_URL` | Public URL |
|
|
105
|
+
| `PICO_ENGINE_LOG_FILE` | Log file path, or `stdout` / `-` / `0` / empty for stdout-only |
|
|
106
|
+
| `PICO_ENGINE_LOG_MIRROR` | When stdout-only: `false` / `0` disables writing `$PICO_ENGINE_HOME/pico-engine.log` (config: **`logMirror`**). The Logging tab does not read that file |
|
|
107
|
+
| `PICO_ENGINE_LOG_RING` | How many recent transactions per pico the Logging tab keeps in memory. Default **200**. A restart clears the ring |
|
|
104
108
|
|
|
105
109
|
---
|
|
106
110
|
|
|
@@ -130,7 +134,7 @@ Mesh state lives under `home`:
|
|
|
130
134
|
| `rulesets/` | Compiled ruleset JS |
|
|
131
135
|
|
|
132
136
|
- One writer per data directory (LevelDB).
|
|
133
|
-
- **Fargate:** mount EFS at e.g. `/var/pico-image`, set `home` accordingly, `baseUrl` to public **HTTPS**, `logToStdout: true` in config.
|
|
137
|
+
- **Fargate:** mount EFS at e.g. `/var/pico-image`, set `home` accordingly, `baseUrl` to public **HTTPS**, `logToStdout: true` in config. Set **`logMirror: false`** if you do not want the engine writing `pico-engine.log` on EFS (stdout → CloudWatch only).
|
|
134
138
|
- Set `allowLocalhostChannelBypass` to **false** on public deployments.
|
|
135
139
|
|
|
136
140
|
Detailed checklists: package **README** § Containers / Fargate.
|
|
@@ -233,6 +237,6 @@ Logs: default `$home/pico-engine.log`, or stdout when configured. Engine logs **
|
|
|
233
237
|
|
|
234
238
|
## Related docs
|
|
235
239
|
|
|
236
|
-
- [Pico overview / philosophy](pico-overview.md) · [Bundled rulesets (wrangler, PDS, …)](rulesets/README.md) · [Manifold mesh framework](https://github.com/Picolab/manifold-api/blob/main/docs/llms.txt) · [KRL manual](krl/README.md)
|
|
240
|
+
- [Pico overview / philosophy](pico-overview.md) · [Pico views](pico-views.md) · [Bundled rulesets (wrangler, PDS, …)](rulesets/README.md) · [Manifold mesh framework](https://github.com/Picolab/manifold-api/blob/main/docs/llms.txt) · [KRL manual](krl/README.md)
|
|
237
241
|
- Package [README](../../README.md) — OAuth, authentication, full container checklist
|
|
238
242
|
- Release [1.8.0 notes](https://github.com/Picolab/pico-engine/blob/main/docs/release/1.8.0.md) — what changed in this line
|
|
@@ -0,0 +1,140 @@
|
|
|
1
|
+
# Pico views
|
|
2
|
+
|
|
3
|
+
A **view** is a shared function that returns [XMLUI](https://xmlui.org) markup. Install the ruleset, open it on a channel that may call that function, and the engine serves the page.
|
|
4
|
+
|
|
5
|
+
The engine ships the XMLUI runtime (`/xmlui/0.12.7.js`) and the optional ruleset `io.picolabs.xmlui`. That ruleset builds the app shell, navigation, and the markup helpers. It is not installed on every pico. Install it from the engine:
|
|
6
|
+
|
|
7
|
+
`/krl/io.picolabs.xmlui.krl`
|
|
8
|
+
|
|
9
|
+
Channel policy applies to views the same way it applies to any other query. A channel that cannot call the function does not get that page. Live data still comes from `/sky/query` and `/sky/event` on that same channel.
|
|
10
|
+
|
|
11
|
+
Examples live in `demos/xmlui/` in the pico-engine repository. The design record is `docs/design/pico-views-xmlui.md`.
|
|
12
|
+
|
|
13
|
+
## Write a view
|
|
14
|
+
|
|
15
|
+
Tag the function with `@view` and return one `<Component>`:
|
|
16
|
+
|
|
17
|
+
```krl
|
|
18
|
+
ruleset com.example.hello {
|
|
19
|
+
meta {
|
|
20
|
+
name "Hello"
|
|
21
|
+
shares hello
|
|
22
|
+
}
|
|
23
|
+
global {
|
|
24
|
+
/**
|
|
25
|
+
* A first view
|
|
26
|
+
* @view "Hello"
|
|
27
|
+
*/
|
|
28
|
+
hello = function() {
|
|
29
|
+
<<<Component name="Hello">
|
|
30
|
+
<H1>Hello</H1>
|
|
31
|
+
<Text>This view is a shared function in #{meta:rid}.</Text>
|
|
32
|
+
</Component>
|
|
33
|
+
>>
|
|
34
|
+
}
|
|
35
|
+
}
|
|
36
|
+
}
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
`@view "Title"` sets the navigation label. The shell turns the function name into the component tag by capitalizing the first letter (`hello` → `<Hello />`). The `<Component name>` in the markup has to be that same name.
|
|
40
|
+
|
|
41
|
+
Give the function a path when you want a specific URL:
|
|
42
|
+
|
|
43
|
+
```krl
|
|
44
|
+
@view "Settings" /settings
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
With one view and no path, the page is `/`. With several views and no path, each page is `/` plus the function name. A path that contains `:` is a detail page (`@view "Contact" /contact/:id`). It is left out of the navigation. The component reads `{$routeParams.id}`. Other views link to it with `<Link to="/contact/{$item.id}">`.
|
|
48
|
+
|
|
49
|
+
Do not name a view after a built-in XMLUI tag (`List`, `Table`, `Form`, `Text`, …). A function named `list` becomes `<List />`, which is the framework list, not your page. Name it `contactsPage` and, if you want the URL to be `/list`, set the path.
|
|
50
|
+
|
|
51
|
+
`#{}` runs in KRL while the page is generated. Use it for constants: `meta:rid`, labels, and the helpers below. Do not put entity variables or query results in `#{}`. Those values belong in a `DataSource`, which XMLUI renders as text. `krl check` warns when a `@view` function interpolates `ent:` and when the heredoc is not well-formed XML.
|
|
52
|
+
|
|
53
|
+
## Open it
|
|
54
|
+
|
|
55
|
+
| URL | What it serves |
|
|
56
|
+
|-----|----------------|
|
|
57
|
+
| `/ui/{eci}` | A list of rulesets on this channel that have a view the channel may call |
|
|
58
|
+
| `/ui/{eci}/{rid}/` | That ruleset's app. Routes are hash URLs under this path |
|
|
59
|
+
|
|
60
|
+
The shell (`index.html`), `Main.xmlui`, and `config.json` come from `io.picolabs.xmlui:file`. `components/<Name>.xmlui` is the view function itself, queried on the channel in the URL.
|
|
61
|
+
|
|
62
|
+
In the developer UI, a ruleset with at least one `@view` function has a **View** button on the Rulesets tab. Pick the channel, then open the app.
|
|
63
|
+
|
|
64
|
+
The channel must allow:
|
|
65
|
+
|
|
66
|
+
- `io.picolabs.xmlui` / `file`, or the shell does not load
|
|
67
|
+
- the view function, or that component is not found
|
|
68
|
+
- every query and event the page calls
|
|
69
|
+
|
|
70
|
+
A policy denial on these routes is HTTP 403. Anything else the route cannot serve is HTTP 404.
|
|
71
|
+
|
|
72
|
+
These `/ui/` files are the ruleset's markup plus the ECI and RID already in the URL. They are served without a bearer token. Pico data is not in them. When the engine requires a bearer on `/sky/*`, the shell signs in and sends that token as `appGlobals.auth` on each `DataSource` and `APICall`.
|
|
73
|
+
|
|
74
|
+
## Read and write
|
|
75
|
+
|
|
76
|
+
`use module io.picolabs.xmlui alias ui`. The helpers return markup, so they go in the heredoc with `#{}`.
|
|
77
|
+
|
|
78
|
+
| Call | Result |
|
|
79
|
+
|------|--------|
|
|
80
|
+
| `ui:query(id, name, opts)` | A `DataSource`. `opts.rid` defaults to this ruleset. `opts.args` is a map of query parameters (values may be XMLUI bindings such as `"{$routeParams.id}"`). `opts.select` sets `resultSelector`. |
|
|
81
|
+
| `ui:event(id, domain, type, opts)` | An `APICall` that posts the form body. `opts.refresh` is a list of `DataSource` ids to refetch. `opts.confirm` sets a confirmation message. |
|
|
82
|
+
| `ui:query_url(name, rid, eci)` | `/sky/query/…` for this channel, ruleset, and query. |
|
|
83
|
+
| `ui:event_url(domain, type, eci)` | `/sky/event/{eci}/xmlui/{domain}/{type}`. |
|
|
84
|
+
| `ui:app_url(tags, app_rid)` | `/ui/{eci}/{rid}/` for the newest channel with those tags, or `null`. |
|
|
85
|
+
| `ui:escape(s)` | Escape `&`, `<`, `>`, and `"` for text placed in markup. |
|
|
86
|
+
|
|
87
|
+
A guestbook view:
|
|
88
|
+
|
|
89
|
+
```krl
|
|
90
|
+
meta {
|
|
91
|
+
name "Guestbook"
|
|
92
|
+
use module io.picolabs.xmlui alias ui
|
|
93
|
+
shares entries, book
|
|
94
|
+
}
|
|
95
|
+
global {
|
|
96
|
+
/** Guestbook entries, newest first. @returns Array */
|
|
97
|
+
entries = function() {
|
|
98
|
+
ent:entries.defaultsTo([]).reverse()
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
/**
|
|
102
|
+
* Sign and read the guestbook
|
|
103
|
+
* @view "Guestbook"
|
|
104
|
+
*/
|
|
105
|
+
book = function() {
|
|
106
|
+
<<<Component name="Book">
|
|
107
|
+
#{ui:query("entries", "entries")}
|
|
108
|
+
#{ui:event("sign", "guestbook", "signed", {"refresh": ["entries"]})}
|
|
109
|
+
<Form onSubmit="(toSave) => sign.execute(toSave)">
|
|
110
|
+
<FormItem bindTo="name" label="Name" />
|
|
111
|
+
<FormItem bindTo="message" label="Message" type="textarea" />
|
|
112
|
+
</Form>
|
|
113
|
+
<Table data="{entries}">
|
|
114
|
+
<Column bindTo="name" header="Name" />
|
|
115
|
+
<Column bindTo="message" header="Message" />
|
|
116
|
+
</Table>
|
|
117
|
+
</Component>
|
|
118
|
+
>>
|
|
119
|
+
}
|
|
120
|
+
}
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
The matching rule selects `guestbook signed`. After it fires, `entries.refetch()` reloads the table. The full ruleset is `demos/xmlui/com.example.guestbook.krl`.
|
|
124
|
+
|
|
125
|
+
## App channel
|
|
126
|
+
|
|
127
|
+
`ui:create_app_channel(tags, domains, queries, app_rid)` creates a channel whose events are limited to `domains` (each name is `*`) and whose queries are `queries` on `app_rid`. When `queries` is `null`, every shared function of `app_rid` is allowed. The query policy always includes `io.picolabs.xmlui` / `file`.
|
|
128
|
+
|
|
129
|
+
```krl
|
|
130
|
+
rule create_app_channel {
|
|
131
|
+
select when wrangler ruleset_installed where event:attr("rids") >< meta:rid
|
|
132
|
+
ui:create_app_channel(["guestbook", "app"], ["guestbook"], null, meta:rid)
|
|
133
|
+
}
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
`ui:rotate_app_channel(tags)` creates a new channel with the same tags and policy as the newest channel that already has those tags.
|
|
137
|
+
|
|
138
|
+
## What a view does not do
|
|
139
|
+
|
|
140
|
+
A view does not subscribe to changes made somewhere else. It loads when the page opens and refetches the `DataSource`s named in `opts.refresh` after its own event. Another pico's data is reached by a query on this pico that calls out, not by pointing a `DataSource` at the other pico. See `demos/xmlui/com.example.temperature_sensors_view.krl`.
|
|
@@ -21,5 +21,6 @@ Shipped under `/krl/` on your engine; install from the Rulesets tab or `wrangler
|
|
|
21
21
|
|---------|-----|--------|
|
|
22
22
|
| **io.picolabs.oauth** | [oauth](io.picolabs.oauth.md) | **Root pico only** — optional mesh-wide OAuth on `/sky/*` |
|
|
23
23
|
| **io.picolabs.portable_subtree** | [portable_subtree](io.picolabs.portable_subtree.md) | Portable export/import of subtrees (identity-aware move) |
|
|
24
|
+
| **io.picolabs.xmlui** | [Pico views](../pico-views.md) | Optional. A `@view` function is a page at `/ui/{eci}/{rid}/` |
|
|
24
25
|
|
|
25
26
|
Application rulesets (Manifold, your apps) are not bundled; install their KRL URLs like any other ruleset.
|