From bc00b0c5df1017b4976b58a02eb756c83724dd0b Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 17 Aug 2026 04:31:40 +0000 Subject: [PATCH] Say which of the three sample catalogues answers which question 615 working apps live in three repositories, and until now the only way to find out which one to open was to know all three existed. The cookbook links individual samples per chapter (link-samples.mjs), which answers "show me one for THIS page" - not "where do I look". samples 152 has somebody already built this PATTERN samples-controls 431 how is this CONTROL expressed in ABAP samples-stack 32 how do I reach my SYSTEM from an app Picking the wrong one costs more time than reading the page, so the table says it in one line each, with the rule of thumb underneath: samples if you are learning, samples-controls if you already know the control, samples-stack only when the app has to talk to something in the system. The rest of the page is the part a reader cannot see from the catalogues themselves: that all three pages have the SAME row shape, that the title, the sentence and the search terms all live ON THE CLASS rather than on the page, and that each repository refuses a sample missing one of them - which is why a catalogue can never describe a sample differently from the class it links to. Plus the two lines an agent needs (`examples` searches all three at once, `capabilities` answers the neighbouring question) and how to start one in a system. The nav's Links block listed `samples` alone; it now names all three. --- docs/.vitepress/config.mjs | 13 +++++++ docs/resources/samples.md | 79 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 92 insertions(+) create mode 100644 docs/resources/samples.md diff --git a/docs/.vitepress/config.mjs b/docs/.vitepress/config.mjs index a6136af8..746aa19a 100644 --- a/docs/.vitepress/config.mjs +++ b/docs/.vitepress/config.mjs @@ -79,6 +79,14 @@ export default defineConfig({ }, { text: "addons", link: "https://github.com/abap2UI5-addons" }, { text: "samples", link: "https://github.com/abap2UI5/samples" }, + { + text: "samples-controls", + link: "https://github.com/abap2UI5/samples-controls", + }, + { + text: "samples-stack", + link: "https://github.com/abap2UI5/samples-stack", + }, { text: "docs", link: "https://github.com/abap2UI5/docs" }, { text: "issues", @@ -409,6 +417,11 @@ export default defineConfig({ collapsed: true, items: [ { text: "Reference", link: "/resources/references" }, + // 615 working apps in three repositories, and until this page the + // only way to find out which one to open was to know all three + // existed. The cookbook links individual samples per chapter; this + // says which CATALOGUE answers which question. + { text: "Sample Catalogues", link: "/resources/samples" }, { text: "Who Uses abap2UI5?", link: "/resources/who_uses" }, { text: "Release", link: "/resources/changelog" }, { text: "Deprecations", link: "/resources/deprecations" }, diff --git a/docs/resources/samples.md b/docs/resources/samples.md new file mode 100644 index 00000000..40ab2356 --- /dev/null +++ b/docs/resources/samples.md @@ -0,0 +1,79 @@ +--- +outline: [2, 4] +--- +# Sample Catalogues + +**615 working apps, in three repositories.** Every one is a single ABAP class +that compiles, renders, and is downported to three releases — so a sample is +never a fragment you have to trust, it is an app you can pull and run. + +The three answer three different questions. Picking the wrong one costs more +time than reading this page. + +| | | you are asking | +|---|--:|---| +| [**samples**](https://github.com/abap2UI5/samples/blob/main/SAMPLES.md) | 152 | *has somebody already built this pattern?* — value help, navigation between apps, trees, tables, timers, file up- and download. Runs on a bare abap2UI5 install. | +| [**samples-controls**](https://github.com/abap2UI5/samples-controls/blob/main/SAMPLES.md) | 431 | *how is this UI5 control expressed in ABAP?* — the UI5 demo kit, rebuilt control by control, grouped by library. | +| [**samples-stack**](https://github.com/abap2UI5/samples-stack/blob/main/SAMPLES.md) | 32 | *how do I reach my system from an app?* — OData, RAP, APC, MIME, the Fiori Launchpad. Each needs something the framework alone does not give you. | + +Start with **samples** if you are learning abap2UI5, with **samples-controls** +if you know which control you want, and with **samples-stack** only when the +app has to talk to something in your system. + +## The pages have the same shape on purpose + +Every row of every catalogue reads the same way: + +> **sap.m.Breadcrumbs** +> Breadcrumbs is useful for displaying link hierarchy +> breadcrumbs sap.m breadcrumb trail separator link hbox label select + +The **title** says which sample it is, the **sentence** says what it shows, and +the **small type** are the words to search the page for — the terms somebody +would type who does not yet know the sample exists. `Ctrl+F` on any of the +three pages is a real search, not a scroll. + +None of it is written on the page. All three lines live **on the class**, as +its abapGit short text and two comment lines above `CLASS … DEFINITION`: + +```abap +" @keywords f4 search help suggestion input dialog select +" @summary The value help, both halves: suggestions while typing and the F4 dialog behind the field. +CLASS z2ui5_cl_smp_app_009 DEFINITION PUBLIC. +``` + +The catalogues are generated from those lines, and each repository refuses a +sample that is missing one. So a page can never describe a sample differently +from the class it links to — and a search engine that drops you into the class +gives you the same sentence the catalogue would have. + +## For AI agents + +The same three catalogues are queryable through the +[MCP server](https://github.com/abap2UI5/ai-mcp) — the `examples` tool searches +all of them at once and answers with a repository, a class name and a path to +read, never with a copied snippet: + +``` +examples { query: "value help f4" } +examples { query: "wizard", repo: "samples-controls" } +``` + +The neighbouring question — *can abap2UI5 express this UI5 feature at all* — is +the `capabilities` tool, out of `samples-controls`' +[CAPABILITIES.md](https://github.com/abap2UI5/samples-controls/blob/main/CAPABILITIES.md). +Neither answers the other: a control being expressible says nothing about how +an app that uses it is put together. + +## Running one + +Install [abap2UI5](https://github.com/abap2UI5/abap2UI5), pull the repository +with [abapGit](https://abapgit.org), then start any class by name: + +``` +?app_start=Z2UI5_CL_SMP_APP_009 +``` + +Each repository also ships an **overview app** that lists its own samples with +a search box, so once the repository is in your system you do not need the page +here at all.