@lotics/cli 0.318.50 → 0.320.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/AGENTS.md +5 -6
- package/README.md +1 -4
- package/dist/src/cli.js +204 -95
- package/docs/agent_surface.md +10 -5
- package/docs/app_architecture.md +20 -12
- package/docs/{first_build.md → build.md} +12 -17
- package/docs/data_model.md +17 -7
- package/docs/design.md +51 -22
- package/docs/document_templates.md +37 -9
- package/docs/examples.md +73 -42
- package/docs/field_values.md +2 -0
- package/docs/getting_started.md +6 -4
- package/docs/workflows.md +74 -12
- package/docs/working_in_a_workspace.md +3 -3
- package/package.json +1 -1
- package/docs/building_an_app.md +0 -252
package/docs/agent_surface.md
CHANGED
|
@@ -6,12 +6,12 @@ reach them, over MCP and as `lotics run <tool>`:
|
|
|
6
6
|
|
|
7
7
|
| Tool | Answers |
|
|
8
8
|
|---|---|
|
|
9
|
-
| `get_app` | The app's `catalog`: its queries and workflows by alias, each one's description, its params or inputs with their types and legal values, and under a query's line its output columns (`returns`) — beside what each table they name holds, in its owner's words |
|
|
9
|
+
| `get_app` | The app's `catalog`: its queries and workflows by alias, each one's description, its params or inputs with their types and legal values, and under a query's line its output columns (`returns`) — beside what each table they name holds, in its owner's words — and, for the app's author, `notes`: what its stored tree compiles with, each at its address under its rule id (`list.layout-call`, a root List drawing a table over rows a board layout would draw, with the layouts to state; `list.filter-unshown`, a filter no row draws, which the app leaves out) |
|
|
10
10
|
| `run_app_query` | The rows, a count or the groups of one query — or of several in one call |
|
|
11
11
|
| `run_app_workflow` | One write — or several in order — or a dry run of it that writes nothing |
|
|
12
12
|
|
|
13
13
|
An app generates this surface from its tree; Query and Workflow nodes declare what the screen never
|
|
14
|
-
asks (
|
|
14
|
+
asks (`agent_surface/declaring-more`). Every root List of an app (a change may add one at any time) is part of it: each List's list, its rows by id, its page's
|
|
15
15
|
Lists and its Acts are queries and workflows of the same app, named by that List's table — `get_app` lists them in the
|
|
16
16
|
one roster, and nothing of a root List is another app's. Every caller the app is shared with is answered them, its rows narrowed by the app's row rules. A custom-code app's surface is the queries and workflows bound on it
|
|
17
17
|
(`app_bindings`).
|
|
@@ -93,6 +93,7 @@ the screen already holds.
|
|
|
93
93
|
|---|---|---|---|
|
|
94
94
|
| `create_<entity>` | Opens one row of <entity>. | every field the add asks, and the link it files the row under | an entity the app adds rows of |
|
|
95
95
|
| `update_<entity>` | Changes one row of <entity>; every input but the row is optional, and one left out is left as it is. | `record_id`, and each field a person edits — a files field or a link to several rows as `<field>_added` / `<field>_removed` | an entity the app edits |
|
|
96
|
+
| `move_<list>` | Gives rows of <entity> to a <lane> together: every row is judged before any is written, so a refusal leaves them all as they were. `lane` left out leaves the <lane> as it is, `lane` empty clears it; `day` dates only the rows holding none; `order` places each by its number. | `record_ids`, `lane` (left out, the lane stays; empty, none), `day` for the rows holding none, and `order`: each row's id and number | a lanes board of days with no hour whose app writes its lane |
|
|
96
97
|
| `remove_<entity>` | Removes one row of <entity>. | `record_id` | an entity the app removes rows of |
|
|
97
98
|
| `restore_<entity>` | Brings back one deleted row of <entity>. | `record_id` | an entity the app removes rows of |
|
|
98
99
|
| `act_<act>` | <label> — on one row of <entity>, refused where its conditions do not hold. | `record_id` — `record_ids` on an act over several rows — and what the act asks | each Act that names no workflow of its own |
|
|
@@ -100,7 +101,7 @@ the screen already holds.
|
|
|
100
101
|
|
|
101
102
|
<!-- generated:end workflows -->
|
|
102
103
|
|
|
103
|
-
A Workflow node is called by its `key
|
|
104
|
+
A Workflow node is called by its `key`, and every Act by `act_<key>`; an Act that names its own `workflow` is also called by that workflow's alias.
|
|
104
105
|
|
|
105
106
|
## Calling a query
|
|
106
107
|
|
|
@@ -180,8 +181,8 @@ run_app_workflow {"app_id":"app_…","alias":"act_hand_over","inputs":{"record_i
|
|
|
180
181
|
| Argument | Does |
|
|
181
182
|
|---|---|
|
|
182
183
|
| `inputs` | The workflow's declared inputs. An update takes the record and only the fields that change |
|
|
183
|
-
| `dry_run` | `true`: the run is made and taken back, so nothing is kept, and the answer is what the run would return, with the calls it would make — or `status: "not_previewed"` where the workflow cannot be dry-run (
|
|
184
|
-
| `as_member` |
|
|
184
|
+
| `dry_run` | `true`: the run is made and taken back, so nothing is kept, and the answer is what the run would return, with the calls it would make — or `status: "not_previewed"` where the workflow cannot be dry-run (`agent_surface/a-dry-run`) |
|
|
185
|
+
| `as_member` | For a workspace admin: the run is a dry run, judged as that member would press it — their stage owners, row rules and app access — and writes nothing. Anyone else is refused; a record tool takes it the same way, and so do `query_records` and `run_app_query`, which answer what that member would read, and `screenshot_app`, which draws the app as that member sees it |
|
|
185
186
|
| `runs` | Several runs in one call, 50 at most, in order, each its own write, answered under `runs`. The first one refused, failed or not dry-run ends the call. An input `{"from_run": 0, "path": "data.record_id"}` is an earlier run's answer at that path. A run states its own `dry_run`, or takes the call's. Dry runs one after another share their rows, taken back together, so a run reads what the one before it made; a run reads a dry run's answer only from a run dry-run in that stretch |
|
|
186
187
|
|
|
187
188
|
```
|
|
@@ -242,6 +243,10 @@ checked before any is written, and all are written in one transaction or none; t
|
|
|
242
243
|
that moved is recorded by the same run. `applied.previous` holds, for each record in `updated`, what the fields the call wrote held before (null for an empty one): `update_records` with it as `set` puts them back, and `delete_records` of a `created` record takes that row away. An act over every
|
|
243
244
|
row in view takes no `record_ids`. A `file` input takes the id of a file uploaded to the workspace.
|
|
244
245
|
|
|
246
|
+
An Act that `makes` a cadence's rows proposes the same way with no body: `creates` are the child rows still owed, each
|
|
247
|
+
`key` `<parent id>|<day>`, a row its write would refuse unticked with the refusal as its `note`, and `unplaced` says what
|
|
248
|
+
stays off the pattern and how many closed days were skipped.
|
|
249
|
+
|
|
245
250
|
## A refusal
|
|
246
251
|
|
|
247
252
|
A workflow re-checks on the server what the screen shows of its own act or save: what an act requires, a
|
package/docs/app_architecture.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
# App architecture —
|
|
1
|
+
# App architecture — which apps, and who gets each
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**Which apps.** One app per main entity, a thing the owner's words give its own list. A row that makes sense only under one parent (an employee's contracts, an order's lines) is a child List on the parent's page, never another app or a Tab. A second root List is rare: one job working two unrelated entities side by side. A related row's value on the list is a lookup column; work over many rows (a month's payroll) an Act on the list's rows. A person's part of the work doesn't make an app; a different job may.
|
|
4
4
|
|
|
5
5
|
One bakery's wholesale arm, five people, seven apps:
|
|
6
6
|
|
|
@@ -28,14 +28,22 @@ record, one page. The owner reads the figures each register leads with. Each app
|
|
|
28
28
|
}
|
|
29
29
|
```
|
|
30
30
|
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
31
|
+
How each tree is composed is `design`.
|
|
32
|
+
|
|
33
|
+
## Who gets each
|
|
34
|
+
|
|
35
|
+
Who does which job is asked in `build`'s one message before the first write. An app stays with admins until the answer comes, and sharing waits on it. `set_access` then gives each app to everyone who works its rows (ids from `get_workspace`); none loses access. They need no
|
|
36
|
+
table access: an app runs as its owner. With no `rows` on the App they read every row; where people differ, `rows`
|
|
37
|
+
states one rule per table (`reference/read-scope`):
|
|
38
|
+
|
|
39
|
+
| The business says | The app states |
|
|
40
|
+
|---|---|
|
|
41
|
+
| Everyone sees every order | nothing |
|
|
42
|
+
| Each rep sees only their own deals | `"rows": { "deal": { "any": [{ "field": "rep", "is": "self" }] } }` |
|
|
43
|
+
| Reps see their own deals; managers see all | `"rows": { "deal": { "any": [{ "field": "rep", "is": "self" }, { "member_of": "<managers group id>" }] } }` |
|
|
44
|
+
| Each branch manager sees their branch's orders | `"rows": { "order": { "any": [{ "through": ["branch"], "field": "manager", "is": "self" }] } }` |
|
|
45
|
+
| Each employee sees only their own payslips; HR sees all | two apps: one stating `"payslip": { "any": [{ "field": "employee", "is": "self" }] }`, one for HR stating none |
|
|
46
|
+
| Team leads see people, not salaries | an app that draws no salary field |
|
|
40
47
|
|
|
41
|
-
|
|
48
|
+
A public link or an API key reaches every alias an app declares, so what outsiders may call is a second app over the
|
|
49
|
+
same tables, and the team's desk stays private (`app_bindings/api-apps`).
|
|
@@ -1,12 +1,12 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Build — a workspace or an app, call by call
|
|
2
2
|
|
|
3
|
-
Build from this page
|
|
3
|
+
Build from this page, `design` and the treatment the rows call for; a refusal names the `reference/<id>` page for the rest. The worked business: a bakery takes cake orders at the counter, a customer and one line per cake from the menu, moving taken, baking, ready, collected, with a slip printed when ready.
|
|
4
4
|
|
|
5
|
-
`get_workspace` shows what already exists.
|
|
5
|
+
`get_workspace` shows what already exists and `get_app` an app's tree: an app added or changed later starts there and states only the difference (`reference/changing-an-app`). Each write to an app makes a new version of it, and the live app is the only copy; sending an earlier tree restores the app, never a table or a row a write made, so try a write on a throwaway row. Before the first write, send the person who asked one message covering: the jobs and lists this business runs beyond those named, the trade's usual ones stated as defaults that stand; who does each job (`get_workspace` kind `member` lists the organization's people, not who works in this business or what each does); and the lists and papers they already keep, attached. A busy owner answers what comes first, so the message's first line is its first question, and it asks only what their papers and your defaults cannot settle, among them the papers they keep, asked by what they hold, and what else they keep track of; the defaults come after. "Go ahead" is a full answer. No second round: build from the answer. A short request names a business, not everything it runs on, so the workspace holds what that kind of business can't run without, such as what must never happen, what people are paid for and the papers it sends; your report names what you assumed, for them to change. What no one could guess from the data goes into a knowledge doc with `set_knowledge` (`knowledge_docs`).
|
|
6
6
|
|
|
7
7
|
## 1. Tables and their checks: `set_tables`
|
|
8
8
|
|
|
9
|
-
Linked tables go in one call, since they name each other by `ref`; `records` and checks may follow in the next call, so a refusal costs a patch rather than the whole document. A new table is named by its `ref`, which becomes its alias. One table per kind of thing, one column per fact, a link wherever one record points at another. A status is the stage of the work; a touch ("called") is a log row, a money fact ("paid in full") a formula, a quantity a number with its unit in `notation`. Read `design` before stating `records`, since a row's face, picture and mark are stated there. A table people work states `title` (who or what a row is; a code only where nothing else names it), `records` (an app over a table without it is refused) and `singular` (so is an Add over a table lacking it).
|
|
9
|
+
Linked tables go in one call, since they name each other by `ref`; `records` and checks may follow in the next call, so a refusal costs a patch rather than the whole document. A new table is named by its `ref`, which becomes its alias. One table per kind of thing, one column per fact, a link wherever one record points at another (`data_model`). A status is the stage of the work; a touch ("called") is a log row, a money fact ("paid in full") a formula, a quantity a number with its unit in `notation`. Read `design` before stating `records`, since a row's face, picture and mark are stated there. Over rows already there, read a sample before building on a field: one mostly empty holds up no screen. A table people work states `title` (who or what a row is; a code only where nothing else names it), `records` (an app over a table without it is refused) and `singular` (so is an Add over a table lacking it).
|
|
10
10
|
|
|
11
11
|
```json
|
|
12
12
|
{
|
|
@@ -62,7 +62,9 @@ Linked tables go in one call, since they name each other by `ref`; `records` and
|
|
|
62
62
|
}
|
|
63
63
|
```
|
|
64
64
|
|
|
65
|
-
`default_from` copies the menu's price when a line is made, so a later change leaves taken orders alone. `min`, `unique` and a check hold on every write; a check's language is `workflows/table-checks`, an effect after a write a table workflow (`workflows/table-workflows`).
|
|
65
|
+
`default_from` copies the menu's price when a line is made, so a later change leaves taken orders alone. `min`, `unique` and a check hold on every write; a check's language is `workflows/table-checks`, an effect after a write a table workflow (`workflows/table-workflows`). A check at its smallest, under an alias in the table's `checks`: `{"on": ["create"], "fail_when": "record.quantity < 1", "message": "\"Quantity is at least 1\""}`; `message` is an expression, so fixed text is a quoted string.
|
|
66
|
+
|
|
67
|
+
A `date` field is a day, or a moment with `"format": "datetime"`; a time of day is a `text` field with `"format": "time"`. Days between two dates in a formula is `differenceInCalendarDays(later, earlier)`; the helpers are named exactly (`reference/formula`). Two rows that must not hold one resource at once are the table's `no_overlap`: `{"from": "start_at", "to": "end_at", "by": "room"}`, a list where a row holds two resources (`reference/no-overlap`).
|
|
66
68
|
|
|
67
69
|
## 2. The paper: `set_template`
|
|
68
70
|
|
|
@@ -78,9 +80,7 @@ One template per paper the owner sends. A slot is named after a field of the rec
|
|
|
78
80
|
|
|
79
81
|
## 3. The app and its acts: `set_app`
|
|
80
82
|
|
|
81
|
-
**Which apps
|
|
82
|
-
|
|
83
|
-
**How each row reads** comes before the first List: `design/treatments` names the view per kind of row.
|
|
83
|
+
**Which apps**, and who gets each, is `app_architecture`. **How each row reads** comes before the first List: `design/treatments` names the view per kind of row.
|
|
84
84
|
|
|
85
85
|
**Start from one root List.** `{"type": "List", "entity": "cake_order"}` in the App's `children` is a whole app: the platform draws the page every row opens, the add and the Delete. `set_app` answers with what it drew and what it placed or folded; state only the difference.
|
|
86
86
|
|
|
@@ -116,11 +116,11 @@ One template per paper the owner sends. A slot is named after a field of the rec
|
|
|
116
116
|
|
|
117
117
|
**A press can be a mistake.** An Act also moves a row back (`when` the later stage, `set` the earlier), at the foot of the Section of the stage it leaves. **Someone with no seat** who signs or approves one record, a customer or a supplier, gets a Record's `Outside`: a link a member makes of that record.
|
|
118
118
|
|
|
119
|
-
`dry_run` checks a body and writes nothing
|
|
119
|
+
`dry_run` checks a body and writes nothing; then share each app (`app_architecture`). An Act's or stage's `owner` decides who presses.
|
|
120
120
|
|
|
121
121
|
## 4. What the owner will ask an agent: Query and Workflow nodes
|
|
122
122
|
|
|
123
|
-
What the business asks its assistant again and again (orders waiting for pickup) is a Query or Workflow node of the app, with a `description` for an agent that has not seen the screen (`agent_surface`
|
|
123
|
+
What the business asks its assistant again and again (orders waiting for pickup) is a Query or Workflow node of the app, with a `description` for an agent that has not seen the screen (`agent_surface/declaring-more`). A figure's name is not its definition: which rows count, by which field, now or over a window, is the owner's; where no field holds it, say so rather than total a near one. The App's `description` heads what a member's chat agent reads every turn, so a standing process the app expects of it goes there. A connected service is reached by a Workflow node's step (`workflows`).
|
|
124
124
|
|
|
125
125
|
## 5. The owner's rows: `create_records`
|
|
126
126
|
|
|
@@ -133,7 +133,7 @@ create_records {"table_id": "cake_line", "field_keys": ["order", "item", "quanti
|
|
|
133
133
|
|
|
134
134
|
## 6. Verify: `run_app_workflow`, `screenshot_app`
|
|
135
135
|
|
|
136
|
-
Move the owner's rows through the app as their person would, each only as far as the stage the owner says it is at
|
|
136
|
+
Move the owner's rows through the app as their person would, each only as far as the stage the owner says it is at. Every Act runs as `act_<key>`, the one name, handed what it asks. A dry run walks the moves and files nothing; then press each paper Act for real, on one row the owner's stage allows or on an example row left at its last stage: what is left on a row is what the owner opens. Prove a rule by sending the write with `dry_run: true`; never switch a check off. Only an admin passes `as_member`: it shows a member's view and reads, which is how each person's screen is checked. What the shots and runs must show is `design/the-rubric`.
|
|
137
137
|
```
|
|
138
138
|
run_app_workflow {"app_id": "app_…", "alias": "act_start_baking", "inputs": {"record_id": "rec_…", "prepaid": 20}, "dry_run": true}
|
|
139
139
|
screenshot_app {"app_id": "app_…", "as_member": "<member id>"}
|
|
@@ -143,9 +143,4 @@ screenshot_app {"app_id": "app_…", "as_member": "<member id>"}
|
|
|
143
143
|
|
|
144
144
|
Name the workspace and its organization after the business with `set_workspace` (`name`, `organization_name`, and `organization_language`: the language its papers, invitations and members default to, `vi` until set), and leave standing instructions there (`instructions`, one entry per rule): who the business is, its people's words, what any agent here must keep to. As an admin, invite the people named with `set_members` (`members` keyed by email, role `member` or `admin`), else say whom to invite.
|
|
145
145
|
|
|
146
|
-
Before you report
|
|
147
|
-
|
|
148
|
-
- Go through the owner's message and papers line by line and find each thing they named on a shot, as the person who uses it, at phone and desk width.
|
|
149
|
-
- Read each paper the presses made for a blank.
|
|
150
|
-
|
|
151
|
-
Put right or name each gap. Then show the owner what you built, job by job, each paper and what makes it, with the choices you made for them to change.
|
|
146
|
+
Before you report, answer each question of `design/the-rubric` with a call, and put right or name each gap. Then show the owner what you built, job by job, each paper and what makes it, with the choices you made for them to change.
|
package/docs/data_model.md
CHANGED
|
@@ -28,8 +28,9 @@ it runs.
|
|
|
28
28
|
description that says which one is real.
|
|
29
29
|
- **Empty is not the same as redundant.** A field nothing fills may still be the only home for a
|
|
30
30
|
real distinction — read what it MEANS before removing it.
|
|
31
|
-
- **A stored field becomes required only once every row holds a value**, so it always holds one:
|
|
32
|
-
|
|
31
|
+
- **A stored field becomes required only once every row holds a value**, so it always holds one: state its `default`,
|
|
32
|
+
which the same write fills into every row holding it empty (a draft takes it when submitted), or fill the empty cells
|
|
33
|
+
first; without either, the write is refused while a row holds it empty. A computed field's flag is checked as each row is written.
|
|
33
34
|
|
|
34
35
|
## One entity, one table — and the test is measurable
|
|
35
36
|
|
|
@@ -54,10 +55,10 @@ growing. Where one side holds more values than the other, the wider side must **
|
|
|
54
55
|
express rather than quietly picking the nearest value.
|
|
55
56
|
|
|
56
57
|
A value read through a link or a lookup reads exactly as the same field would on its own row: an option written by its alias in
|
|
57
|
-
a body and read as
|
|
58
|
-
across tables is a link to one table: two selects never compare, and a save that compares them is refused, in a check's lookup too. A filter or a write on another table's select takes a value read from this one by its alias, else its label.
|
|
58
|
+
a body and read as that alias, a member or a link by its id. A value a check matches
|
|
59
|
+
across tables is a link to one table, or a select whose options state the same aliases: two selects that state no alias in common never compare, and a save that compares them is refused, in a check's lookup too. A filter or a write on another table's select takes a value read from this one by its alias, else its label.
|
|
59
60
|
|
|
60
|
-
A lookup reads as one flat list of the values it looks up, in a check and in every body: `first(record.x)` is the one value through a one-row link and `includes(record.x, v)` asks whether any row holds `v`; two selects
|
|
61
|
+
A lookup reads as one flat list of the values it looks up, in a check and in every body: `first(record.x)` is the one value through a one-row link and `includes(record.x, v)` asks whether any row holds `v`; two selects that state no alias in common never compare. A single member, a single select, a number or a text reads as the value itself, and `first(...)` of one is refused when the body is saved. A rollup that adds up (a sum, a count) over no rows is 0, never empty, as `sum` over an empty list is; a min, a max or an average over no rows is empty.
|
|
61
62
|
|
|
62
63
|
## A copy boundary accounts for EVERY source field
|
|
63
64
|
|
|
@@ -138,8 +139,13 @@ or a `notation` on another type, never a `type`:
|
|
|
138
139
|
| Quantity | `{ type: "number", notation: { style: "unit", unit: "kg" } }` |
|
|
139
140
|
| Percentage | `{ type: "number", notation: { style: "unit", unit: "percent" } }` |
|
|
140
141
|
| Datetime | `{ type: "date", format: "datetime" }` |
|
|
142
|
+
| Month (a payroll or billing period) | `{ type: "date", format: "month" }` |
|
|
141
143
|
| Date range | `{ type: "date", format: "date_range" }` |
|
|
144
|
+
| Time of day (a class at 16:00, any day) | `{ type: "text", format: "time" }` |
|
|
142
145
|
|
|
146
|
+
A unit is written in any of its words, the workspace's language included, and stored as its code: `ngày` and `days` are
|
|
147
|
+
`day`, `giờ` is `h`. A time of day is stored `HH:mm`; `min` and `max` bound one by another time field (an end after its
|
|
148
|
+
start), and a table's `no_overlap` spans two of them (`reference/write-rules`).
|
|
143
149
|
### Changing a field
|
|
144
150
|
|
|
145
151
|
Read the table with `get_table`, which answers its document exactly as `set_tables` takes it, then send `set_tables` with
|
|
@@ -175,12 +181,16 @@ A table is named by its alias wherever a call names one (`table_id`, a link's `t
|
|
|
175
181
|
The partner may stand on a table the call does not name: `pair: "<alias>"` makes it there, or pairs the one-way link that table
|
|
176
182
|
already holds under that alias, and the answer lists that table among the call's. Only someone who manages that table may.
|
|
177
183
|
- A formula's `output_type` is inferred from its expression; state it only to override.
|
|
178
|
-
- **A call's removals are judged together, on what the call leaves.** A table and the links and lookups naming it, removed in one call, pass; every reader left outside the call is named in one answer, not one per retry. An app reading a field or an option that leaves is rebuilt in the same call, and the answer (a dry run too) lists each node of its tree that changed: a column, a filter, a sort key or a field of a part that only drew the field is dropped, and an option leaves every list of options it stood in. What has no meaning without it refuses the call, naming the node: an act that sets a removed option, a part left with nothing to draw, a list that held only the removed option. An app drawing a field that is retyped, or a link pointed at another table, is rebuilt too, its tree unchanged: where the field no longer lets the tree draw what it drew, the call refuses, naming the node, and a field that became a formula, rollup, lookup or autonumber leaves the app's allowlist of saves. A workflow body its author wrote is never rewritten: it is checked again against the tables as the call leaves them, and the call refuses, naming the workflow, only if it no longer checks. A table's check or workflow that reads a retyped field or a link pointed elsewhere is judged the same way and refuses, naming it, only if it no longer holds. Deleting one field through the table's field route drops no node: an app whose tree draws the field refuses it, naming the node.
|
|
184
|
+
- **A call's removals are judged together, on what the call leaves.** A table and the links and lookups naming it, removed in one call, pass; every reader left outside the call is named in one answer, not one per retry. An app reading a field or an option that leaves is rebuilt in the same call, and the answer (a dry run too) lists each node of its tree that changed: a column, a filter, a sort key or a field of a part that only drew the field is dropped, and a filter whose field the rows no longer draw is left out, and an option leaves every list of options it stood in. What has no meaning without it refuses the call, naming the node: an act that sets a removed option, a part left with nothing to draw, a list that held only the removed option. An app drawing a field that is retyped, or a link pointed at another table, is rebuilt too, its tree unchanged: where the field no longer lets the tree draw what it drew, the call refuses, naming the node, and a field that became a formula, rollup, lookup or autonumber leaves the app's allowlist of saves. A workflow body its author wrote is never rewritten: it is checked again against the tables as the call leaves them, and the call refuses, naming the workflow, only if it no longer checks. A table's check or workflow that reads a retyped field or a link pointed elsewhere is judged the same way and refuses, naming it, only if it no longer holds. Deleting one field through the table's field route drops no node: an app whose tree draws the field refuses it, naming the node.
|
|
179
185
|
- **A field something reads cannot go.** A query, a workflow, a check, an app only its owner can rebuild, or another
|
|
180
186
|
table's formula, rollup, lookup or copy that reads the field refuses its deletion, naming the reader. Change or remove
|
|
181
187
|
the reader first, or in the same call.
|
|
182
188
|
- **`force` consents to losing values:** deleting a field rows hold, removing an option rows hold, and a change of type
|
|
183
|
-
that does not convert every value
|
|
189
|
+
or format that does not convert every value (a date made a month cuts a day other than the 1st, a text made a time
|
|
190
|
+
clears a cell holding none). Unforced, the call is refused naming the cells; the API's table and field routes take
|
|
191
|
+
`force` in the body and refuse with `error_code` `ConversionNeedsForce`, its `findings` counting the `cells` per field.
|
|
192
|
+
- A field the call makes required with a `default` answers how many rows took it: `defaulted` per field alias on
|
|
193
|
+
`set_tables`, `rows_defaulted` on the API's table and field routes.
|
|
184
194
|
- A money formula is proven by its numbers. `query_records` with `aggregate` the affected totals before the change and after, and
|
|
185
195
|
compare. A new field in a formula is tested for the value you want, never for differing from an empty cell, which reads
|
|
186
196
|
`""` and differs from every option.
|
package/docs/design.md
CHANGED
|
@@ -4,14 +4,14 @@ An app is a tree of components: a List of one table, the Record a row opens, its
|
|
|
4
4
|
tree states COMPOSITION — which fields, lists and acts each job's screen holds; how each piece looks is the platform's,
|
|
5
5
|
one way per concept. A node the tree leaves out draws its default, from the table's facts (`records`, the stage, the
|
|
6
6
|
write rules): a List's Readings band, the stage buttons, the picture, a Record's Sections. State a node to change it,
|
|
7
|
-
or `false` at it to turn it off (`"readings": false`, a Record's `"row": { "image": false }`). A drawn Field is a control unless it
|
|
8
|
-
or its entity is read-only (`edit: false`); a stepped status never is, since Acts move it. Which apps a business needs is `
|
|
7
|
+
or `false` at it to turn it off (`"readings": false`, a Record's `"row": { "image": false }`). A field is written where its Record declares it: a Section's Field, the table's face (title, line, picture, figure), or every field where the Record states no Section; the head, a line, a column or a board draws it, and never makes one written; every head part (`row.title`, each `row.subtitle` entry, `row.figure`, `row.image`) takes `edit: false` to be read. A drawn Field is a control unless it
|
|
8
|
+
or its entity is read-only (`edit: false`); a stepped status never is, since Acts move it. Which apps a business needs is `app_architecture`.
|
|
9
9
|
|
|
10
10
|
**The visual bar.** Every screen is judged against it; a miss is a change to the tree.
|
|
11
11
|
|
|
12
12
|
- Each app looks like its own rows: the view its kind of row takes (`design/treatments`) — cards for things found by
|
|
13
13
|
their photo, a calendar or lanes for dated work, faces for people and organisations. A List left as a table is drawn
|
|
14
|
-
as one, the most common failure of an app; the
|
|
14
|
+
as one, the most common failure of an app; the answers of `set_app` and `get_app` note the view rows that are work in time call for (a calendar, lanes, a roster, a gantt where rows wait on one another).
|
|
15
15
|
- What needs attention leads the row: `records.mark` on a select or a computed category (a formula stating its options;
|
|
16
16
|
where it is empty, its seat is blank). A yes that needs attention (papers still owed) is a `Check` of its List over a
|
|
17
17
|
yes/no formula, in the warning tone on the row's line; every other yes reads in the success tone.
|
|
@@ -33,10 +33,6 @@ or its entity is read-only (`edit: false`); a stepped status never is, since Act
|
|
|
33
33
|
carrier, the authority) in the Section where that work happens, and the source of a
|
|
34
34
|
figure (a screenshot, an email, a sheet) on its row. Every files field is drawn somewhere.
|
|
35
35
|
|
|
36
|
-
**Each shot answers:** can the person find their row? Is what needs doing first, on the row's lead? Is anything
|
|
37
|
-
repeated or empty? Is anyone shown without their face? Is every paper visible? Across the workspace: can each app be
|
|
38
|
-
told apart by its own screen, and does any app hold a second entity behind tabs? A failed answer is a change to the tree.
|
|
39
|
-
|
|
40
36
|
<!-- generated:start words -->
|
|
41
37
|
|
|
42
38
|
**The words most builds state.** A node's page holds its rules and every other word: `reference/list-node`, `reference/records`, `reference/field`.
|
|
@@ -153,7 +149,7 @@ told apart by its own screen, and does any app hold a second entity behind tabs?
|
|
|
153
149
|
|
|
154
150
|
- `title` (text, required): The part's heading
|
|
155
151
|
- `key` (alias): Unique among its siblings
|
|
156
|
-
- `children` (list of (alias | Field | Fieldset | List | Reading | Statement | Act) (at least one)): What the part draws
|
|
152
|
+
- `children` (list of (alias | Field | Fieldset | List | Reading | Statement | Act | Check) (at least one)): What the part draws, in reading order
|
|
157
153
|
- `at` (list of alias (at least one)): Options of the record's status during which this part is the work now
|
|
158
154
|
- `when` (condition): Drawn only while this holds
|
|
159
155
|
|
|
@@ -198,17 +194,31 @@ told apart by its own screen, and does any app hold a second entity behind tabs?
|
|
|
198
194
|
|
|
199
195
|
## Look at it
|
|
200
196
|
|
|
201
|
-
After an apply, `screenshot_app` draws each app as its people see it — the register, and a record by its `path`
|
|
202
|
-
for a later screen of a long one) — at a desk's width and a phone's, naming the columns a table left off at each width;
|
|
197
|
+
After an apply, `screenshot_app` draws each app as its people see it — the register, and a record by its `path` or its `record_id`
|
|
198
|
+
(with a `path` on that record, such as one Section; `screen` for a later screen of a long one) — at a desk's width and a phone's, naming the columns a table left off at each width;
|
|
203
199
|
`-o <dir>` saves the shots from the CLI. Beside them, `verdict` is what a write of the stored tree would be refused for
|
|
204
|
-
now, and its notes. Answer the
|
|
200
|
+
now, and its notes. Answer `design/the-rubric`, change the tree with `nodes`, and write again. To go back,
|
|
205
201
|
send the tree saved before the change as `body` with `app_id`, nulling an App prop stated since (`words`, `scope`,
|
|
206
202
|
`period`, `icon`); tables and rows stay as they are.
|
|
207
203
|
|
|
204
|
+
## The rubric
|
|
205
|
+
|
|
206
|
+
Whether the build does the owner's work, answered by a call each, never from what you meant to write:
|
|
207
|
+
|
|
208
|
+
1. Each job the owner named, and each their kind of business cannot run without: which screen does it, and which press? Find each on a `screenshot_app` shot of the person who does it (`as_member`).
|
|
209
|
+
2. Can an agent do each job in one call, an `act_<key>` or a Query or Workflow node whose `description` names it? `get_app` lists them; `run_app_workflow` with `dry_run` proves one (`agent_surface/prove-an-app-as-an-agent`).
|
|
210
|
+
3. Is each kind of row in its treatment (`design/treatments`)? Timed work reads in a calendar or lanes, and a weekly plan as the dated rows it makes.
|
|
211
|
+
4. Does each screen show the least its next step needs, each fact once, the signal that a step is due leading?
|
|
212
|
+
5. Is anything cramped at desk or phone width?
|
|
213
|
+
6. Is every paper and every Export made, those this kind of business sends unasked too, with no blank? Press each paper Act and read the file it files; prove an Export with `run_app_query` and `export`.
|
|
214
|
+
|
|
215
|
+
A failed answer is a change to the tree, or a gap named to the owner.
|
|
216
|
+
|
|
208
217
|
## Treatments
|
|
209
218
|
|
|
210
|
-
|
|
211
|
-
node that would state it; a note refuses nothing.
|
|
219
|
+
The answers of `set_app` and `get_app` note the view rows that are work in time call for (a calendar, lanes, a roster, a gantt
|
|
220
|
+
where rows wait on one another), naming the node that would state it; a note refuses nothing. No other treatment below is noted.
|
|
221
|
+
Each kind of row's view is chosen before its List is written:
|
|
212
222
|
|
|
213
223
|
| The rows are | The treatment | Its own page |
|
|
214
224
|
|---|---|---|
|
|
@@ -216,7 +226,8 @@ node that would state it; a note refuses nothing. Each kind of row's view is cho
|
|
|
216
226
|
| Things with a photo, a scan or a paper | `records.image`; List `layout: "cards"` where the picture is how a row is found | `reference/cards` |
|
|
217
227
|
| Read by their day | List `layout: "calendar"`; on a record, a child List with `layout: {"agenda": …}` | `reference/calendar`, `reference/layouts` |
|
|
218
228
|
| Ranked by a figure, or worked by a date | List `sort: {"field": …, "desc": true}` on that column | |
|
|
219
|
-
| Booked on a resource | List `layout: {"lanes": {"by": …}}`, and the table's `no_overlap` | `reference/lanes`, `reference/write-rules` |
|
|
229
|
+
| Booked on a resource | List `layout: {"lanes": {"by": …}}`, and the table's `no_overlap` — a list of rules where a row holds two (a room and a teacher) | `reference/lanes`, `reference/write-rules` |
|
|
230
|
+
| A day's work given out to people or vehicles | List `layout: {"lanes": {"by": …}}` over rows holding a day and no hour | `reference/lanes` |
|
|
220
231
|
| A log of what happened | a child List with `layout: "timeline"` | `reference/layouts` |
|
|
221
232
|
| Opened to be worked on | the Record's Sections, in the order the work reaches them — `at` where it moves in steps; fields only one kind of row holds (a delay's cause, a safety issue's hours lost) in a Section whose `when` names that kind | |
|
|
222
233
|
| Rows that each belong to another row | a child List on that row's Record, with `create` and `remove` — and a child's own rows a List in that child's page, as deep as the data goes; a List with `same` where read-only | |
|
|
@@ -232,6 +243,7 @@ node that would state it; a note refuses nothing. Each kind of row's view is cho
|
|
|
232
243
|
| Photos that must be taken on site | `records.on_site: {"photos": […]}`: a photo taken through the camera keeps where the device stood, and a record holding one taken away says so | `reference/record-places-pins-and-cadence` |
|
|
233
244
|
| The real size of the thing (a carton, a piece of furniture, a pallet) | `records.size: {"across": …, "along": …, "up": …}`: three number fields in one length unit, read as one fact "400 × 300 × 250 mm" after the subtitle; a plan register draws each box at that size | `reference/record-places-pins-and-cadence`, `reference/plan` |
|
|
234
245
|
| A number painted on the thing, or a barcode or QR code on it | `records.scan: "iso6346"` or `"text"` (read off one photo by an agent), or `"code"` (decoded on the device, no agent): the title read on a phone, beside each search matching it | `reference/record-places-pins-and-cadence` |
|
|
246
|
+
| The rows a weekly pattern owes (a class's lessons on Tue and Thu at 16:00) | `records.cadence: [{"entity": …, "on": "<a multi-select of mon–sun>", "start": …, "end": …, "planned": …, "except": …}]` on the parent, and an Act `makes: "<child>"`: the press lists the rows still owed, each with what would stop it, and writes the ones ticked; pressed again it lists what is missing, and moves a row to the pattern's hours and copied fields where it differs and no person or linked row has touched it (ticked), else leaves it unticked saying why | `reference/record-places-pins-and-cadence` |
|
|
235
247
|
| Who did what on which day | List `layout: "roster"` with the List of its cells inside | `reference/roster` |
|
|
236
248
|
| Someone with no seat signs off one record (a buyer approves a proof, a client signs a handover) | the Record's `Outside`: the Fields and Lists the link shows as they are, and Acts that each move the status out of its `at` — a link a member makes of the record, never a seat; the link's page names the record only where the Outside states its title's field | |
|
|
237
249
|
| Steps people drop out of between | a Reading with `steps` on the record whose child rows count them | |
|
|
@@ -244,7 +256,7 @@ node that would state it; a note refuses nothing. Each kind of row's view is cho
|
|
|
244
256
|
| Rows on file a record takes in | a List with `pick` | |
|
|
245
257
|
| One owner's question across jobs | an App of Tabs and Readings and no register | |
|
|
246
258
|
|
|
247
|
-
What these nodes do not state, a long-form writing page or a bespoke tool, is a custom-code app (`lotics app create <name> --custom`, `
|
|
259
|
+
What these nodes do not state, a long-form writing page or a bespoke tool, is a custom-code app (`lotics app create <name> --custom`, `app_bindings`), never a new node.
|
|
248
260
|
|
|
249
261
|
### Faces and pictures
|
|
250
262
|
|
|
@@ -283,18 +295,24 @@ a time each — a member's periods in turn — read by what they hold.
|
|
|
283
295
|
|
|
284
296
|
`layout: "calendar"`, or `{ "calendar": { "date": "starts_at", "end": "ends_at" } }`: the rows by their day — a
|
|
285
297
|
month, a week, a day or a list; an entry at its hour where `date` holds one, over its span where `end` names the date it
|
|
286
|
-
runs to. The bare word takes both from the rows' facts and is refused, naming `date`, where they name none. An entry pressed opens a
|
|
287
|
-
it: the row, Delete, its Acts, Reschedule (the day alone moves; its hour and its length stay) and Open. Worked:
|
|
298
|
+
runs to. The bare word takes both from the rows' facts and is refused, naming `date`, where they name none. An entry pressed opens its row beside the calendar; where the app saves the row, a drag or F2 moves it. Worked:
|
|
288
299
|
`examples/calendar`.
|
|
289
300
|
|
|
290
301
|
#### Lanes
|
|
291
302
|
|
|
292
303
|
`layout: {"lanes": {"by": …}}` with `by` naming a one-row link whose target's rows are the lanes (a chair, a
|
|
293
304
|
machine, a room), each drawn even when empty: every row a block from the first date on its line to the
|
|
294
|
-
second, and a free stretch adds a row there. `loads` reads what a lane carries against what it holds
|
|
305
|
+
second, and a free stretch adds a row there. `loads` reads what a lane carries against what it holds: hours summed
|
|
306
|
+
within each day (across days, the fullest day, named), any other number the most its rows add up to at one time. A
|
|
295
307
|
`no_overlap` `by` the same link refuses two rows on one resource at once. A lane per person: `by` a member field
|
|
296
308
|
and `of` a role of the model, each member of it a lane, idle ones too. Worked: `examples/lanes`.
|
|
297
309
|
|
|
310
|
+
A day's work given out (stops to drivers, jobs to technicians): rows holding a day and no hour read at one day as cards
|
|
311
|
+
in lanes, those no lane holds, or holding no day, first in a tray. Each lane's head reads its count, its loads and its
|
|
312
|
+
row's status; a lane its link no longer admits (`options_where`) says so in its head and refuses a card. Where the app writes the link, cards ticked or
|
|
313
|
+
dragged go to a lane in one write, every row checked before any is written, and the List's first `sort`, ascending on a
|
|
314
|
+
number the app writes, is a card's place in its lane.
|
|
315
|
+
|
|
298
316
|
#### Gantt
|
|
299
317
|
|
|
300
318
|
`layout: {"gantt": {"start": …}}` (and `end`, else the table's first `due`; a `due` is a deadline, never an appointment date): one bar a row over
|
|
@@ -308,7 +326,16 @@ register's outline is. A child List on a record with this layout draws the bars
|
|
|
308
326
|
`layout: "roster"` with a List inside it over the child whose rows fill the days — one link back to the
|
|
309
327
|
register's table and a date on its line: what each row did on each day (shifts, runs, attendance). With
|
|
310
328
|
`expect` (and `of`) on the cells the columns are the options of a select instead of days: which papers each row holds.
|
|
311
|
-
Worked: `examples/roster`.
|
|
329
|
+
An `Export` with an html or Excel `template` prints the grid as the screen reads it (`document_templates/a-template`). Worked: `examples/roster`.
|
|
330
|
+
|
|
331
|
+
#### Weekly pattern
|
|
332
|
+
|
|
333
|
+
A row that owes a child's rows on set weekdays (a class's lessons, a person's shifts) states `records.cadence`, its days
|
|
334
|
+
a multi-select whose options are aliased `mon` to `sun`, and its times two `format: "time"` fields. The multi-select draws
|
|
335
|
+
as a week strip wherever a person writes it; a Section holding the cadence's fields draws them as one week pattern; the
|
|
336
|
+
row's line reads it as one fact ("Tue, Thu · 16:00–17:30"); a roster of the child reads each row's own days. An Act
|
|
337
|
+
`makes: "<child>"` lists the rows still owed under the row each is made for, a group's count and tick at its head, a
|
|
338
|
+
row that would be refused unticked with why, and writes the ticked ones (`reference/record-places-pins-and-cadence`). A row that differs from a changed pattern is proposed as a move, ticked only where no person edited its day, end or a copied field and no row links to it; the class says how many rows differ.
|
|
312
339
|
|
|
313
340
|
#### Agenda
|
|
314
341
|
|
|
@@ -390,7 +417,7 @@ it, asks the link and its quantities in its List's `create`, and copies the pric
|
|
|
390
417
|
keeps what was quoted when the book moves. A line's amount is a formula, the record's total a rollup over the rows
|
|
391
418
|
the List shows — what is not paid for is a second rollup, never a filter on the first, so each group subtotals.
|
|
392
419
|
Group the lines by the parts the record is quoted in (a container, a room, a leg), a field the line asks. A book worked only while a quote is written is the picker on the quote's lines; a book with a keeper, Acts or a history of its own is
|
|
393
|
-
an app (`
|
|
420
|
+
an app (`app_architecture`).
|
|
394
421
|
|
|
395
422
|
### The record
|
|
396
423
|
|
|
@@ -400,7 +427,8 @@ A record is a head, its parts and at most one Side. From three parts it shows on
|
|
|
400
427
|
part whole for the work there: a field may stand in any number of parts, and a field an Act requires draws beside it
|
|
401
428
|
unstated. A step may hold nothing but its name. What a person needs in view at every part (who it is for, how to reach
|
|
402
429
|
them) goes in a Side: it leaves the head and stays on the rows. The status stands in the head or the Side, never a
|
|
403
|
-
Section. `row` changes how the app's rows read, never a page.
|
|
430
|
+
Section. `row` changes how the app's rows read, never a page nor what the app writes. A List, Reading, Statement or Act stated alike in several
|
|
431
|
+
Sections draws once, in the first; a Check stated in a Section guards the whole record.
|
|
404
432
|
|
|
405
433
|
The Record's Sections, in the order the work reaches them: the fields people write, a Field per paper the record
|
|
406
434
|
keeps, a child List per child, the Acts at each one's foot. A register's `columns` are in the order the job reads them, as many as fit a desk; what is read only on the way deeper is the Record's, and a figure that is final only from a stage is a Field of that stage's Section, never a column read on every row at every stage. A register laid out in time (calendar, lanes, roster) opens the
|
|
@@ -417,7 +445,8 @@ Rows that each belong to one row of another table (a one-row link to it) are dra
|
|
|
417
445
|
its Record, `layout: "timeline"` where they are a log, `layout: {"agenda": …}` where they are planned on a day and within it, a roster of
|
|
418
446
|
them, or lanes of them by that link. Which children a record lists is the author's — one of them at least. A List
|
|
419
447
|
listing only some of them narrows by its `where`: a select (one leg's fees), or a yes/no — a formula's for what is
|
|
420
|
-
still owed — on a List that adds no rows.
|
|
448
|
+
still owed — on a List that adds no rows. A child List stating no `create` asks the table's required fields, natural key and
|
|
449
|
+
title; where defaults fill them all, it adds none. Rows on
|
|
421
450
|
file before the row they come to belong to — a job's cost lines before the supplier bill over them — are picked into
|
|
422
451
|
it: a List with `pick`, often with no `create` and no `remove`.
|
|
423
452
|
|
|
@@ -49,7 +49,9 @@ A paper prints the owner's own terms only: the clauses, wording and fields of th
|
|
|
49
49
|
when it is given one. Creating takes `type` and `name`, and the fields of its type; changing takes
|
|
50
50
|
`expected_version` — the `current_version` that `get_template` returned, so a concurrent edit is
|
|
51
51
|
refused rather than overwritten — and only the fields to change. A field the type does not take is
|
|
52
|
-
refused rather than dropped. `description` (one line on what the template produces) is on every type.
|
|
52
|
+
refused rather than dropped. `description` (one line on what the template produces) is on every type. A change is
|
|
53
|
+
built into every app whose Acts make the template; one an app can no longer be built with is refused, naming the app and
|
|
54
|
+
the marker, and nothing is written.
|
|
53
55
|
|
|
54
56
|
### Getting a file in
|
|
55
57
|
|
|
@@ -107,10 +109,15 @@ the `set_template` description for the reference; here is the capability:
|
|
|
107
109
|
`table` type; its variable types are string/number/date/boolean/array.) Inside a loop the row's number counted from 1
|
|
108
110
|
is `{{@ordinal}}` (Excel, HTML, email) or `{{$ordinal}}` (Word), the innermost loop's: an STT column is a cell holding
|
|
109
111
|
`{{@ordinal}}` beside the row's other markers. `{{@index}}` counts from 0.
|
|
112
|
+
- **Columns across** — a column per item of a list, for a grid of rows by days or by kinds. HTML/email nest a
|
|
113
|
+
`{{#each}}` inside a table row's; Excel repeats the columns between `{{#each-col columns}}` and `{{/each-col}}`, each
|
|
114
|
+
marker alone in its column, and a row's cell under the column is `{{cells | lookup:@index}}`, its list's item at that
|
|
115
|
+
column's place; Word repeats a table cell between a cell holding `{{FOR c IN columns}}` and one holding
|
|
116
|
+
`{{END-FOR c}}`, and a row's cells the same way inside its loop, `{{FOR k IN $r.cells}}` `{{$k}}` `{{END-FOR k}}`.
|
|
110
117
|
- **Conditional sections** — a block shown only when a condition holds (a "paid" stamp, an
|
|
111
118
|
optional notes block). Excel/HTML/email use `{{#if}}…{{else}}…{{/if}}`; Word uses `{{IF name}}…{{END-IF name}}`.
|
|
112
119
|
|
|
113
|
-
The `html` and `email` types print a raw value through a helper in the template's `locale` (`vi` or `en`; none prints in the organization's language): `{{money total "VND"}}`, `{{number qty}}`, `{{date issued_on}}`, `{{words total "USD"}}` (`reference/groups-and-templates` lists what each prints). `{{date (add_days issued_on -1)}}` prints the day before, `add_days` shifting a date by whole days. A value a helper cannot read fails the render.
|
|
120
|
+
The `html` and `email` types print a raw value through a helper in the template's `locale` (`vi` or `en`; none prints in the organization's language): `{{money total "VND"}}`, `{{number qty}}`, `{{date issued_on}}`, `{{words total "USD"}}` (`reference/groups-and-templates` lists what each prints). `{{date (add_days issued_on -1)}}` prints the day before, `add_days` shifting a date by whole days. A value a helper cannot read fails the render, and a template calling a helper the engine lacks (`{{eq a b}}`) is refused when saved, naming the ones it has.
|
|
114
121
|
|
|
115
122
|
A field can also print as a **QR code** or a **Code 128 barcode** (a picture a phone's camera or a scanner reads back): `{{qr link}}` or `{{code128 position 6}}` in html (never email: mail clients do not show the picture, and a save refuses it), `{{position | qr}}` or `{{position | code128:6}}` as a whole Excel cell (its row grows to the picture), `{{IMAGE qr(position)}}` or `{{IMAGE code128(position, 6)}}` in Word. The optional number is the picture's width in centimetres. Without it the width follows the value's length — each module prints 0.5 mm in a QR code and 0.33 mm in a barcode, so a longer value prints wider; a width that would shrink a module below what a scanner reads (0.3 mm, 0.19 mm) is refused, naming the least width that scans. An empty field draws nothing.
|
|
116
123
|
|
|
@@ -149,10 +156,11 @@ generate_document {"document_template_id": "dtl_…", "filename": "invoice-104
|
|
|
149
156
|
## A template an app's Act makes
|
|
150
157
|
|
|
151
158
|
An Act with `template` (or `templates`) fills an `html`, `excel` or `word` template from its record and files the result
|
|
152
|
-
(a PDF, an `.xlsx` or a `.docx`) in the record's files field `into`; `run_app_workflow` on `act_<key>`
|
|
159
|
+
(a PDF, an `.xlsx` or a `.docx`) in the record's files field `into`; `run_app_workflow` on `act_<key>` presses it. The Act hands the template the record's fields by their
|
|
153
160
|
alias, so name each variable after one: `{{customer}}`, `{{total}}`. A select, a member and a link arrive as their words
|
|
154
161
|
(a link as the linked row's title); a number and a date arrive raw, for `{{money total "VND"}}` and `{{date issued_on}}`.
|
|
155
|
-
|
|
162
|
+
A loop over a link of the record whose partner the table pairs, or over the alias of a table that links to the record
|
|
163
|
+
once, receives those rows with their fields, read under the app's row rules:
|
|
156
164
|
|
|
157
165
|
```html
|
|
158
166
|
<h1>Quote {{code}}</h1>
|
|
@@ -160,9 +168,10 @@ The rows of each child the record draws arrive under the name of the record's ow
|
|
|
160
168
|
{{#each lines}}<p>{{description}} × {{quantity}}</p>{{/each}}
|
|
161
169
|
```
|
|
162
170
|
|
|
163
|
-
Here `code`, `customer` and `total` are fields of the record and `lines` is its link to the child table
|
|
164
|
-
|
|
165
|
-
`{{$line.description}}` … `{{END-FOR line}}`.
|
|
171
|
+
Here `code`, `customer` and `total` are fields of the record and `lines` is its link to the child table, so
|
|
172
|
+
`{{#each quote_line}}`, the child table's alias, fills as well; a Word template loops the same rows with `{{FOR line IN lines}}` …
|
|
173
|
+
`{{$line.description}}` … `{{END-FOR line}}`. A link whose partner is not paired reaches no rows from the record, and
|
|
174
|
+
a loop printing a field of each of its items is refused, naming `pair`.
|
|
166
175
|
|
|
167
176
|
Every List the record draws and the template names (an html template's variables, a Word template's markers) hands its
|
|
168
177
|
rows, each List's `where` applied; a List the template does not name is not read. A List that only reads hands them under its
|
|
@@ -191,12 +200,31 @@ bound narrows what is listed and is never an access bound; the table's row rules
|
|
|
191
200
|
A List that reads by a path (`via: "<link>.<link>"`) hands its rows the same way. A List the screen draws as an outline (a record's own
|
|
192
201
|
sub-rows, in a table whose rows nest, with no `where`, total, group, long-text column or other narrowing) hands every sub-row, depth first, each after the row it is filed under and its
|
|
193
202
|
siblings in the List's order, with its depth as `level` (1 for the rows filed under the record): `{{#each tasks}}{{level}} {{name}}{{/each}}`.
|
|
194
|
-
A paper that lists an outline whose table has a field named `level` is refused.
|
|
195
|
-
|
|
203
|
+
A paper that lists an outline whose table has a field named `level` is refused. Inside a listed row a link arrives as the
|
|
204
|
+
titles of its rows (`{{#each marks}}{{this}}{{/each}}` prints them), so a loop there printing a field of each item is
|
|
205
|
+
refused, naming the key a List hands those rows under; so is one drawing a table cell per title, which lines up with no
|
|
206
|
+
column — a grid of rows by days is a roster's Export (below). A Word template is read for this when it is next saved.
|
|
196
207
|
|
|
197
208
|
A paper over many rows (a client's month, a statement) is that: a record of the period whose List is windowed by its dates, made by the Act's `template`; or a List `Export` with `template` and `per` (`reference/export-node`).
|
|
198
209
|
`reference/groups-and-templates` has the rest.
|
|
199
210
|
|
|
211
|
+
A roster's `Export` (an html or Excel `template`) is handed its grid over the window in view: `columns`, the days
|
|
212
|
+
holding a row in the file (with `expect`, every option), each a `label`, its `date` and `weekday`; and on each row (under the List's entity alias, `student` here)
|
|
213
|
+
`cells`, a word per column — each of its rows' mark, the option's `short` else its label (a row with no state, its title), joined by `, ` —
|
|
214
|
+
`counts`, how many of its rows stand at each option by alias (`held`, at none), and `total`, as the roster reads it (its owed or expected ratio, else the sum of the row's figure, else the count of the cells it holds):
|
|
215
|
+
|
|
216
|
+
```html
|
|
217
|
+
<tr><th>Student</th>{{#each columns}}<th>{{label}}</th>{{/each}}<th>Absent</th></tr>
|
|
218
|
+
{{#each student}}<tr><td>{{name}}</td>{{#each cells}}<td>{{this}}</td>{{/each}}<td>{{counts.absent}}</td></tr>{{/each}}
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
| | A | B | C | D | E |
|
|
222
|
+
|---|---|---|---|---|---|
|
|
223
|
+
| 1 | Student | `{{#each-col columns}}` | `{{label}}` | `{{/each-col}}` | Absent |
|
|
224
|
+
| 2 | `{{#each student}}` | | | | |
|
|
225
|
+
| 3 | `{{name}}` | | `{{cells \| lookup:@index}}` | | `{{counts.absent}}` |
|
|
226
|
+
| 4 | `{{/each}}` | | | | |
|
|
227
|
+
|
|
200
228
|
## Discovering and managing templates
|
|
201
229
|
|
|
202
230
|
These tools work across all five types:
|