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

package/src/gramlot_examples/catalog.json

@@ -260,6 +260,27 @@
           "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,16 +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/): eleven 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, the end-to-end story and `dataRpc` calls to the endpoints of the page.
+  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, the `Logic` of the page module and the endpoints
-of the page. 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/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. `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.
+`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**. **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**.
+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. An endpoint is a method of the page in each language: Python `@endpoint`, JavaScript `Page.registerEndpoint`.
+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`.