@gramlot/gramlot-examples 0.2.9 → 0.2.11

package/README.md

@@ -12,7 +12,7 @@ npm install @gramlot/gramlot-examples
 [![PyPI](https://img.shields.io/pypi/v/gramlot-examples)](https://pypi.org/project/gramlot-examples/)
 [![npm](https://img.shields.io/npm/v/@gramlot/gramlot-examples)](https://www.npmjs.com/package/@gramlot/gramlot-examples)
 
-Current release: 0.2.9.
+Current release: 0.2.11.
 
 The repositories of the family are described in
 [The Gramlot family](https://github.com/gramlot-org/gramlot/blob/main/docs/public/055-family.md)
@@ -26,8 +26,9 @@ same-name README:
 
 - `html_svg/`: thirteen HTML and SVG pages, without binding (`e01`–`e13`);
 - `binding/`: eleven pages whose DOM follows the Data (`b01`–`b11`);
-- `controllers/`: eight pages with formulas, controllers, named logic, events and
-  the end-to-end story (`c01`–`c08`).
+- `controllers/`: fourteen pages with formulas, controllers, named logic, events, the
+  end-to-end story, `dataRpc` calls to the endpoints of the page, `remote` fragments and
+  `dataRemote` values (`c01`–`c14`).
 
 Each `NN_name.js` exports `Page` and `Logic`; the Python page `NN_name.py` takes its
 `Logic` from the module beside it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gramlot/gramlot-examples",
-  "version": "0.2.9",
+  "version": "0.2.11",
   "description": "Gramlot example pages, the gallery page and its catalogue.",
   "license": "Apache-2.0",
   "repository": {
@@ -14,7 +14,7 @@
     "prepack": "node scripts/build-browser.mjs"
   },
   "dependencies": {
-    "@gramlot/gramlot": ">=0.2.12"
+    "@gramlot/gramlot": ">=0.2.16"
   },
   "devDependencies": {
     "@genrojs/bag": ">=0.10.1",

package/src/gramlot_examples/catalog.json

@@ -239,6 +239,48 @@
           "folder": "08_end_to_end",
           "description": "Title, input, radios, checkbox, formula, SVG, button and freeze together.",
           "explanation": "Setters after the controls, live editing, a radio pair, a formula and controller driving text and SVG, a counting button and freeze."
+        },
+        {
+          "key": "c09",
+          "title": "Endpoint",
+          "folder": "09_endpoint",
+          "description": "dataRpc calls an endpoint of the page and writes the value at its result path.",
+          "explanation": "The page declares with_vat with @endpoint in Python and Page.registerEndpoint in JavaScript. The author attributes of the dataRpc are the arguments; _init=True makes the call when the page starts."
+        },
+        {
+          "key": "c10",
+          "title": "Call on change",
+          "folder": "10_call_on_change",
+          "description": "dataRpc follows a ^ argument, with _delay, _onCalling and _onResult.",
+          "explanation": "Each change of the quantity calls the endpoint 500 ms after the last edit. _onCalling and _onResult are inline code that write the status; the latest call wins."
+        },
+        {
+          "key": "c11",
+          "title": "Call on click",
+          "folder": "11_call_on_click",
+          "description": "A dataRpc nested in a button, with _onError for a failing and a protected endpoint.",
+          "explanation": "Each click calls the endpoint. An exception answers application_error; an endpoint with auth answers not_authenticated on a server that knows no identity. _onError receives the error."
+        },
+        {
+          "key": "c12",
+          "title": "Remote",
+          "folder": "12_remote",
+          "description": "remote makes the content of an element a fragment built by the server.",
+          "explanation": "The section declares remote('details', record_id='^.record_id'). The page builds the fragment with @source in Python and Page.registerSource in JavaScript; each change of the record requests it again."
+        },
+        {
+          "key": "c13",
+          "title": "Cached remote",
+          "folder": "13_cached_remote",
+          "description": "remote with _cachedRemote and _onRemote, under a variable datapath.",
+          "explanation": "The rules fragment depends on the category of the product. _cachedRemote makes no request when the category is the same; _onRemote is inline code that counts the mounted fragments and writes the status."
+        },
+        {
+          "key": "c14",
+          "title": "Data remote",
+          "folder": "14_data_remote",
+          "description": "dataRemote computes a Data value with an endpoint when the value is read.",
+          "explanation": "The menu path holds a resolver of the endpoint load_menu with cacheTime 5. The ^.menu paragraph reads it: the answer arrives with the Data event. A change of the table loads the menu again."
         }
       ]
     }

package/src/gramlot_examples/pages/README.md

@@ -7,15 +7,17 @@ JavaScript, in three families:
 - [`binding/`](binding/): eleven pages whose DOM follows the Data through pointers,
   editing, booleans, style, SVG and freeze. The last three take the content of
   `html_svg` examples 06, 08 and 12 and add the binding.
-- [`controllers/`](controllers/): eight pages with formulas, controllers, named
+- [`controllers/`](controllers/): fourteen pages with formulas, controllers, named
   logic in the `Logic` class of the page module, inline expressions, node methods, buttons,
-  events and the end-to-end story.
+  events, the end-to-end story, `dataRpc` calls to the endpoints of the page, `remote`
+  fragments and `dataRemote` values.
 
 Each example is a file page: `NN_name.py`, its JavaScript equivalent `NN_name.js`,
 its README `NN_name.md`, and where needed a same-name stylesheet `NN_name.css`.
 `NN_name.js` exports `Page` and `Logic`: the JavaScript page uses both, the Python
 page takes `Logic` from it. The pages use only what the core `GramlotFileServer` serves:
-`Page.css`, the same-name stylesheet and the `Logic` of the page module. The gallery
+`Page.css`, the same-name stylesheet, the `Logic` of the page module, the endpoints
+and the Source fragments of the page. The gallery
 adds its own files: the frame script, a staged `<key>_aux.js` per example and its
 assets ([GE-010 §025](https://github.com/gramlot-org/gramlot-examples/blob/main/docs/010-gallery.md#ge-010-025)).
 

package/src/gramlot_examples/pages/controllers/09_endpoint.js

@@ -0,0 +1,29 @@
+import {Page as BasePage} from '@gramlot/gramlot/page';
+
+export class Page extends BasePage {
+    static title = 'Endpoint';
+    static css = ['/themes/gramlot-base/theme.css'];
+
+    main(root) {
+        const pane = root.div({class: 'example-page stack', datapath: 'invoice'});
+        pane.h1('Endpoint');
+
+        const result = pane.section({class: 'card stack'});
+        result.h2('Total with VAT, computed by the server');
+        const facts = result.dl();
+        for (const [label, key] of [['Price', 'price'], ['VAT rate (%)', 'rate'], ['Total with VAT', 'gross']]) {
+            facts.dt(label);
+            facts.dd(`^.${key}`, {id: key});
+        }
+
+        pane.dataRpc({method: 'with_vat', result_path: '.gross', price: '=.price', rate: '=.rate', _init: true});
+        pane.dataSetter({destination_path: '.price', value: 12.5});
+        pane.dataSetter({destination_path: '.rate', value: 22});
+    }
+
+    with_vat({price, rate}) { return Math.round(price * (100 + rate)) / 100; }
+}
+Page.registerEndpoint('with_vat');
+
+/** The page logic: this page names no methods. */
+export class Logic {}

package/src/gramlot_examples/pages/controllers/09_endpoint.md

@@ -0,0 +1,12 @@
+# 09 · Endpoint
+
+An endpoint is a method of the page that the browser calls for a value. `dataRpc(method, result_path, **parameters)` calls it and writes the answer at `result_path`.
+
+- **Declare the endpoint.** Python marks the method with `@endpoint`; JavaScript calls `Page.registerEndpoint('with_vat')` after the class.
+- **Arguments.** The other attributes of the `dataRpc` are the arguments of the call: `price` and `rate`, read here from the Data with `=`. Python receives them as keywords, JavaScript as one object.
+- **`**kwargs`.** `dataRpc` sends every attribute the author writes, and Python rejects a keyword the method does not declare. A Python endpoint called from `dataRpc` declares `**kwargs`.
+- **`_init=True`** calls the endpoint once when the page starts, after the setters. The total is Data: the `dd` shows it through `^.gross`.
+
+The call travels as one envelope on `POST /gramlot/rpc`; the page writes no `fetch`.
+
+**Try it:** Open the browser network panel and reload: one call to `/gramlot/rpc` carries `with_vat` with price 12.5 and rate 22.

package/src/gramlot_examples/pages/controllers/10_call_on_change.js

@@ -0,0 +1,37 @@
+import {Page as BasePage} from '@gramlot/gramlot/page';
+
+export class Page extends BasePage {
+    static title = 'Call on change';
+    static css = ['/themes/gramlot-base/theme.css'];
+
+    main(root) {
+        const pane = root.div({class: 'example-page stack', datapath: 'quote'});
+        pane.h1('Call on change');
+
+        const form = pane.form({class: 'card stack'});
+        form.html_label('Quantity', {for: 'quantity'});
+        form.input({type: 'number', min: 0, value: '^.quantity', live: true, id: 'quantity'});
+
+        const result = pane.section({class: 'card stack'});
+        result.h2('Quote');
+        const facts = result.dl();
+        for (const [label, key] of [['Total', 'total'], ['Status', 'status']]) {
+            facts.dt(label);
+            facts.dd(`^.${key}`, {id: key});
+        }
+
+        pane.dataRpc({method: 'quote', result_path: '.total', quantity: '^.quantity', _delay: 500, _init: true,
+            _onCalling: "this.SET('.status', 'Asking the server for ' + quantity)",
+            _onResult: "this.SET('.status', 'Answered ' + result + ' for ' + quantity)"});
+        pane.dataSetter({destination_path: '.quantity', value: 1});
+    }
+
+    quote({quantity}) {
+        quantity ??= 0;
+        return quantity * (quantity >= 10 ? 8 : 10);
+    }
+}
+Page.registerEndpoint('quote');
+
+/** The page logic: this page names no methods. */
+export class Logic {}

package/src/gramlot_examples/pages/controllers/10_call_on_change.md

@@ -0,0 +1,13 @@
+# 10 · Call on change
+
+A `dataRpc` follows the Data like a `dataController`: a `^` argument calls the endpoint again at every change. The endpoint `quote` prices 10 per piece, 8 from ten pieces on.
+
+- **`quantity='^.quantity'`** triggers the call when the quantity changes and sends the new value.
+- **`_delay=500`** calls 500 ms after the last change, once: typing `12` makes one call, not two.
+- **`_onCalling`** is inline code that runs before the call, with the arguments: it writes the status.
+- **`_onResult`** runs after the value is written at `result_path`, with the arguments and `result`.
+- **Latest call wins.** A new trigger aborts the call in flight and its answer is dropped.
+
+`_init=True` makes the first call when the page starts. The callbacks are inline code: the page needs a Content Security Policy that allows it.
+
+**Try it:** Type 12 in the quantity and watch the status before and after the answer.

package/src/gramlot_examples/pages/controllers/11_call_on_click.js

@@ -0,0 +1,36 @@
+import {Page as BasePage} from '@gramlot/gramlot/page';
+
+const SHOW_ERROR = "this.SET('.error', error.code + ': ' + error.message)";
+
+export class Page extends BasePage {
+    static title = 'Call on click';
+    static css = ['/themes/gramlot-base/theme.css'];
+
+    main(root) {
+        const pane = root.div({class: 'example-page stack', datapath: 'stock'});
+        pane.h1('Call on click');
+
+        const calls = pane.section({class: 'card stack'});
+        calls.h2('A dataRpc nested in the button');
+        const reserve = calls.button('Reserve the item', {id: 'reserve'});
+        reserve.dataRpc({method: 'reserve', result_path: '.reserved', item: '=.item', _onError: SHOW_ERROR});
+        const cancel = calls.button('Cancel the order (auth)', {id: 'cancel'});
+        cancel.dataRpc({method: 'cancel', result_path: '.reserved', item: '=.item', _onError: SHOW_ERROR});
+        const facts = calls.dl();
+        for (const [label, key] of [['Item', 'item'], ['Reserved', 'reserved'], ['Error', 'error']]) {
+            facts.dt(label);
+            facts.dd(`^.${key}`, {id: key});
+        }
+
+        pane.dataSetter({destination_path: '.item', value: 'Lamp'});
+    }
+
+    reserve({item}) { throw new Error(`${item} is out of stock`); }
+
+    cancel() { return false; }
+}
+Page.registerEndpoint('reserve');
+Page.registerEndpoint('cancel', {auth: 'admin'});
+
+/** The page logic: this page names no methods. */
+export class Logic {}

package/src/gramlot_examples/pages/controllers/11_call_on_click.md

@@ -0,0 +1,11 @@
+# 11 · Call on click
+
+A `dataRpc` nested in a `button` is the click mechanism of the button: each click calls the endpoint. A button has one mechanism, as in example 06.
+
+- **`_onError`** is inline code that runs when the call fails, with the arguments and `error`. `error.code` is the outcome, `error.message` the message of the server, `error.remoteName` the name of the exception (`LookupError` in Python, `Error` in JavaScript).
+- **An endpoint that raises.** `reserve` raises: the outcome is `application_error` and nothing is written at `result_path`.
+- **A protected endpoint.** `cancel` declares the rule `auth="admin"` (Python `@endpoint(auth="admin")`, JavaScript `Page.registerEndpoint('cancel', {auth: 'admin'})`). A server without the `auth` capability knows no identity: the call answers `not_authenticated` and the method does not run.
+
+Without `_onError` the failure reaches the browser console as an unhandled rejection.
+
+**Try it:** Press each button and read the error.

package/src/gramlot_examples/pages/controllers/12_remote.js

@@ -0,0 +1,33 @@
+import {Page as BasePage} from '@gramlot/gramlot/page';
+
+const RECORDS = {lamp: ['Lamp', 3], desk: ['Desk', 0], chair: ['Chair', 12]};
+
+export class Page extends BasePage {
+    static title = 'Remote';
+    static css = ['/themes/gramlot-base/theme.css'];
+
+    main(root) {
+        const pane = root.div({class: 'example-page stack', datapath: 'catalog'});
+        pane.h1('Remote');
+
+        const form = pane.form({class: 'card stack'});
+        form.html_label('Record', {for: 'record'});
+        const choice = form.select({value: '^.record_id', id: 'record'});
+        for (const [key, [name]] of Object.entries(RECORDS)) choice.option(name, {value: key});
+
+        const details = pane.section('Waiting for the server', {class: 'card stack', id: 'details'});
+        details.remote('details', {record_id: '^.record_id'});
+
+        pane.dataSetter({destination_path: '.record_id', value: 'lamp'});
+    }
+
+    details(root, {record_id}) {
+        const [name, stock] = RECORDS[record_id];
+        root.h2(name, {id: 'name'});
+        root.p(`${stock} in stock`, {id: 'stock'});
+    }
+}
+Page.registerSource('details');
+
+/** The page logic: this page names no methods. */
+export class Logic {}

package/src/gramlot_examples/pages/controllers/12_remote.md

@@ -0,0 +1,13 @@
+# 12 · Remote
+
+`remote` makes the content of an element a Source fragment that a method of the page builds on the server. The node method `remote(name, **params)` writes it on the element.
+
+- **Declare the fragment.** Python marks the method with `@source`; JavaScript calls `Page.registerSource('details')` after the class. The method receives the root of the fragment and the parameters, and populates the root.
+- **Parameters.** `record_id='^.record_id'` is a parameter of the call. A `^` parameter requests the fragment again at every change; a `=` parameter is only read.
+- **When.** The fragment is requested when the element starts. The authored content, `Waiting for the server`, stays until the first fragment arrives; each fragment replaces the content of the element.
+- **`**kwargs`.** A Python fragment method declares `**kwargs`, as a Python endpoint does.
+- **Latest wins.** A new request supersedes the one in flight; removing the element cancels its request.
+
+The request travels as one envelope on `POST /gramlot/rpc`; the page writes no `fetch`.
+
+**Try it:** Choose another record: the section shows the name and the stock that the server returns for it.

package/src/gramlot_examples/pages/controllers/13_cached_remote.js

@@ -0,0 +1,44 @@
+import {Page as BasePage} from '@gramlot/gramlot/page';
+
+const PRODUCTS = {
+    lamp: {name: 'Lamp', category: 'lighting'},
+    spot: {name: 'Spotlight', category: 'lighting'},
+    chair: {name: 'Chair', category: 'seating'},
+};
+const RULES = {lighting: 'Ships in two days, bulbs not included.', seating: 'Ships in a week, assembly required.'};
+const ON_REMOTE = "this.SET('requests', (this.GET('requests') ?? 0) + 1); this.SET('status', 'Mounted the ' + category + ' rules')";
+
+export class Page extends BasePage {
+    static title = 'Cached remote';
+    static css = ['/themes/gramlot-base/theme.css'];
+
+    main(root) {
+        const pane = root.div({class: 'example-page stack'});
+        pane.h1('Cached remote');
+        pane.html_label('Product', {for: 'product'});
+        const choice = pane.select({id: 'product', value: '^current'});
+        for (const [key, product] of Object.entries(PRODUCTS)) choice.option(product.name, {value: `products.${key}`});
+
+        const card = pane.article({datapath: '^current', class: 'card stack'});
+        card.h2('^.name', {id: 'name'});
+        const rules = card.div('Waiting for the server', {id: 'rules'});
+        rules.remote('rules', {category: '^.category', _cachedRemote: true, _onRemote: ON_REMOTE});
+
+        const facts = pane.dl();
+        for (const [label, key] of [['Requests', 'requests'], ['Status', 'status']]) {
+            facts.dt(label);
+            facts.dd(`^${key}`, {id: key});
+        }
+
+        pane.dataSetter({destination_path: 'products', value: PRODUCTS});
+        pane.dataSetter({destination_path: 'current', value: 'products.lamp'});
+    }
+
+    rules(root, {category}) {
+        root.p(RULES[category], {id: 'rule'});
+    }
+}
+Page.registerSource('rules');
+
+/** The page logic: this page names no methods. */
+export class Logic {}

package/src/gramlot_examples/pages/controllers/13_cached_remote.md

@@ -0,0 +1,12 @@
+# 13 · Cached remote
+
+The control attributes of `remote` act on the requests of the element. The `article` has a variable datapath, as in binding example 02; the rules fragment depends only on the category of the product.
+
+- **A change of the Data context** requests the fragment again: choosing another product moves the datapath of the `article`.
+- **`_cachedRemote=True`** makes no request when the parameters equal those of the last request. Lamp and Spotlight share the category `lighting`: switching between them makes no request.
+- **`_onRemote`** is inline code that runs after the fragment is mounted, with the parameters as locals: here it counts the mounted fragments and writes the status.
+- **`_if` and `_else`** are the other control attributes: a false `_if` makes no request and runs `_else`.
+
+The callbacks are inline code: the page needs a Content Security Policy that allows it.
+
+**Try it:** Choose Spotlight, then Chair. Requests stays at 1 for Spotlight and becomes 2 for Chair.

package/src/gramlot_examples/pages/controllers/14_data_remote.js

@@ -0,0 +1,31 @@
+import {Page as BasePage} from '@gramlot/gramlot/page';
+
+const MENUS = {dishes: ['Soup', 'Risotto', 'Fish'], drinks: ['Water', 'Lemonade', 'Coffee']};
+
+export class Page extends BasePage {
+    static title = 'Data remote';
+    static css = ['/themes/gramlot-base/theme.css'];
+
+    main(root) {
+        const pane = root.div({class: 'example-page stack', datapath: 'kitchen'});
+        pane.h1('Data remote');
+
+        const form = pane.form({class: 'card stack'});
+        form.html_label('Table', {for: 'table'});
+        const choice = form.select({value: '^.table', id: 'table'});
+        for (const key of Object.keys(MENUS)) choice.option(key[0].toUpperCase() + key.slice(1), {value: key});
+
+        const result = pane.section({class: 'card stack'});
+        result.h2('Menu, loaded by the server when it is read');
+        result.p('^.menu', {id: 'menu'});
+
+        pane.dataRemote({destination_path: '.menu', method: 'load_menu', cacheTime: 5, table: '^.table'});
+        pane.dataSetter({destination_path: '.table', value: 'dishes'});
+    }
+
+    load_menu({table}) { return MENUS[table].join(', '); }
+}
+Page.registerEndpoint('load_menu');
+
+/** The page logic: this page names no methods. */
+export class Logic {}

package/src/gramlot_examples/pages/controllers/14_data_remote.md

@@ -0,0 +1,10 @@
+# 14 · Data remote
+
+`dataRemote(destination_path, method, cacheTime=None, **params)` makes a Data path a value computed by an endpoint of the page. The endpoint is called when the path is read, not when the page starts.
+
+- **Declare the endpoint** as for `dataRpc`: Python `@endpoint`, with `**kwargs`; JavaScript `Page.registerEndpoint('load_menu')`.
+- **A read never waits.** The paragraph `^.menu` reads the path: the read returns the current value, empty before the first call, and starts the call. The answer is written with the Data event, so the paragraph shows the menu.
+- **`cacheTime`** is in seconds. `5` serves the stored value for five seconds, then the next read calls again. `None` or a negative value calls once; `0` calls at every read and writes the answer without the Data event.
+- **`table='^.table'`** is an argument of the endpoint. After the first call, a change of a `^` argument loads the value again at once and the paragraph receives it.
+
+**Try it:** Choose Drinks: the menu changes to the drinks that the server returns.

package/src/gramlot_examples/pages/controllers/README.md

@@ -2,10 +2,10 @@
 
 The pages of this family run code when the Data changes.
 
-`dataFormula` computes a value and writes it to its result path. `dataController` runs code for its effects. A button runs a nested controller at every click; `connect_on<event>` attributes connect other DOM events. The code is inline in the page, or a method of the `Logic` class that the page module `NN_name.js` exports; the Python page takes it from there.
+`dataFormula` computes a value and writes it to its result path. `dataController` runs code for its effects. `dataRpc` calls an endpoint of the page on the server and writes the answer to its result path. `remote` makes the content of an element a fragment built by the page on the server; `dataRemote` makes a Data path a value computed by an endpoint when it is read. A button runs a nested controller at every click; `connect_on<event>` attributes connect other DOM events. The code is inline in the page, or a method of the `Logic` class that the page module `NN_name.js` exports; the Python page takes it from there.
 
 Inline code needs a Content Security Policy that allows it. Named logic in the `Logic` class also runs under a strict policy.
 
-Start with **Formula** and **Controller**, then move the code to the `Logic` class with **Named logic**. The last page is the end-to-end story: every piece of the two families on one page.
+Start with **Formula** and **Controller**, then move the code to the `Logic` class with **Named logic**. **End-to-end story** puts every piece of the two families on one page. Six pages call the server. **Endpoint**, **Call on change** and **Call on click** use `dataRpc`; **Remote** and **Cached remote** mount a fragment of the page with `remote`; **Data remote** computes a Data value with `dataRemote`.
 
-Each example has a Python page and its JavaScript equivalent. Both use the `Logic` class of the JavaScript module.
+Each example has a Python page and its JavaScript equivalent. Both use the `Logic` class of the JavaScript module. An endpoint is a method of the page in each language: Python `@endpoint`, JavaScript `Page.registerEndpoint`. A fragment method is declared with Python `@source`, JavaScript `Page.registerSource`.