diff --git a/AGENTS.md b/AGENTS.md
index 99d9f32..e933684 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -20,7 +20,8 @@ VitePress build. It is also what CI runs, on every pull request
"@cap2ui5/cds-plugin"` **inside a code fence** names only what the package
really exports (and two dead packages are reported, in either form: the
port's `abap2UI5/…` and the plugin's withdrawn old name `cap2ui5`),
-- every `cds.cap2ui5.` is an option the plugin defines,
+- every `cds.requires.cap2ui5. ` is an option the plugin defines (and
+ 0.1.0's `cds.cap2ui5. ` is reported as the deprecated place),
- every `1.x.y` release number is the pinned runtime release,
- every internal anchor exists.
@@ -84,16 +85,21 @@ There is **no static frontend route** and no `webapp` option either. The page
the roundtrip route answers a GET with embeds the whole UI5 component, so the
plugin serves no frontend files (`/z2ui5/webapp/index.html` answers 404, and
cap2UI5's `scripts/consumer-test.mjs` asserts it). `plugin/package.json`
-defines `apps`, `requires` and `routes` under `cds.cap2ui5`, nothing else.
+defines `apps`, `roles` and `routes` under `cds.requires.cap2ui5` (next to
+CAP's own `model`); the plugin also reads `body_parser.limit`, which has no
+default there. 0.1.0's top-level `cds.cap2ui5`, with `requires` for the
+roles, is still read with a deprecation warning — the site teaches only the
+new place.
Path conventions inside cap2UI5:
- `plugin/` — the package: `cds-plugin.js` (the route, the auth guard, the
startup lines naming each app's address), `index.cds` (the `cap2ui5.Drafts`
entity), `index.js` (what `import`/`require` of `@cap2ui5/cds-plugin`
- returns) and `lib/`
- (`define-app.js`, `define-exit.js`, `draft-store.js`, `hints.js`,
- `runtime.js`)
+ returns), `index.d.ts` (its TypeScript declarations), `bin/cap2ui5.js`
+ (`npx cap2ui5 abap2js`) and `lib/` (`abap2js.js`, `add.js`, `config.js`,
+ `define-app.js`, `define-exit.js`, `draft-store.js`, `hints.js`,
+ `runtime.js`, `view-builder.js`)
- `examples/bookshop/` — a CAP project using it, with the test suite. Its apps
are in `examples/bookshop/srv/apps/`
- `runtime/` — a stand-in for `@abap2ui5/node-runtime`. Only `package.json`
@@ -103,7 +109,7 @@ Path conventions inside cap2UI5:
What a READER's project looks like is a different thing and must not be
confused with the above: they install `@cap2ui5/cds-plugin`, write apps in
-`srv/apps/` (configurable via `cds.cap2ui5.apps`), may add packages that bring
+`srv/apps/` (configurable via `cds.requires.cap2ui5.apps`), may add packages that bring
apps (`@cap2ui5/samples` for one), and get the route (whose GET page
embeds the UI5 frontend) and the draft entity from the plugin. A project from
`cds init --nodejs` is an ES module project, so the site's examples `import`
@@ -118,9 +124,15 @@ against the cap2UI5 repository.
- The framework's own classes are **not a supported import**. Importing
`@abap2ui5/node-runtime/output/…` technically works — the package exports
`./output/*` — but it couples an app to transpiler output. A JS app imports
- `@cap2ui5/cds-plugin` and nothing else; `c.raw` is the escape hatch to the transpiled
- `z2ui5_if_client`. An app that wants the framework's ABAP API (the view
- builder, for one) is written in ABAP and transpiled — see the views guide.
+ `@cap2ui5/cds-plugin` and nothing else. Since 0.2.0 that is enough: the
+ client an app's `main( client )` receives is `z2ui5_if_client` by its own
+ method names, and the plugin exports `z2ui5_cl_ui5_view_builder` and the
+ interface's constants. `client.raw` is the escape hatch to the transpiled
+ `z2ui5_if_client`.
+- Teach the client by its ABAP names (`client.check_on_navigated()`,
+ `client._bind("name")`, `client.view_display(xml)`). The 0.1.0 names
+ (`c.isDisplay`, `c.bind`, `c.view`, …) throw since 0.2.0 and appear only
+ where a page explains migrating from 0.1.0.
- Measure before documenting a framework behaviour. The runtime is upstream's
ABAP running on open-abap, and not everything upstream does works here —
the user exit is discovered by a class-repository lookup in ABAP and had to
diff --git a/docs/.vitepress/config.mjs b/docs/.vitepress/config.mjs
index a99fb27..02e4f2d 100644
--- a/docs/.vitepress/config.mjs
+++ b/docs/.vitepress/config.mjs
@@ -138,7 +138,7 @@ export default defineConfig({
{
text: 'API Reference',
items: [
- { text: 'c — the client facade', link: '/api/client' },
+ { text: 'client — z2ui5_if_client', link: '/api/client' },
{ text: 'App Interface', link: '/api/app-interface' }
]
}
diff --git a/docs/api/app-interface.md b/docs/api/app-interface.md
index c68488a..9d2976f 100644
--- a/docs/api/app-interface.md
+++ b/docs/api/app-interface.md
@@ -8,20 +8,24 @@ import { defineApp, defineExit, t } from "@cap2ui5/cds-plugin";
cannot be inferred from a literal; `defineExit` registers the one user exit —
it has [a page of its own](../guide/user-exit).
+The package also exports `z2ui5_cl_ui5_view_builder` — abap2UI5's view
+builder, see [Views](../guide/views) — and `z2ui5_if_client`, the client's
+constants as an ABAP app reads them (`z2ui5_if_client.cs_event.set_title`).
+
## `defineApp(name, class, opts?)`
```js
defineApp("ZCL_HELLO", class {
name = "";
- main(c) { /* … */ }
+ main(client) { /* … */ }
});
```
| | |
|---|---|
-| `name` | the app's name **on the wire** — what `?app_start=` takes and `c.navTo()` resolves. Uppercased. The file name is irrelevant |
-| `class` | a plain class with a `main(c)` method and its state as fields |
+| `name` | the app's name **on the wire** — what `?app_start=` takes and `client.nav_app_call()` resolves. Uppercased. The file name is irrelevant |
+| `class` | a plain class with a `main(client)` method and its state as fields |
| `opts.interfaces` | rarely needed; defaults to `["Z2UI5_IF_APP", "IF_SERIALIZABLE_OBJECT"]` |
It returns the wrapped class and registers it, so `defineApp` may be called
@@ -33,13 +37,16 @@ Without a `main`, it throws:
defineApp(ZCL_HELLO): the class needs a main( client ) method
```
-### `main(c)` is synchronous
+`client` is abap2UI5's `z2ui5_if_client`, by its own method names — see
+[`client`](./client).
+
+### `main(client)` is synchronous
No `async`, no `await` for anything the framework offers. Make it `async` only
when **your app** does I/O:
```js
-async main(c) {
+async main(client) {
this.books = await SELECT.from(cds.entities("my.bookshop").Books);
}
```
@@ -50,7 +57,39 @@ The wrapper awaits it either way.
Every field with an initial value becomes part of the model and survives the
roundtrip. A field the plugin cannot type is left out and **named in a
-warning**, never silently dropped.
+warning**, never silently dropped. Unlike ABAP there is no `PROTECTED
+SECTION`: every field is model.
+
+Inside `main` and inside any method it calls, fields read and write as plain
+values. A helper method that needs the client gets it as an ABAP app does —
+`this.client = client` in `main`. Assigned there rather than declared as a
+field, it is not part of the model or the draft:
+
+```js
+defineApp("ZCL_HELLO", class {
+ name = "";
+
+ view_display() {
+ this.client.view_display(`` +
+ ` `);
+ }
+
+ main(client) {
+ this.client = client;
+ if (client.check_on_navigated()) this.view_display();
+ }
+});
+```
+
+### Types in the editor
+
+The package ships TypeScript declarations. In a JavaScript app, annotate the
+client for completion and checked field names:
+
+```js
+/** @param {import("@cap2ui5/cds-plugin").Client<{ search: string }>} client */
+main(client) { /* with type checking on, client._bind("serach") is an error */ }
+```
## `t` — the type declarations
@@ -65,13 +104,17 @@ is not, declare it:
| `t.bool()` | `abap_bool`; the app sees `true`/`false` — same as `false` |
| `t.char(len)` | fixed-width character |
| `t.packed(len, dec)` | **packed decimal.** Use this for money |
+| `t.numc(len)` | ABAP's `N`: digits, kept with their leading zeros. A string |
+| `t.date()` | ABAP's `D`, `YYYYMMDD`. A string |
+| `t.time()` | ABAP's `T`, `HHMMSS`. A string |
| `t.struct({…})` | a structure. A plain object literal is one implicitly |
-| `t.table(row)` | a table; the argument is one **row** |
+| `t.table(row)` | a table; the argument is one **row**, the initial value is empty |
```js
price = t.packed(9, 2);
books = t.table({ ID: 0, title: "", price: t.packed(9, 2) });
addr = { street: "", zip: 0 }; // t.struct is implicit here
+cfg = t.struct({ mode: "list", items: [{ key: "x" }] });
```
Numbers are the ambiguity worth knowing: ABAP has `I`, `P` and `F` and they
@@ -79,8 +122,12 @@ render with different decimals, so an integer literal becomes `I`, a fractional
one `F`, and a decimal amount has to say so with `t.packed()`. Guessing would
produce a view with the wrong number of decimals and nothing to point at.
+Rows in a field initializer are its initial value — `rows = [{ id: 1, title: "first" }]`
+is a table typed from its first row, starting with those rows.
+
Structures and tables nest, to a depth of 8 — a cycle guard rather than a
-judgement. See [Data Binding](../guide/data-binding).
+judgement. Component names are UPPERCASE in the model. See
+[Data Binding](../guide/data-binding).
## `defineExit(exit)`
@@ -101,6 +148,6 @@ registered rather than discovered: [The User Exit](../guide/user-exit).
## Next
-- [**`c` — the client facade**](./client) — what `main` receives
+- [**`client` — `z2ui5_if_client`**](./client) — what `main` receives
- [**Data Binding**](../guide/data-binding) — the types in practice
- [**The User Exit**](../guide/user-exit) — `defineExit` in full
diff --git a/docs/api/client.md b/docs/api/client.md
index 6696a94..6a76c7a 100644
--- a/docs/api/client.md
+++ b/docs/api/client.md
@@ -1,89 +1,190 @@
-# API: `c` — the client facade
+# API: `client` — `z2ui5_if_client`
-The single argument `main` receives. Every member is **synchronous**: queries
-are resolved before `main` runs, commands are recorded and replayed after it.
+The single argument `main` receives. It is abap2UI5's `z2ui5_if_client`, by
+its own method names: `client->check_app_prev_stack( )` is
+`client.check_app_prev_stack()`. [abap2UI5's documentation](https://abap2ui5.github.io/docs/)
+of a method is therefore the documentation of the JavaScript one; this page
+lists them and says where JavaScript differs.
```js
defineApp("ZCL_X", class {
- main(c) { /* c is this page */ }
+ main(client) { /* client is this page */ }
});
```
-## Lifecycle
+Two rules for every method:
+
+- **Parameters.** A method's preferred parameter is its one positional
+ argument; parameters by name are **one object** with the ABAP names.
+ ``client->_event( val = `GO` t_arg = … )`` is
+ `client._event({ val: "GO", t_arg: [ … ] })`. A second positional argument,
+ or a name the method does not have, throws and lists the parameters.
+- **Synchronous.** Queries are resolved before `main` runs; commands are
+ recorded and carried out **in the order you called them** after it returns.
+ No `await` for anything the client offers.
+
+## Lifecycle and queries
+
+| | |
+|---|---|
+| `client.check_on_init()` | `true` on the first roundtrip of **this app instance**, and only that one. Seed state here |
+| `client.check_on_navigated()` | `true` on the first roundtrip **and** every time this app gets the screen back — a called app leaving, a value help closing, a bookmark restored. **Render here** |
+| `client.check_on_event(val)` | whether this roundtrip answers the event `val`; without `val`, whether it answers any event |
+| `client.check_app_prev_stack()` | `true` if there is an app to return to — for a Page's `showNavButton` |
+| `client.get_event()` | the event this roundtrip answers; `""` on an app start |
+| `client.get_event_arg(v)` | the *v*-th event argument, **1-based**, `1` by default. The first 8 are resolved up front; beyond that, `client.raw` |
+| `client.get()` | what the frontend sent with this roundtrip, as plain values under the ABAP component names: `event`, the draft ids (`s_draft`), the browser location (`s_config`), device, focus and scroll information, and `r_event_data` — what a returning app handed over |
+| `client.get_app_prev()` | the app on the other side of the last navigation — inside a called app its caller, back in the caller the app that just returned. A `defineApp` app as its fields' plain values, an ABAP app as the instance |
+| `client.get_app()` | without an id, the running app itself |
+| `client.get_app(id)` | the app behind a draft id. It is read from the draft store **after** `main`, so its fields can be written, not read; hand it to `nav_app_leave()` or `nav_app_call()` |
+| `client.app_state_get_href()` | the absolute link to this app's current state |
+
+`check_on_init()` implies `check_on_navigated()`. See [App Lifecycle](../guide/lifecycle)
+for why rendering only on `check_on_init()` produces a screen that silently
+does not refresh.
+
+## Binding
| | |
|---|---|
-| `c.isFirstRun` | `true` on the first roundtrip of **this app instance**, and only that one. Seed state here |
-| `c.isDisplay` | `true` on the first roundtrip **and** every time this app gets the screen back — a called app leaving, a value help closing, a bookmark restored. **Render here** |
-| `c.canGoBack` | `true` if there is an app to return to. Guard `navBack` with it |
-| `c.eventName` | the event this roundtrip answers; `""` on an app start |
-| `c.eventArg(i)` | the *i*-th event argument, **1-based**. The first 8 are resolved up front; beyond that use `c.raw` |
-| `c.prevApp` | the app on the other side of the last navigation, as plain values — how a called app's result is read |
+| `client._bind(name)` | the binding of a field for a view attribute: `{/NAME}`. Takes the field's **name**, since a JavaScript value cannot carry a reference. Throws, listing the known fields, if it is not one |
+| `client._bind("s_order-customer")` | a component of a structure field, named as ABAP names it (`.` works too) |
+| `client._bind({ val, path: true })` | the bare path `/NAME`, for a composed binding |
+| `client._bind({ val: column, tab, tab_index })` | one cell of a table field; `tab_index` is the row, 1-based |
+| `client._bind({ val, omit_initial, omit_initial_paths, json, switch_default_model })` | `_bind( )`'s options, as in ABAP |
+| `client._bind_path(name)` | the same as `_bind({ val: name, path: true })` |
+
+```js
+``
+`… ` +
`` +
- `` +
+ `` +
`` +
`` +
`` +
- ` `);
return;
}
- if (c.eventName === "GO") c.messageBox(`Hello ${this.name}`);
+ if (client.check_on_event("GO")) client.message_box_display(`Hello ${this.name}`);
}
});
```
-Run it:
+Run it — `cds watch` prints the address, and the user to log in as:
```
-http://localhost:4004/rest/root/z2ui5?app_start=ZCL_JS_HELLO
+http://localhost:4004/sap/bc/z2ui5?app_start=ZCL_JS_HELLO
```
## Line by line
| | |
|---|---|
-| `import { … } from "@cap2ui5/cds-plugin"` | the plugin's export surface: `defineApp`, `t`, and `defineExit` for the [user exit](../guide/user-exit) |
+| `import { … } from "@cap2ui5/cds-plugin"` | what the plugin exports: `defineApp`, `t`, the view builder `z2ui5_cl_ui5_view_builder`, the `z2ui5_if_client` constants, `defineExit` for the [user exit](../guide/user-exit), and `abap2js` |
| `defineApp("ZCL_JS_HELLO", …)` | the first argument is the name **on the wire** — what `?app_start=` takes. The file name does not matter |
| `name = ""` | app state. An empty string types it as `string`, and it survives the roundtrip because the instance is written to `cap2ui5.Drafts` |
-| `main(c)` | synchronous — no `async`, no `await` |
-| `c.isDisplay` | the render branch. True on the first roundtrip **and** whenever the app gets the screen back |
-| `c.bind("name")` | the binding path — two-way, so what the user types arrives on `this.name` |
-| `c.event("GO")` | the handler expression; the next roundtrip has `c.eventName === "GO"` |
-| `c.messageBox(…)` | a dialog with an OK button |
+| `main(client)` | synchronous — no `async`, no `await`. `client` is abap2UI5's `z2ui5_if_client`, by its ABAP method names |
+| `client.check_on_navigated()` | the render branch. True on the first roundtrip **and** whenever the app gets the screen back |
+| `client._bind("name")` | the binding path — two-way, so what the user types arrives on `this.name` |
+| `client._event("GO")` | the handler expression; on the next roundtrip `client.check_on_event("GO")` is true |
+| `client.message_box_display(…)` | a dialog with an OK button |
+
+The ABAP app it corresponds to calls `client->check_on_navigated( )`,
+`client->_bind( name )`, ``client->_event( `GO` )`` and
+`client->message_box_display( … )` — the same methods. The full list is the
+[client API](../api/client).
## What happens when you click
@@ -63,27 +71,28 @@ defineApp("ZCL_JS_HELLO", class {
name = "";
count = 0;
- main(c) {
- if (c.isDisplay) {
- c.view(
+ main(client) {
+ if (client.check_on_navigated()) {
+ client.view_display(
`` +
`` +
- ` `);
return;
}
- if (c.eventName === "GO") {
+ if (client.check_on_event("GO")) {
this.count++;
- c.messageToast(`Hello ${this.name}, click ${this.count}`);
+ client.message_toast_display(`Hello ${this.name}, click ${this.count}`);
}
}
});
```
`count` needs no re-render: changed **bound data** is pushed to the view on its
-own. You call `c.view()` again only when the view's *structure* changes.
+own. You call `client.view_display()` again only when the view's *structure*
+changes.
The counter also survives a server restart — the state is a row in your
database, not memory. See [Persistence](../guide/persistence).
@@ -91,5 +100,5 @@ database, not memory. See [Persistence](../guide/persistence).
## Next
- [**List & Detail**](./list) — a table filled from your own CDS entity
-- [**App Lifecycle**](../guide/lifecycle) — `isDisplay` vs. `isFirstRun`
+- [**App Lifecycle**](../guide/lifecycle) — `check_on_navigated()` vs. `check_on_init()`
- [**Data Binding**](../guide/data-binding) — the types
diff --git a/docs/examples/list.md b/docs/examples/list.md
index 9f5b26f..b21dc1c 100644
--- a/docs/examples/list.md
+++ b/docs/examples/list.md
@@ -2,8 +2,9 @@
A table filled from your own CDS entity, and a row that can be written back.
This is [`examples/bookshop/srv/apps/books.js`](https://github.com/cap2UI5/cap2UI5/blob/main/examples/bookshop/srv/apps/books.js)
-— the app the coexistence test drives, so both directions below are measured
-rather than sketched.
+in ES-module form (the bookshop itself is CommonJS and `require`s) — the app the
+coexistence test drives, so both directions below are measured rather than
+sketched.
```js
// srv/apps/books.js
@@ -16,37 +17,38 @@ defineApp("ZCL_JS_BOOKS", class {
hits = 0;
books = t.table({ ID: 0, title: "", author: "", price: t.packed(9, 2) });
- async main(c) {
- if (c.isDisplay) {
- c.view(
+ async main(client) {
+ if (client.check_on_navigated()) {
+ client.view_display(
`` +
`` +
- `` +
+ `` +
`` +
`` +
`` +
- ` ` +
- `` +
+ `` +
`` +
@@ -60,16 +48,30 @@ defineApp("ZCL_ORDERS", class {
`
` +
``);
+ return;
+ }
+
+ if (client.check_on_event("GO")) {
+ const { Orders } = cds.entities("my.shop");
+ let q = SELECT.from(Orders).where`customer like ${"%" + this.customer + "%"}`;
+ if (this.minTotal) q = q.and`total >= ${this.minTotal}`;
+ if (this.onlyOpen) q = q.and`open = ${true}`;
+
+ this.rows = await q;
+ this.hits = this.rows.length;
+ client.message_toast_display(`${this.hits} orders`);
}
}
});
```
-## Why the event branch comes first
+## Why `GO` does not render
-`GO` runs, *then* the render branch runs in the same roundtrip. The order
-matters: the table the view binds is the one the query just produced. Writing
-the render branch first with a `return` would show the user the previous result.
+`client.check_on_navigated()` is true on the first roundtrip and when the app
+gets the screen back — not on the `GO` roundtrip. The view stays as it is, and
+the new `rows` and `hits` are pushed into it on their own: changed bound data
+needs no `client.view_display()`. Render again only when the view's
+*structure* changes.
## The types the form needs
@@ -84,8 +86,9 @@ A `CheckBox` binds `selected`, an `Input` binds `value` — ordinary UI5.
## Building the query conditionally
-`cds.ql` composes, so the filter is plain JavaScript: add a `where` only for the
-fields the user filled. The `${…}` holes are **bound parameters**, so a customer
+`cds.ql` composes, so the filter is plain JavaScript: the customer condition is
+always there (an empty one is `like '%%'`, which matches every row), and an
+`and` is added only for the other fields the user filled. The `${…}` holes are **bound parameters**, so a customer
name containing a quote is a value and not a syntax error.
## Keeping the criteria
diff --git a/docs/examples/static-xml-view.md b/docs/examples/static-xml-view.md
index 59641aa..80b03d3 100644
--- a/docs/examples/static-xml-view.md
+++ b/docs/examples/static-xml-view.md
@@ -5,7 +5,7 @@ the middle of your logic. For a large screen, keep the XML in its own file and
read it once.
::: info Illustrative
-`c.view()` taking any string is the tested part. Loading it from disk is
+`client.view_display()` taking any string is the tested part. Loading it from disk is
ordinary Node — shown here because it is the question that comes up as soon as a
view passes a screenful.
:::
@@ -34,7 +34,7 @@ Two kinds of placeholder are in there, and the difference matters:
relative to the row, needs nothing from you, and must survive to the browser
untouched.
- `{CUSTOMER_PATH}` and `{GO_HANDLER}` are **yours** — they stand where
- `c.bind()` and `c.event()` go.
+ `client._bind()` and `client._event()` go.
## The app
@@ -49,14 +49,14 @@ defineApp("ZCL_ORDERS_FILE", class {
customer = "";
rows = t.table({ customer: "" });
- main(c) {
- if (c.isDisplay) {
- c.view(XML
- .replace("{CUSTOMER_PATH}", c.bind("customer"))
- .replace("{GO_HANDLER}", c.event("GO")));
+ main(client) {
+ if (client.check_on_navigated()) {
+ client.view_display(XML
+ .replace("{CUSTOMER_PATH}", client._bind("customer"))
+ .replace("{GO_HANDLER}", client._event("GO")));
return;
}
- if (c.eventName === "GO") { /* … */ }
+ if (client.check_on_event("GO")) { /* … */ }
}
});
```
@@ -66,6 +66,10 @@ is what you want for a placeholder that appears once. For one that repeats, use
`replaceAll` — and pick placeholder names that cannot collide with a UI5 binding
(`{GO_HANDLER}`, not `{GO}`).
+What `client._event("GO")` returns is a placeholder that becomes the event's
+wire after `main()` returns. Putting it into the string unchanged, as here, is
+what it is for; parsing or comparing it is not.
+
## Why read it at load
`readFileSync` at module scope runs once, when the plugin imports the file.
@@ -82,9 +86,9 @@ inside `main` until you are done.
|---|---|
| a screenful of XML | keep it inline. The template literal is easier to follow |
| a large form, or a view a designer edits | a file, with your editor's XML support |
-| a view assembled from repeated pieces | neither — build it with functions, see [Views](../guide/views) |
+| a view assembled from repeated pieces | neither — build it with `z2ui5_cl_ui5_view_builder`, or with functions, see [Views](../guide/views) |
## Next
-- [**Views**](../guide/views) — composing XML in JavaScript
+- [**Views**](../guide/views) — composing XML in JavaScript, and the view builder
- [**Selection Screen**](./selection-screen) — a form inline
diff --git a/docs/guide/data-binding.md b/docs/guide/data-binding.md
index 2a927c1..568aa56 100644
--- a/docs/guide/data-binding.md
+++ b/docs/guide/data-binding.md
@@ -1,19 +1,19 @@
# Data Binding
-A field of your class is a bound model field. `c.bind("name")` gives you the
-binding path to put in the view; the browser sends the value back, and the
+A field of your class is a bound model field. `client._bind("name")` gives you
+the binding path to put in the view; the browser sends the value back, and the
framework applies it to the instance before your `main` runs.
```js
defineApp("ZCL_HELLO", class {
name = "";
- main(c) {
- if (c.isDisplay) {
- c.view(``
+`` +
+ async main(client) {
+ if (client.check_on_navigated()) {
+ client.view_display(
+ ``);
return;
}
- if (c.eventName === "SEARCH") {
+ if (client.check_on_event("SEARCH")) {
this.books = await SELECT.from(cds.entities("my.bookshop").Books);
}
}
@@ -82,9 +110,9 @@ defineApp("ZCL_BOOKS", class {
Two things to note:
-- **the row fields are UPPERCASE in the view** — `{TITLE}`, `{PRICE}`. Component
- names are stored lowercase, as the transpiler does, and appear uppercase in
- the model;
+- **the model names are UPPERCASE in the view** — `{TITLE}`, `{PRICE}`, and a
+ field `name` is `/NAME`. Component names are stored lowercase, as the
+ transpiler does, and appear uppercase in the model;
- **assign the whole array.** `this.books = await SELECT…` replaces the table;
the plugin rebuilds the rows. Pushing into the array you read back does not
write through.
@@ -102,18 +130,16 @@ order = {
```
The model carries `ORDER.CUSTOMER.CITY` and `ORDER.LINES[].PRICE`, decimals
-included, through the draft and back. Read the whole tree as plain values:
+included, through the draft and back. Bind a component by its ABAP name,
+`client._bind("order-customer-city")`, and read the whole tree as plain values:
```js
const city = this.order.customer.city;
this.order = { ...this.order, customer: { name: "Ada", city: "London" } };
```
-::: info This was documented as unsupported for a while. It was not.
-Three pages said nested state could not be done. It could — the limitation was
-one guard in the plugin's own type derivation, written when only scalars had
-been tried. "Unsupported" must say whose limitation it is.
-:::
+Assigning a structure is ABAP's `s = VALUE #( … )`: what the new value leaves out
+is initial afterwards.
The depth limit is **8**, and it is a cycle guard rather than a judgement: an
object containing itself would otherwise recurse until the stack goes. A field
@@ -129,14 +155,16 @@ order.self.self.self.self.self.self.self.a is nested more than 8 levels deep.
model and **named in a warning** rather than silently dropped:
```
-[defineApp] ZCL_ORDER: these fields are NOT part of the model —
- total has no ABAP type: null, undefined and an empty array carry none.
+[cap2ui5] - defineApp ZCL_ORDER: these fields are NOT part of the model —
+ total has no ABAP type
+ Give an initial value, or declare it with t.table(…) / t.struct(…) / t.packed(…) / t.char(…). The app runs without them.
```
Give it an initial value, or declare it with `t.table(…)` / `t.packed(…)`.
## Next
-- [**Events**](./events) — `c.event` and its arguments
-- [**View Builder**](./views) — what goes inside `c.view`
+- [**Events**](./events) — `client._event` and its arguments
+- [**View Builder**](./views) — what goes inside `client.view_display`
- [**Persistence**](./persistence) — what survives the roundtrip
+- [**Client API**](../api/client) — every `_bind` option
diff --git a/docs/guide/ecosystem.md b/docs/guide/ecosystem.md
index 9660df3..d1a9e93 100644
--- a/docs/guide/ecosystem.md
+++ b/docs/guide/ecosystem.md
@@ -40,7 +40,8 @@ package `cap2ui5`, which is withdrawn from npm.
## What the plugin does and does not own
**Owns:** the CAP route and its authentication guard, `cap2ui5.Drafts` and the
-draft store over it, `defineApp` and the `c` facade, the two ABI gates.
+draft store over it, `defineApp` and the client that maps a JavaScript app
+onto `z2ui5_if_client`, the two ABI gates.
**Does not own:** views, the wire format, the model service, the lifecycle, the
UI5 shell, the frontend actions — all upstream's, running unmodified. The plugin
diff --git a/docs/guide/events.md b/docs/guide/events.md
index 934aa0e..b8665df 100644
--- a/docs/guide/events.md
+++ b/docs/guide/events.md
@@ -1,58 +1,81 @@
# Events
-`c.event("NAME")` produces the wire string a control's event attribute needs.
-The next roundtrip answers with `c.eventName === "NAME"`.
+`client._event("NAME")` produces the handler a control's event attribute needs.
+The next roundtrip answers `client.check_on_event("NAME")` with `true`.
```js
defineApp("ZCL_HELLO", class {
name = "";
count = 0;
- main(c) {
- if (c.isDisplay) {
- c.view(
- `/newValue}"],
+ s_ctrl: { check_queue_last: true, check_no_busy: true },
+})}"/>`
+```
+
+| `s_ctrl` | |
+|---|---|
+| `check_queue_last` | keep the last firing while a roundtrip runs, instead of dropping it — for `liveChange` |
+| `check_no_busy` | no busy indicator for this event |
+| `check_arg_literal` | every argument is quoted, so none is read as a binding or expression |
+| `check_prevent_default` | cancel the control's default for this event |
+
+`client._event("TAKE", ["red"])` — a second positional argument — is refused:
+the one positional argument is `val`, everything else goes by name.
+
+::: info The argument has to be on the wire
+Only the browser shows whether it is. A test that plays the frontend's part by
+hand and feeds the argument table itself simulates a browser that may never
+send it. A method that composes view XML needs a browser test, not only a wire
+test.
:::
## Where an event string goes
@@ -60,28 +83,53 @@ only a wire test.
Anywhere UI5 takes an event handler:
```js
-`
`
+`
`
```
The value you get back is a handler expression, not a plain name — embed it,
-do not parse or compare it. Between `c.event(…)` and the end of `main` it is in
-fact a placeholder token that is substituted for the real wire string on the
-way out; embedding is what it is for.
+do not parse or compare it. Between `client._event(…)` and the end of `main` it
+is in fact a placeholder token that is substituted for the real wire string on
+the way out; embedding is what it is for.
+
+Two more handlers go into view attributes the same way:
+
+- **`client._event_nav_app_leave()`** leaves the app — a `Page`'s
+ `navButtonPress`, with `showNavButton="${client.check_app_prev_stack()}"`.
+ `main` needs no branch for it. See [Navigation](./navigation).
+- **`client.follow_up_action({ val, t_arg })`** is a front-end action: `val` a
+ `z2ui5_if_client.cs_event` constant. Embedded in a view attribute it runs in
+ the browser, **with no roundtrip**; called on its own it runs when this
+ roundtrip's answer lands.
+
+```js
+import { defineApp, z2ui5_if_client } from "@cap2ui5/cds-plugin";
+
+// in the view: focus the search field, no roundtrip
+`` +
`` +
- ` `);
return;
}
- if (c.eventName === "GO") {
+ if (client.check_on_event("GO")) {
this.count++;
- c.messageToast(`Hi, ${this.name}! You clicked ${this.count}x.`);
+ client.message_toast_display(`Hi, ${this.name}! You clicked ${this.count}x.`);
}
}
});
```
+`client` is abap2UI5's `z2ui5_if_client`, under its ABAP method names:
+`client->check_on_navigated( )` in an ABAP app is
+`client.check_on_navigated()` here. The [Client API](../api/client) lists
+every method.
+
::: warning `import`, not `require` — in this project
`cds init --nodejs` creates an **ES module** project (`"type": "module"` in
`package.json`), so a `.js` file there must `import`. A `require("@cap2ui5/cds-plugin")`
-in it does not fail on its own line: it fails the **whole runtime boot** —
-the log says `[cap2ui5] runtime failed to boot: ReferenceError: require is not
-defined in ES module scope`, and every roundtrip, for every app, answers 500
-"roundtrip failed".
+in it fails the **start**: the plugin loads the app modules before the server
+listens, and a module that fails to load stops it, as a broken service
+implementation does. `cds watch` then never prints the app addresses, and the
+log names the file with `ReferenceError: require is not defined in ES module
+scope`. See [Troubleshooting](./troubleshooting#the-server-does-not-start-require-is-not-defined-in-es-module-scope).
In a CommonJS project (no `"type": "module"`), or in a file ending in `.cjs`,
`const { defineApp } = require("@cap2ui5/cds-plugin")` is correct and works the same way.
@@ -139,18 +145,31 @@ The examples on this site use `import`, because that is what `cds init` gives
you.
:::
+::: details Or let `cds add cap2ui5` write a first app
+`cds add cap2ui5` creates `srv/apps/hello.js` in a project that has no apps
+yet: abap2UI5's hello world, `HELLO`, with its view built by
+`z2ui5_cl_ui5_view_builder` (see [Views](./views)). Plugin 0.3.0 writes that
+file with `require`, so in a project from `cds init --nodejs` rename it to
+`hello.cjs`, or change its `require` line to
+`import { defineApp, z2ui5_cl_ui5_view_builder } from "@cap2ui5/cds-plugin";`.
+It takes the app name `HELLO`, so use it instead of the file above, not beside it.
+:::
+
Four things worth knowing, and each of them is a rule rather than a style:
-- **`main` is synchronous.** No `async`, no `await`. Make it `async` only when
- *your app* does I/O — reading your own entities with `await SELECT.from(Books)`.
-- **`c.isDisplay` is the render branch, not `c.isFirstRun`.** `isDisplay` is
- also true every time the app gets the screen back from a navigation or a
- value help. An app that renders only on `isFirstRun` works perfectly until
- something navigates back into it, and then leaves the previous screen
- standing with no error anywhere. `isFirstRun` is for seeding state once.
+- **`main` is synchronous.** No `async`, no `await` — the client's methods
+ need none. Make it `async` only when *your app* does I/O — reading your own
+ entities with `await SELECT.from(Books)`.
+- **`client.check_on_navigated()` is the render branch, not
+ `client.check_on_init()`.** `check_on_navigated()` is also true every time
+ the app gets the screen back from a navigation or a value help. An app that
+ renders only on `check_on_init()` works perfectly until something navigates
+ back into it, and then leaves the previous screen standing with no error
+ anywhere. `check_on_init()` is for seeding state once.
- **State is ordinary fields.** `name = ""` and `count = 0` are the app's
- model; `c.bind("name")` binds one into the view. They survive the roundtrip
- because the plugin stores the instance in `cap2ui5.Drafts`.
+ model; `client._bind("name")` binds one into the view — by its **name**, as
+ a string. They survive the roundtrip because the plugin stores the instance
+ in `cap2ui5.Drafts`.
- **The first argument of `defineApp` is the app's name on the wire** — it is
what `?app_start=` takes. The file name does not matter.
@@ -164,28 +183,14 @@ Once the server listens, the plugin prints every app with the address that
starts it, and the user to log in as:
```
-[cap2ui5] HELLO http://localhost:4004/sap/bc/z2ui5?app_start=HELLO
-[cap2ui5] development login: alice (empty password)
-```
-
-Open that address. Those lines are the entry point: CAP's index page at
-`http://localhost:4004/` lists the HTML files under `app/` and your CDS
-services, not this route.
-
-::: details Tip: a link to the app on CAP's index page
-The index page lists every `index.html` under `app/`, so a one-line redirect
-puts the app there. Create `app/hello/index.html`:
-
-```html
-
-
-
+
( … )`, async |
-
-## The three differences that actually bite
+| `z2ui5_if_app~main` | `main(client)` |
+| `client->check_on_init( )` | `client.check_on_init()` |
+| `client->check_on_navigated( )` | `client.check_on_navigated()` ← **render on this one** |
+| ``client->check_on_event( `GO` )`` | `client.check_on_event("GO")` |
+| `client->get_event_arg( 1 )` | `client.get_event_arg(1)` |
+| `client->_bind( name )`, `_bind( s_order-customer )` | `client._bind("name")`, `client._bind("s_order-customer")` — a **name**, not a value |
+| `client->_bind( val = t_tab path = abap_true )` | `client._bind({ val: "t_tab", path: true })` |
+| ``client->_event( val = `GO` t_arg = VALUE #( ( `x` ) ) )`` | `client._event({ val: "GO", t_arg: ["x"] })` |
+| `client->follow_up_action( val = z2ui5_if_client=>cs_event-set_title t_arg = … )` | `client.follow_up_action({ val: z2ui5_if_client.cs_event.set_title, t_arg: [ … ] })` |
+| `client->view_display( view->stringify( ) )` | `client.view_display(view.stringify())` |
+| ``client->message_box_display( text = … type = `error` )`` | `client.message_box_display({ text: …, type: "error" })` |
+| `client->nav_app_call( NEW zcl_other( ) )` | `client.nav_app_call("ZCL_OTHER")` |
+| `client->nav_app_leave( event = … r_data = … )` | `client.nav_app_leave({ event, r_data })` |
+| `client->get( )-r_event_data` | `client.get().r_event_data` |
+| `z2ui5_cl_ui5_view_builder=>factory( )->ele( … )` | `z2ui5_cl_ui5_view_builder.factory().ele(…)` |
+
+Every method of the interface is there under its name — the plugin's tests
+hold the client to the interface, so none is missing and none is invented.
+`z2ui5_if_client` and `z2ui5_cl_ui5_view_builder` are imported from
+`@cap2ui5/cds-plugin`.
+
+## What is JavaScript's own
**`_bind` takes a name, not a value.** In ABAP, `client->_bind( name )` passes
-the attribute and the framework matches it by reference. JavaScript cannot do
-that — two empty strings are indistinguishable — so the facade takes the field
-name and resolves the binding for you.
-
-**Render on `isDisplay`, not `isFirstRun`.** The same trap as in ABAP, with
-clearer names: `check_on_init( )` is this instance's first roundtrip only, and
-`check_on_navigated( )` is also every return from a navigation. The JS facade
-renames them to say which is which.
-
-**Views are XML strings.** abap2UI5's fluent builder exists in the runtime, but
-the facade does not expose it: in JavaScript a template literal is shorter than
-a chain. See [Views](./views).
-
-```abap
-client->view_display( z2ui5_cl_ui5_view_builder=>factory(
- )->ele( `Page` )->tag( `Input` )->a( ... )->stringify( ) ).
-```
-
-```js
-c.view(`
│ rebuild the app instance
│ apply the model the browser sent
- │ call your main(c)
+ │ call your main(client)
│ write a NEW draft, new id
◀──{S_FRONT:{ID:…}, actions, model}────────────┘
```
@@ -35,7 +35,7 @@ defineApp("ZCL_ORDER", class {
customer = { name: "", city: "" };
lines = t.table({ sku: "", qty: 0, price: t.packed(9, 2) });
- main(c) { /* … */ }
+ main(client) { /* … */ }
});
```
@@ -47,9 +47,9 @@ A field the plugin cannot type is **left out of the model and named in a
warning** rather than silently dropped:
```
-[defineApp] ZCL_ORDER: these fields are NOT part of the model —
- total has no ABAP type: null, undefined and an empty array carry none.
- Give it a value, or declare it with t.table(…) / t.packed(…).
+[cap2ui5] - defineApp ZCL_ORDER: these fields are NOT part of the model —
+ total has no ABAP type
+ Give an initial value, or declare it with t.table(…) / t.struct(…) / t.packed(…) / t.char(…). The app runs without them.
```
`null`, `undefined` and `[]` carry no type, so declare them: `t.table({…})` for
@@ -61,6 +61,10 @@ Anything that is not a declared field. A value stashed on `this` inside `main`
with no initializer at construction time is not part of the model and will be
gone on the next roundtrip. If you want it to survive, declare it.
+That is also what makes `this.client = client` in `main()` safe: a helper
+method reaches the client the way it does in an ABAP app, and the client is
+never persisted.
+
## It survives a restart — measured
`cold-test.mjs` is not a unit test. It starts a server, does a roundtrip,
diff --git a/docs/guide/popups.md b/docs/guide/popups.md
index 5ec4ccc..8d450fb 100644
--- a/docs/guide/popups.md
+++ b/docs/guide/popups.md
@@ -1,94 +1,131 @@
# Popups & Toasts
-Four ways to put something on the screen that is not the main view.
+Five ways to put something on the screen that is not the main view.
## Messages
```js
-c.messageToast("saved"); // transient, bottom of the screen
-c.messageBox("Hello " + this.name); // a dialog with an OK button
+client.message_toast_display("saved"); // transient, bottom of the screen
+client.message_box_display("Hello " + this.name); // a dialog with an OK button
```
Both are recorded and replayed in the order you wrote them, so two toasts arrive
-in that order.
+in that order. Their other parameters go by name, in one object with the ABAP
+names:
+
+```js
+client.message_box_display({ text: "Delete it?", type: "confirm", actions: ["DELETE", "CANCEL"],
+ emphasizedaction: "DELETE", onclose: "BOX_CLOSED" });
+client.message_toast_display({ text: "saved", duration: 5000 });
+```
+
+`text` may be data — an object or an array is laid out as abap2UI5 lays out an
+ABAP structure or table.
## A popup — a fragment on top of the view
```js
-if (c.eventName === "HELP") {
- c.popup(
+if (client.check_on_event("HELP")) {
+ client.popup_display(
`` +
`` +
` `);
return;
}
-if (c.eventName === "HELP_CLOSE") {
- c.popupClose();
+if (client.check_on_event("HELP_CLOSE")) {
+ client.popup_destroy();
return;
}
```
A popup is a **`FragmentDefinition`**, not an `mvc:View` — that is the shape UI5
-expects here. It shares the main view's model, so `c.bind()` and `c.event()`
-work inside it exactly as they do outside.
+expects here. It shares the main view's model, so `client._bind()` and
+`client._event()` work inside it exactly as they do outside.
+
+Close it with `client.popup_destroy()`. Changed bound data is pushed into an
+open popup automatically; you do not re-render it to refresh a value.
+
+## A popover — a fragment anchored to a control
+
+```js
+if (client.check_on_event("POPOVER")) {
+ client.popover_display({
+ xml: `` +
+ ` `,
+ by_id: "more", // the id of a control in the main view
+ });
+ return;
+}
+
+if (client.check_on_event("POPOVER_CLOSE")) client.popover_destroy();
+```
-Close it with `c.popupClose()`. Changed bound data is pushed into an open popup
-automatically; you do not re-render it to refresh a value.
+`by_id` names the control it opens at — here `` +
`` +
- ` `);
// later
-if (c.eventName === "DETAIL") {
- c.nest("slot",
- `` +
- ` `);
+if (client.check_on_event("DETAIL")) {
+ client.nest_view_display({
+ val: `` +
+ ` `,
+ id: "slot",
+ method_insert: "addContent",
+ method_destroy: "removeAllContent",
+ });
return;
}
-if (c.eventName === "DETAIL_HIDE") c.nestClose();
+if (client.check_on_event("DETAIL_HIDE")) client.nest_view_destroy();
```
-The main view stays as it is; only the fragment re-renders on the next `nest`.
+The main view stays as it is; only the nested view re-renders on the next
+`nest_view_display`.
-`c.nest(into, xml, opts)` takes the receiving control's `id`, and `opts` names
-the UI5 mutators for its aggregation:
+`id` is the receiving control's `id`, and the other two parameters name the UI5
+mutators for its aggregation — there are no defaults:
-| | default | when to change it |
-|---|---|---|
-| `insert` | `addContent` | `addItem` for a `List`, etc. |
-| `clear` | `removeAllContent` | `removeAllItems` for a `List` |
+| | required | for a `Page` or `VBox` | for a `List` |
+|---|---|---|---|
+| `method_insert` | yes | `addContent` | `addItem` |
+| `method_destroy` | no | `removeAllContent` | `removeAllItems` |
-**Without `clear`, every call adds one more fragment.** The defaults fit a
-`Page` or a `VBox`.
+**Without `method_destroy`, nothing is cleared first, and every call adds one
+more view.**
-There is exactly **one** nested slot, and `c.nestClose()` takes no argument: it
-clears that slot rather than a named one.
+There are **two** nested slots: `nest2_view_display({ val, id, method_insert,
+method_destroy })` and `nest2_view_destroy()` are the second, with the same
+contract. Each `*_destroy()` takes no argument: it clears its slot.
## Which one do I want?
| | |
|---|---|
-| a short confirmation | `messageToast` |
-| something the user must acknowledge | `messageBox` |
-| a modal that takes input or a decision | `popup` |
-| a region of the page that updates independently | `nest` |
+| a short confirmation | `message_toast_display` |
+| something the user must acknowledge | `message_box_display` |
+| a modal that takes input or a decision | `popup_display` |
+| a few details next to the control that asked | `popover_display` |
+| a region of the page that updates independently | `nest_view_display` |
| a whole second screen with its own state | [navigation](./navigation) — a separate app |
## Next
- [**Navigation**](./navigation) — when a popup is really another app
- [**Events**](./events) — the handlers the buttons above use
+- [**Client API**](../api/client) — every parameter of these methods
diff --git a/docs/guide/project-structure.md b/docs/guide/project-structure.md
index 691b731..46cc143 100644
--- a/docs/guide/project-structure.md
+++ b/docs/guide/project-structure.md
@@ -40,9 +40,16 @@ vendored folder, no sync pipeline. Upgrading is `npm update @cap2ui5/cds-plugin`
## `srv/apps/` — the one directory that is yours
-Every `.js`, `.mjs` or `.cjs` file in it is loaded once the runtime is up. A
-file is not special in any way: it just calls `defineApp`, and it may call it
-more than once.
+Every `.js`, `.mjs` or `.cjs` file in it is loaded once the runtime is up and
+CAP has served the model, so an app module may call `cds.entities()` at its
+top. A file is not special in any way: it just calls `defineApp`, and it may
+call it more than once. A module that fails to load fails the start, as a
+service implementation does.
+
+`cds add cap2ui5` creates a first one, `srv/apps/hello.js`, when the directory
+has none. In 0.3.0 that file uses `require`, so in an ES module project — what
+`cds init --nodejs` creates — rename it to `hello.cjs`, or change its first
+line to `import { defineApp, z2ui5_cl_ui5_view_builder } from "@cap2ui5/cds-plugin";`.
```js
// srv/apps/pick.js — two apps in one file is fine
@@ -53,12 +60,12 @@ defineApp("ZCL_PICK_ONE", class { /* … */ });
```
The **first argument to `defineApp` is the name on the wire** — what
-`?app_start=` takes and what `c.navTo()` resolves. The file name is irrelevant.
+`?app_start=` takes and what `client.nav_app_call()` resolves. The file name is irrelevant.
To put apps somewhere else, point the plugin at it:
```json
-{ "cds": { "cap2ui5": { "apps": "srv/my-apps" } } }
+{ "cds": { "requires": { "cap2ui5": { "apps": "srv/my-apps" } } } }
```
See [Configuration](../reference/configuration) for the rest of the knobs.
@@ -98,7 +105,7 @@ In `node_modules`, in two packages, and you own neither:
| | |
|---|---|
| `@cap2ui5/cds-plugin` | the plugin — about 1,050 lines in 0.1.0, of which about 640 are code. `cds-plugin.js`, `index.cds`, `index.js`, `lib/` |
-| `@abap2ui5/node-runtime` | abap2UI5 itself: upstream's ABAP, downported and transpiled over open-abap, with the UI5 frontend embedded in the page its GET answers with. the plugin pins one exact release |
+| `@abap2ui5/node-runtime` | abap2UI5 itself: upstream's ABAP, downported and transpiled over open-abap, with the UI5 frontend embedded in the page its GET answers with. The plugin pins one exact release |
That split is the whole design. The plugin is a **host**: it mounts a route,
implements the draft store over a CDS entity, and turns a JavaScript class into
diff --git a/docs/guide/roadmap.md b/docs/guide/roadmap.md
index 273ea8a..316e72b 100644
--- a/docs/guide/roadmap.md
+++ b/docs/guide/roadmap.md
@@ -16,6 +16,15 @@ limitation this page used to carry — and it retired the pipelines, the vendore
core and 82,804 lines of generated code with it. The reasoning and the
measurements are in [Where cap2UI5 Comes From](./where-it-comes-from).
+Since then the JavaScript side closed its own gaps. 0.2.0 made the client an
+app receives abap2UI5's `z2ui5_if_client`, every method under its ABAP name,
+exported `z2ui5_cl_ui5_view_builder` and shipped TypeScript declarations;
+0.3.0 added `npx cap2ui5 abap2js`, which translates an abap2UI5 app class
+into a cap2UI5 app line for line, and apps that come from a package —
+[`@cap2ui5/samples`](https://github.com/cap2UI5/samples) is 71 of abap2UI5's
+samples that way. The details are in the plugin's
+[CHANGELOG](https://github.com/cap2UI5/cap2UI5/blob/main/plugin/CHANGELOG.md).
+
## Known limits today
### Behind an approuter, the roundtrip path needs its own route
@@ -28,20 +37,22 @@ is refused with `403` until the roundtrip path gets a route of its own with
abap2UI5/abap2UI5#2802 teaches the frontend the token handshake; it is merged,
but no abap2UI5 release carries it yet.
-### The facade does not cover everything
+### The apps are JavaScript, and so are the errors
-`c` covers views, popups, nested views, navigation, messages, event arguments
-and nested state. Everything else lives behind `c.raw`, which is the full
-`z2ui5_if_client` — async, and under its original ABAP names. That is a real
-escape hatch rather than a placeholder, but a method used often enough deserves
-a facade member.
+A mistyped field name throws at runtime, not at edit time:
+`client._bind("nmae")` names the app's known fields, and an untypeable field
+is named in a warning. The package ships TypeScript declarations, so an
+annotated client —
+`/** @param {import("@cap2ui5/cds-plugin").Client<{ name: string }>} client */`
+— gets completion and checked field names in the editor; nothing checks an
+unannotated app.
-### The apps are JavaScript, and so are the errors
+### `abap2js` translates part of ABAP
-A mistyped field name throws at runtime, not at edit time. `c.bind("nmae")`
-tells you the known fields, and an untypeable field is named in a warning — but
-there is no type checking across your app, and the TypeScript story is
-unwritten.
+`npx cap2ui5 abap2js` knows the ABAP an abap2UI5 app is written in and
+refuses the rest — a field-symbol, `SELECT`, a `sy-` field — with file, row
+and column. What it refuses you translate by hand. Of abap2UI5's 129
+samples, it translates 69 today.
### UI5 comes from the CDN, and only from the CDN
@@ -69,18 +80,16 @@ background pages may still carry the port's mechanics; if a page contradicts
upstream release, pin the plugin to it, and the route CAP generates works
unchanged.
-**Grow the facade where use shows it is needed** — driven by real apps rather
-than by completing a table.
+**Teach `abap2js` more ABAP.** Some of its refusals say "not supported yet".
-**Finish this documentation**, including a page on writing an app against
-`c.raw` when the facade does not reach.
+**Finish this documentation.**
## What is deliberately not planned
-**A cap2UI5 view builder.** Views are UI5 XML strings; a template literal is
-shorter and clearer than a fluent chain in JavaScript. abap2UI5's builder runs
-in the runtime, and an app written in ABAP can use it — see
-[The ABAP view builder](./views#the-abap-view-builder).
+**A view builder of cap2UI5's own.** The builder a JavaScript app uses is
+abap2UI5's `z2ui5_cl_ui5_view_builder`, rendered by the transpiled class in
+the runtime — see [The view builder](./views#the-view-builder). A UI5 XML
+string in a template literal works as well.
**A second implementation of anything upstream owns.** The whole point of the
current design is that there is one implementation of the framework. A feature
diff --git a/docs/guide/troubleshooting.md b/docs/guide/troubleshooting.md
index 952f225..c0003df 100644
--- a/docs/guide/troubleshooting.md
+++ b/docs/guide/troubleshooting.md
@@ -42,13 +42,13 @@ Another `cds watch` still runs, usually in a different terminal. Stop it with
That is expected: the route requires a user, and `cds watch` uses CAP's
mocked authentication. Log in as **`alice` with an empty password** — the
-startup line names it: `[cap2ui5] development login: alice (empty password)`.
+startup line names it: `[cap2ui5] - development login: alice (empty password)`.
Only cancelling the dialog is refused, with a `401`, and the next attempt asks
again.
Mocked authentication lets other names in as well, but a draft belongs to the
user who created it — log in as someone else and a running session starts
-over. The details are under *401 on the roundtrip* below.
+over. The details are under *401 or 403 on the roundtrip* below.
## "App with name X not found"
@@ -58,12 +58,12 @@ Apps are registered by **`defineApp`**, not found by file name:
`defineApp("ZCL_HELLO", …)` is started with `?app_start=ZCL_HELLO`. The file
name is irrelevant, and one file may register several apps.
2. **The file must be in the scanned directory** — `srv/apps` by default, or
- whatever `cds.cap2ui5.apps` points at. Every `.js`, `.mjs` and `.cjs` in it
+ whatever `cds.requires.cap2ui5.apps` points at. Every `.js`, `.mjs` and `.cjs` in it
is imported once the runtime is up.
3. **The plugin says how many it loaded.** On startup:
```
- [cap2ui5] 5 app module(s) loaded from srv/apps
+ [cap2ui5] - 5 app module(s) loaded from srv/apps
```
A count of `0`, or no line at all, is a path problem rather than a code
@@ -73,24 +73,27 @@ Apps are registered by **`defineApp`**, not found by file name:
`main( client )` method throws at registration, and the message names the
app.
-`c.navTo()` on an unknown name is refused where you called it, listing what is
-registered — rather than failing later as `NAV_APP_TARGET_NOT_BOUND`.
+`client.nav_app_call()` with a name no app is registered under is refused
+where you called it — rather than failing later as `NAV_APP_TARGET_NOT_BOUND`.
-## Every roundtrip answers 500 "roundtrip failed"
+## The server does not start: `require is not defined in ES module scope`
-For every app, from the first click — look at the server log above the
-startup lines:
+`cds watch` stops before it listens, and the error names an app file:
```
-[cap2ui5] runtime failed to boot: ReferenceError: require is not defined in ES module scope, you can use import instead
+ReferenceError: require is not defined in ES module scope, you can use import instead
```
The project is an **ES module project** (`"type": "module"` in
`package.json`, which is what `cds init --nodejs` creates), and an app file in
-it uses `require("@cap2ui5/cds-plugin")`. The plugin imports the apps as part of booting
-the runtime, so one such file fails the boot, and the route has nothing to
-answer with. Write `import { defineApp } from "@cap2ui5/cds-plugin"` instead — or rename
-the file to `.cjs`, where `require` stays valid.
+it uses `require("@cap2ui5/cds-plugin")`. The plugin loads the apps before the
+server listens, and an app module that fails to load fails the start — as a
+service implementation does. Write
+`import { defineApp } from "@cap2ui5/cds-plugin"` instead, or rename the file
+to `.cjs`, where `require` stays valid.
+
+The same holds for any other error an app module throws while it loads: the
+start fails and the log names the module.
## The draft cannot be restored
@@ -159,16 +162,21 @@ absent in 1.71 and UI5 renders nothing rather than complaining.
exactly like nothing happening. **Roundtrips → Response** shows whether a
view came back.
-## 401 on the roundtrip
+## 401 or 403 on the roundtrip
-The route requires an authenticated user by default — `cds.cap2ui5.requires` is
-`"authenticated-user"`. In development CAP's mocked auth applies, so any
+**401** means the caller is not logged in. The route requires an authenticated
+user by default — `cds.requires.cap2ui5.roles` is `["authenticated-user"]`. In development CAP's mocked auth applies, so any
configured user works (`alice` with an empty password in a stock project). In
BTP the approuter must forward the token (`HTML5.ForwardAuthToken`).
+**403** from the plugin means the user is logged in but has none of the roles
+in `cds.requires.cap2ui5.roles`; the error names the roles. (A 403 that carries
+`x-csrf-token: Required` comes from the approuter instead — see the next
+section.)
+
The decision happens **before** the body is read, so an unauthenticated POST is
refused without the payload being buffered. To open the route deliberately, set
-`requires` to `null` — and read what that costs in
+`roles` to `any` — and read what that costs in
[Configuration](../reference/configuration).
## 403 on the roundtrip behind the approuter
@@ -182,14 +190,14 @@ is safe, are in [Deployment](../reference/deployment#the-approuter-needs-one-ext
## Two users see each other's state
-Almost always one cause: **`cds.cap2ui5.requires` is `null`.** Every caller is
+Almost always one cause: **`cds.requires.cap2ui5.roles` is `any` or `null`.** Every caller is
then CAP's anonymous user, and the draft store binds a session to
`cds.context.user.id` — so all anonymous visitors share one owner and therefore
each other's sessions. That is the documented consequence of turning
authentication off, not a defect.
With authentication on, a draft answers to its creator and to nobody else. If
-you see otherwise with `requires` set, that is a bug worth reporting — check
+you see otherwise with `roles` set, that is a bug worth reporting — check
the `owner` column of `cap2ui5.Drafts` first:
```sql
diff --git a/docs/guide/user-exit.md b/docs/guide/user-exit.md
index 85b8852..bdd74c4 100644
--- a/docs/guide/user-exit.md
+++ b/docs/guide/user-exit.md
@@ -199,7 +199,7 @@ messages carry entity names, SQL fragments and deployment paths.
App state belongs on the app instance; see [App Lifecycle](./lifecycle).
- **Not a request filter.** It shapes config, it does not accept or reject
requests. Authentication and authorisation belong on the CAP service
- (`@requires`, `@restrict`) and on `cds.cap2ui5.requires` — see
+ (`@requires`, `@restrict`) and on `cds.requires.cap2ui5.roles` — see
[Deployment](../reference/deployment).
- **Not a place for per-user secrets.** The object is registered once and
shared by every request in the process; only the context argument is per
diff --git a/docs/guide/views.md b/docs/guide/views.md
index 9c608c7..9a26697 100644
--- a/docs/guide/views.md
+++ b/docs/guide/views.md
@@ -1,28 +1,32 @@
# Views
-A view is **UI5 XML, as a string**, handed to `c.view()`.
+A view is **UI5 XML, as a string**, handed to `client.view_display()`.
```js
-c.view(
+client.view_display(
`` +
`` +
- ` `);
```
-That is the whole API. There is no builder to learn, no control catalogue to
-wait for, and nothing between you and UI5: anything you can write in a UI5 XML
-view, you can write here, including controls the framework has never heard of.
+There is no control catalogue to wait for, and nothing between you and UI5:
+anything you can write in a UI5 XML view, you can write here, including
+controls the framework has never heard of. abap2UI5's own view builder is
+there as well, for a view built the way an ABAP app builds one — see
+[The view builder](#the-view-builder).
## The two holes you fill
| | |
|---|---|
-| `${c.bind("field")}` | a binding path to one of your fields |
-| `${c.event("NAME")}` | a handler expression; `["arg"]` as a second parameter travels with it |
+| `${client._bind("field")}` | a binding path to one of your fields |
+| `${client._event("NAME")}` | a handler expression; `client._event({ val: "NAME", t_arg: ["arg"] })` sends arguments with it |
-Everything else is plain UI5.
+Everything else is plain UI5. What `_event()` — and a `_bind()` with options —
+returns is a placeholder that becomes the real expression after `main()`:
+embed it as it is, and do not cut or rebuild it.
## The shape
@@ -42,8 +46,8 @@ The view is a string, so composing it is ordinary JavaScript:
```js
const column = (t) => `` +
+client.view_display(
+ `` +
`${["Title", "Author", "Price"].map(column).join("")} ` +
`` +
`` +
`` +
- ` `);
return;
}
- if (c.eventName === "GO") {
+ if (client.check_on_event("GO")) {
// the button was clicked; this.name already holds what the user typed
- c.messageBox(`Hello, ${this.name}!`);
+ client.message_box_display(`Hello, ${this.name}!`);
}
}
});
```
That is the whole app. No `manifest.json`, no `Component.js`, no controller
-file, no i18n setup. The class fields are your state, `main(c)` is your logic,
-and the view is UI5 XML with two holes in it: `c.bind()` for a field and
-`c.event()` for a handler.
-
-::: tip Render on `isDisplay`
-`c.isDisplay` is true on the first roundtrip **and** whenever the app gets the
-screen back — from a called app, a value help, a restored bookmark. Rendering
-only on `c.isFirstRun` produces an app that silently shows its previous screen
-after a navigation. See [App Lifecycle](./lifecycle).
+file, no i18n setup. The class fields are your state, `main(client)` is your
+logic, and the view is UI5 XML with two holes in it: `client._bind()` for a
+field and `client._event()` for a handler. abap2UI5's view builder,
+`z2ui5_cl_ui5_view_builder`, is there too, for a view built as an ABAP app
+builds one — see [Views](./views).
+
+::: tip Render on `check_on_navigated()`
+`client.check_on_navigated()` is true on the first roundtrip **and** whenever
+the app gets the screen back — from a called app, a value help, a restored
+bookmark. Rendering only on `client.check_on_init()` produces an app that
+silently shows its previous screen after a navigation. See
+[App Lifecycle](./lifecycle).
:::
::: tip About the names
-`ZCL_HELLO`, and `z2ui5_if_client` behind `c.raw` — the framework running under
-the plugin *is* ABAP, so its identifiers are ABAP's. The facade renames the
-handful you meet daily (`c.isDisplay`, `c.bind`, `c.event`); everything else
-keeps its original name, which is what lets every abap2UI5 sample and document
-still map onto what you are doing.
+`ZCL_HELLO`, `check_on_navigated`, `_bind` — the framework running under the
+plugin *is* ABAP, and `client` is its `z2ui5_if_client`, under the interface's
+own method names: `client->check_on_navigated( )` in ABAP is
+`client.check_on_navigated()` here. That is what lets every abap2UI5 sample
+and document map onto what you are doing — an ABAP app ports line by line.
+The full list is the [Client API](../api/client).
:::
## The gap this closes {#the-gap}
diff --git a/docs/guide/where-it-comes-from.md b/docs/guide/where-it-comes-from.md
index e1a1f9a..96d2495 100644
--- a/docs/guide/where-it-comes-from.md
+++ b/docs/guide/where-it-comes-from.md
@@ -53,7 +53,7 @@ abap2UI5 (the real ABAP sources)
@abap2ui5/node-runtime the backend AND the UI5 frontend, one package, one commit
│
▼
-cap2ui5 (this plugin) mounts the route, implements the draft store over a
+@cap2ui5/cds-plugin mounts the route, implements the draft store over a
CDS entity, turns a JS class into something the
runtime can call — and contains no framework logic
```
@@ -96,10 +96,13 @@ archived. Nothing consumes their output any more: `@cap2ui5/cds-plugin` depends
## Why the ABAP names remain
`ZCL_HELLO`, `z2ui5_if_client`, `check_on_init` — the runtime *is* ABAP, so its
-identifiers are ABAP's. The plugin's facade renames the handful an app author
-meets every day (`c.isDisplay`, `c.bind`, `c.event`), and `c.raw` reaches the
-rest under their original names. Every abap2UI5 sample and document therefore
-still maps onto what you are doing.
+identifiers are ABAP's. The plugin keeps them: the client an app's
+`main( client )` receives is `z2ui5_if_client` under its own method names —
+`client->check_on_navigated( )` is `client.check_on_navigated()` — and the
+view builder is `z2ui5_cl_ui5_view_builder`. Every abap2UI5 sample and
+document therefore maps onto what you are doing, and an ABAP app ports line
+by line; `npx cap2ui5 abap2js` does the porting (see
+[Migrating from abap2UI5](./migration-from-abap2ui5#translate-it-npx-cap2ui5-abap2js)).
## Next
diff --git a/docs/guide/why-cap2ui5.md b/docs/guide/why-cap2ui5.md
index 93f3258..46a27f9 100644
--- a/docs/guide/why-cap2ui5.md
+++ b/docs/guide/why-cap2ui5.md
@@ -39,7 +39,7 @@ With cap2UI5 the structure shrinks to:
```
my-cap-project/
-├── package.json # ← + 1 dependency: cap2ui5
+├── package.json # ← + 1 dependency: @cap2ui5/cds-plugin
└── srv/
└── apps/
└── my_app.js # ← your app. One file.
@@ -60,7 +60,7 @@ You spend the entire time in **JavaScript** (or TypeScript, if you prefer). No X
```bash
cds watch
# → CAP server runs on :4004, and the plugin prints each app's address:
-# → [cap2ui5] ZCL_MY_APP http://localhost:4004/sap/bc/z2ui5?app_start=ZCL_MY_APP → open it, done
+# → [cap2ui5] - ZCL_MY_APP http://localhost:4004/sap/bc/z2ui5?app_start=ZCL_MY_APP → open it, done
```
### 2. Server state = app state
@@ -68,30 +68,30 @@ cds watch
A cap2UI5 app is a **class with fields**. These fields are your state:
```js
-class CustomerEdit extends z2ui5_if_app {
+defineApp("ZCL_CUSTOMER_EDIT", class {
customer_id = "";
- customer_data = {};
+ customer_data = { name: "", email: "" };
is_dirty = false;
validation = { name: "None", email: "None" };
- async main(c) { /* ... */ }
-}
+ async main(client) { /* ... */ }
+});
```
-After every roundtrip the entire instance is **persisted automatically in the CDS entity `cap2ui5.Drafts`**. On the next roundtrip it is rebuilt, the browser's model is applied, and `main(c)` runs again. You don't need to manage a JSONModel, write a reducer, or build a "service worker" for offline state — the server holds everything.
+After every roundtrip the entire instance is **persisted automatically in the CDS entity `cap2ui5.Drafts`**. On the next roundtrip it is rebuilt, the browser's model is applied, and `main(client)` runs again. You don't need to manage a JSONModel, write a reducer, or build a "service worker" for offline state — the server holds everything.
### 3. Bindings without a model
This is the core pattern that makes cap2UI5 (and abap2UI5) lightweight code in the first place:
```js
-`)`.
The detail goes to the server log under the same id; see
-[Configuration](./configuration).
+[Configuration](./configuration). An app module that fails to load does not
+get that far: it fails the server's start.
Authentication is decided **before** the body is read: an unauthenticated
-caller gets `401` without the server buffering the payload.
+caller gets `401` with the auth strategy's login challenge, an authenticated
+user who lacks the configured role `403`, both without the server buffering
+the payload. A body over the limit gets `413`. These three are answered by
+CAP's error middleware, in CAP's error format.
## Next
diff --git a/scripts/verify-refs.mjs b/scripts/verify-refs.mjs
index ae14b2a..954139e 100644
--- a/scripts/verify-refs.mjs
+++ b/scripts/verify-refs.mjs
@@ -56,7 +56,7 @@
* lands on a file that exists. Two dead packages are reported by name,
* in either form: "abap2UI5/…", the port's package, and "cap2ui5", the
* plugin's name up to 0.2.0, withdrawn from npm.
- * 5. every plugin option named as `cds.cap2ui5.` is a key the plugin
+ * 5. every plugin option named as `cds.requires.cap2ui5.` is a key the plugin
* really defines, every three-part release number (1.x.y) is the runtime
* release the checkout pins or an allowlisted historical number, and a
* `"@cap2ui5/cds-plugin": "^x.y.z"` a page tells a reader to write is a
@@ -159,12 +159,17 @@ const PLUGIN_EXPORTS = (() => {
return inner ? new Set(inner[1].split(",").map((s) => s.trim()).filter(Boolean)) : null;
})();
-/** the plugin's own configuration keys, from package.json#cds.cap2ui5 */
+/** the plugin's own configuration keys, from package.json#cds.requires.cap2ui5
+ * (where they live since 0.2.0). `model` there is CAP's own key - the entry's
+ * CDS model - and not a setting of the plugin. Keys the plugin reads without a
+ * default in package.json (body_parser) are in .verify-refs-ignore. */
const PLUGIN_OPTIONS = (() => {
if (!haveApp) return null;
try {
const pkg = JSON.parse(fs.readFileSync(path.join(APP, "plugin", "package.json"), "utf8"));
- return new Set(Object.keys(pkg.cds?.cap2ui5 ?? {}));
+ const own = pkg.cds?.requires?.cap2ui5;
+ if (!own || typeof own !== "object") return null;
+ return new Set(Object.keys(own).filter((k) => k !== "model"));
} catch { return null; }
})();
@@ -276,10 +281,12 @@ const DESTRUCTURE_RE = /(?:const|let|var)\s*\{([^}]*)\}\s*=\s*require\(\s*["'`]@
// a file.
const IMPORT_RE = /\bimport\s+(?:[^"'`;]*?\s+from\s+)?["'`](@cap2ui5\/cds-plugin|cap2ui5|abap2UI5)(?:\/([^"'`]+))?["'`]/gi;
const IMPORT_NAMES_RE = /\bimport\s*\{([^}]*)\}\s*from\s*["'`]@cap2ui5\/cds-plugin["'`]/g;
-// `cds.cap2ui5.apps`, `cap2ui5.routes` in prose or a config block. Case
-// matters and the flag is deliberately absent: `cap2ui5.Drafts` is the CDS
-// ENTITY, which the docs name constantly and which is not an option at all.
-const OPTION_RE = /`(?:cds\.)?cap2ui5\.([a-z][a-z_]*)`/g;
+// `cds.requires.cap2ui5.apps`, `cap2ui5.routes` in prose or a config block.
+// Case matters and the flag is deliberately absent: `cap2ui5.Drafts` is the
+// CDS ENTITY, which the docs name constantly and which is not an option at all.
+// `cds.cap2ui5.` is 0.1.0's place - still read, with a deprecation
+// warning - so it is reported as the old place rather than checked.
+const OPTION_RE = /`(cds\.(?:requires\.)?)?cap2ui5\.([a-z][a-z_]*)`/g;
// which app ids a PAGE defines itself: a page teaching an app may name it
const DEFINES_RE = /defineApp\(\s*["'`]([A-Za-z0-9_]+)["'`]/g;
@@ -392,10 +399,15 @@ for (const file of markdownFiles(DOCS)) {
for (const m of line.matchAll(OPTION_RE)) {
if (!PLUGIN_OPTIONS) continue;
- const key = m[1].toLowerCase();
+ if (m[1] === "cds.") {
+ add(file, n, `cds.cap2ui5.${m[2]} is 0.1.0's place, deprecated - `
+ + `the settings are under cds.requires.cap2ui5`);
+ continue;
+ }
+ const key = m[2].toLowerCase();
if (PLUGIN_OPTIONS.has(key) || IGNORE.has(`cap2ui5.${key}`)) continue;
- add(file, n, `cap2ui5.${m[1]} is not a plugin option `
- + `(package.json#cds.cap2ui5 defines ${[...PLUGIN_OPTIONS].join(", ")})`);
+ add(file, n, `cap2ui5.${m[2]} is not a plugin option `
+ + `(package.json#cds.requires.cap2ui5 defines ${[...PLUGIN_OPTIONS].join(", ")})`);
}
for (const m of line.matchAll(CLASS_RE)) {