@gramlot/gramlot-examples 0.2.9 → 0.2.10

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.10.
 
 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,8 @@ 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/`: eleven pages with formulas, controllers, named logic, events, the
+  end-to-end story and `dataRpc` calls to the endpoints of the page (`c01`–`c11`).
 
 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.10",
   "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.14"
   },
   "devDependencies": {
     "@genrojs/bag": ">=0.10.1",

package/src/gramlot_examples/catalog.json

@@ -239,6 +239,27 @@
           "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."
         }
       ]
     }

package/src/gramlot_examples/pages/README.md

@@ -7,15 +7,16 @@ 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/): eleven 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 and `dataRpc` calls to the endpoints of the page.
 
 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 and the endpoints
+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/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. 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. The last three pages call the server: **Endpoint**, **Call on change** and **Call on click**.
 
-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`.