From b5d6a97ac4970c9b2ce7209a1109805565462896 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 20 Sep 2026 18:49:06 +0000 Subject: [PATCH 1/6] docs: the two entry pages describe the plugin, because the trigger has fired MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit §22 said these pages were correct today and would be wrong on merge day, and that the trigger was step 4.3 rather than my having the knowledge in hand. That day is today: cap2UI5/cap2UI5@main has carried the plugin since 13:17 UTC, so the published site now documents a product that does not exist. Starting where a reader starts. The landing page and the quickstart, rewritten against the plugin as merged - not against my memory of it: index.md npm i cap2ui5 rather than "clone the repo"; cap2ui5.Drafts rather than z2ui5_t_01; upstream's runtime rather than an ABAP->JS pipeline of ours. The "Try it in the browser" button is gone: it pointed at web-cap2UI5-build, which is archived as of today, and a dead button on a landing page is worse than no button. getting-started defineApp + c.bind/c.event/c.isDisplay rather than `class x extends z2ui5_if_app` + client.view_display; one file in srv/apps/ rather than a cloned CAP project; reading your own entities with cds.ql, which is the point of running inside CAP. TWO THINGS I GOT WRONG AND MEASURED BEFORE PUBLISHING. `npm add cap2ui5` answers 404 - neither cap2ui5 nor @abap2ui5/runtime is published yet, both wait on a release. The page keeps the command as what you WILL run and carries a danger box saying it is the one line that does not work today, with the repository route that does. And the start URL was wrong. I had written /z2ui5/webapp/index.html?app_start=..., which answers 200 and 950 bytes - the shell's own index. The entry point is the ROUNDTRIP ROUTE: /rest/root/z2ui5?app_start=..., 346 KB, the composed page that boots UI5 and starts the app. Measured against the running example, and it is what browser.e2e.mjs opens - the test that actually renders in CI. A third one the build caught: `Owner-scoped: a draft ...` in the landing page's frontmatter is a colon in an unquoted YAML scalar, and vitepress refused the whole file. Every details block is a >- scalar now, which retires the class. `npm run docs:build` green. 34 of 36 pages still describe the port; the audit splitting them is in HANDOVER.md and unchanged. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01JoANwtaK8Jm9srGEqSxmUF --- docs/guide/getting-started.md | 232 +++++++++++++++++++--------------- docs/index.md | 56 +++++--- package-lock.json | 4 + 3 files changed, 168 insertions(+), 124 deletions(-) diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md index fd8ccbc..65cec05 100644 --- a/docs/guide/getting-started.md +++ b/docs/guide/getting-started.md @@ -1,159 +1,183 @@ # Quickstart -This page takes you from "empty directory" to "clickable cap2UI5 app" in under five minutes. - -::: tip No installation at all? -If you just want to *see* cap2UI5 first, open the [**browser playground**](./playground) — the whole stack, including all sample apps, runs on GitHub Pages. -::: +From an empty directory to a clickable cap2UI5 app. cap2UI5 is a **CAP plugin**: +you add it to a CAP project you already have, or to a brand new one. There is +no cap2UI5 project to clone. ## Prerequisites -- **Node.js ≥ 22** (the app declares it in `engines` and `.nvmrc`) -- Internet access (the frontend loads SAPUI5 from the SAP CDN) +- **Node.js ≥ 22** +- A CAP project (`cds init` makes one in seconds) +- Internet access — the frontend loads SAPUI5 from the SAP CDN -That's it. No database setup (CAP starts an in-memory SQLite automatically), no global CLI installs (`@sap/cds-dk` is a dev dependency of the project). +No database setup: CAP starts SQLite for you. No global installs. -## 1. Clone the project +## 1. A CAP project -Clone the reference project — the repo root **is** the CAP application: +Skip this if you already have one. ```bash -git clone https://github.com/cap2UI5/cap2UI5.git -cd cap2UI5 -npm install +npm init -y && npm add @sap/cds @cap-js/sqlite +npx cds init ``` -The repository is a complete, self-contained CAP project: +## 2. Add the plugin +```bash +npm add cap2ui5 ``` -cap2UI5/ -├── srv/ -│ ├── z2ui5-service.cds # service definitions incl. the z2ui5 action -│ ├── z2ui5-service.js # service handler bindings -│ ├── server.js # CAP bootstrap (HTML + CSRF endpoints) -│ └── app/ # your own apps go here -├── db/ -│ └── schema.cds # CDS entity z2ui5_t_01 for persistence -├── app/ -│ └── z2ui5/ # static UI5 frontend (don't touch) -├── core/ # vendored framework package (don't touch) -│ └── srv/app/samples/ # ~105 demo apps (from abap2UI5/samples) -└── package.json # "abap2UI5": "file:./core" -``` -## 2. Start +That is the whole installation. On the next `cds watch` three things exist that +did not before: + +| | | +|---|---| +| the roundtrip route | `/sap/bc/z2ui5` and `/rest/root/z2ui5` | +| the UI5 shell | `/z2ui5/webapp/` — served from the runtime package, not copied into your project | +| `cap2ui5.Drafts` | a CDS entity for session state, created by `cds deploy` next to your own | + +Your own `server.js`, if you have one, is not touched. Nothing is generated +into your repository. + +::: danger Neither package is on npm yet — the one step that does not work as written +`npm add cap2ui5` answers **404** today, and so would `@abap2ui5/runtime`, which +the plugin depends on. Both are published from a release that has not been cut +yet. Verified while writing this page, so that the line above is what you *will* +run and not what you can run now. + +Until then, work from the repository — `examples/bookshop` in it is a complete +CAP project using the plugin: ```bash -npx cds watch -# or: start and open the app in the browser right away -npm run watch-z2ui5 -``` +git clone https://github.com/cap2UI5/cap2UI5 && cd cap2UI5 -The server listens on [http://localhost:4004](http://localhost:4004): +# fill runtime/ from an upstream build (once, ~3 minutes) +git clone https://github.com/abap2UI5/abap2UI5 /tmp/ref +(cd /tmp/ref && npm ci && npm run deps && npm run auto_downport && npm run auto_transpile) +scripts/assemble-runtime.sh /tmp/ref -| URL | What you get | -|---|---| -| [`/z2ui5/webapp/index.html`](http://localhost:4004/z2ui5/webapp/index.html) | the app — without a parameter, the startup launcher is shown | -| [`/z2ui5/webapp/index.html?app_start=z2ui5_cl_ui5_app_hi_world`](http://localhost:4004/z2ui5/webapp/index.html?app_start=z2ui5_cl_ui5_app_hi_world) | start a specific app class directly — works for every sample, e.g. `z2ui5_cl_smp_app_000` | -| `/rest/root/z2ui5` | the roundtrip endpoint the frontend talks to | +npm install && npm start +``` -Click around the demo apps first — everything you see in `core/srv/app/samples/` can be started via `?app_start=`. +The workspace links `plugin/` into the example, so `require("cap2ui5")` resolves +exactly as it will from npm. Everything below this box is accurate today — only +the `npm add` line waits on the release. +::: -## 3. Your first own app +## 3. Your first app -Create a new file `my_first_app.js` in `srv/app/`: +One file in `srv/apps/` — the directory the plugin scans: ```js -// srv/app/my_first_app.js -const z2ui5_if_app = require("abap2UI5/z2ui5_if_app"); -const z2ui5_cl_ui5_view_builder = require("abap2UI5/z2ui5_cl_ui5_view_builder"); - -class my_first_app extends z2ui5_if_app { +// srv/apps/hello.js +const { defineApp } = require("cap2ui5"); - who = "World"; +defineApp("ZCL_HELLO", class { + name = ""; count = 0; - async main(client) { - - if (client.check_on_init()) { - this.render(client); + main(c) { + if (c.isDisplay) { + c.view( + `` + + `` + + `` + + `` + + `