Skip to content

Commit 2db39f8

Browse files
claudeclaude
committed
docs: add samples index, doc style guide, navigation polish
Second pass of the documentation cleanup. - New page resources/samples_index.md: explains the sample naming convention, links to GitHub for each frequently-referenced demo class, wired into the Resources sidebar. - New documentation style guide in resources/contribution.md: frontmatter, heading levels, admonitions, code blocks (incl. code-group), sample links, internal-link format, images, Next Steps convention. Sets the rules used across this cleanup. - Cookbook entry pages (general, view, model/model, events, navigation/navigation) get Next Steps footers, matching the style used in Getting Started. - Tone cleanup on get_started/about.md (Overview & In Production sections): trim marketing language, lead with concrete claims. - technical/concept.md and technical/how_it_all_works.md get shorter intros and (for the long deep dive) a section roadmap so readers can jump to the part they care about. All internal doc links audited — no broken targets. https://claude.ai/code/session_011kvL4ihgqWYQa2SSufEaKv
1 parent e06e55b commit 2db39f8

11 files changed

Lines changed: 227 additions & 19 deletions

File tree

‎docs/.vitepress/config.mjs‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -274,6 +274,7 @@ export default defineConfig({
274274
collapsed: true,
275275
items: [
276276
{ text: "Add-ons", link: "/resources/addons" },
277+
{ text: "Samples Index", link: "/resources/samples_index" },
277278
{ text: "References", link: "/resources/references" },
278279
{ text: "Who Uses abap2UI5?", link: "/resources/who_uses" },
279280
{ text: "Releases", link: "/resources/changelog" },

‎docs/development/events.md‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -186,4 +186,10 @@ METHOD z2ui5_if_app~main.
186186
187187
ENDMETHOD.
188188
```
189-
See sample `Z2UI5_CL_DEMO_APP_180` for a complete example.
189+
See sample [`Z2UI5_CL_DEMO_APP_180`](/resources/samples_index) for a complete example.
190+
191+
## Next Steps
192+
193+
- **[Messages, Errors](/development/messages)** — show toasts, message boxes, and error dialogs in response to events.
194+
- **[Popups, Popovers](/development/popups)** — prompt the user from inside an event handler.
195+
- **[Navigation](/development/navigation/navigation)** — open another app as the result of an event.

‎docs/development/general.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,3 +87,10 @@ CLASS z2ui5_cl_demo_app_001 IMPLEMENTATION.
8787
ENDCLASS.
8888
```
8989
See the dedicated sections of this development guide for full details on views, events, data binding, and navigation.
90+
91+
## Next Steps
92+
93+
- **[View](/development/view)** — define the XML view via the abap2UI5 builder DSL.
94+
- **[Model](/development/model/model)** — bind ABAP data to the view.
95+
- **[Events](/development/events)** — react to button presses, input changes, and other user actions.
96+
- **[Navigation](/development/navigation/navigation)** — chain apps and pass data between them.

‎docs/development/model/model.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,3 +66,10 @@ ENDCLASS.
6666
::: tip Data in Public Attributes
6767
With one-way or two-way binding, store your data in the public attributes of your class so the framework can read it externally. This resembles the PAI/PBO logic, where data lived in global variables.
6868
:::
69+
70+
## Next Steps
71+
72+
- **[Tables, Trees](/development/model/tables)** — bind structured data into table-like controls.
73+
- **[Device Model](/development/model/device)** — query device characteristics (form factor, OS).
74+
- **[Expression Binding](/development/model/expression_binding)** — small in-view formulas without a formatter.
75+
- **[OData](/development/model/odata)** — when you need a real OData model behind a control.

‎docs/development/navigation/navigation.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,3 +63,8 @@ For more on Launchpads and routing, see the [Fiori Launchpad](/configuration/lau
6363
## Inner App Navigation
6464

6565
Use class attributes to track the current state and switch views as needed. This keeps navigation logic in a single ABAP class with no cross-app calls.
66+
67+
## Next Steps
68+
69+
- **[App State](/development/navigation/app_state)** — preserve state across navigations and roundtrips.
70+
- **[Share, Bookmark](/development/navigation/share)** — make app states deep-linkable.

‎docs/development/view.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,4 +40,8 @@ Tips for working with views:
4040
- See the [samples repository](/get_started/samples) for ready-made XML examples to copy and adapt
4141

4242
## Next Steps
43-
This produces a static view. The next section walks through binding and sharing data between the view and the app logic.
43+
44+
This produces a static view. To make it interactive:
45+
46+
- **[Model](/development/model/model)** — bind ABAP data to controls so the view reflects state.
47+
- **[Events](/development/events)** — react to button presses, input changes, and other user actions.

‎docs/get_started/about.md‎

Lines changed: 14 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -44,19 +44,19 @@ Each app ships as an [abapGit](https://abapgit.org) project, so installation acr
4444
## Overview
4545

4646
### Architecture
47-
abap2UI5 takes a "thin frontend" approach — all processing, logic, and data handling stay in the backend. This design simplifies configuration, cuts client-side complexity (no more cache-clearing headaches), and keeps business logic and sensitive data safely on the server.
47+
abap2UI5 takes a "thin frontend" approach: all processing, logic, and data handling stay in the backend. Cache-clearing on the client becomes irrelevant, and business logic and sensitive data stay on the server.
4848

4949
### Performance
50-
abap2UI5 is fast. The frontend focuses only on UI rendering via the UI5 framework, while the ABAP backend handles all processing. Unlike traditional UI5 apps that need separate OData calls for each view, abap2UI5 embeds data directly in XML views — cutting network roundtrips and speeding up the response.
50+
The frontend renders UI5 controls; the ABAP backend handles everything else. View data is embedded directly in the XML view, so a roundtrip means one HTTP request — not one per OData entity.
5151

5252
### Security
53-
abap2UI5 is secure by design. All business logic stays in the ABAP backend. The frontend receives only the data the backend embeds directly in XML views. Unlike traditional UI5 apps that expose OData endpoints, abap2UI5 delivers only what users need — no access to raw services or database queries from external tools.
53+
Business logic stays in the ABAP backend. The frontend only receives what the backend chooses to embed in the rendered view. There is no public OData endpoint to discover or query.
5454

5555
### System Footprint
56-
The framework has a small system footprint — only classes and interfaces. Add functionality with optional add-ons to keep your system lean.
56+
The framework consists of classes and interfaces only — no database tables, no metadata. Optional add-ons cover specialized needs.
5757

5858
### Transparency
59-
All source code lives publicly on GitHub. We discuss features and issues openly, publish technical blog posts that explain key concepts, and ship fixes quickly via abapGit. You'll always understand how the framework works and can confirm its behavior.
59+
All source code lives on GitHub. Issues and features are discussed openly, and fixes ship via abapGit.
6060

6161
## Compatibility
6262

@@ -74,15 +74,15 @@ Works with both ABAP Cloud and Standard ABAP, covering ABAP releases from 7.02 t
7474

7575
A downported version is available for systems on earlier ABAP releases (before 7.50).
7676

77-
## Enterprise Ready
77+
## In Production
7878

79-
abap2UI5 combines SAP's UI5 framework with ABAP's backend capabilities, shaped for enterprise SAP environments. It runs smoothly across S/4HANA Public/Private Cloud, BTP ABAP Environment, and NetWeaver systems.
79+
abap2UI5 runs on S/4HANA Public and Private Cloud, BTP ABAP Environment, and NetWeaver systems.
8080

8181
### Production Usage
82-
Use abap2UI5 like any other UI5 app or ABAP program in production. Add the framework and your apps to a transport request to ship them.
82+
Treat abap2UI5 like any other UI5 app or ABAP program: include the framework and your apps in a transport request and ship.
8383

8484
### Licensing
85-
Technically, abap2UI5 apps are standard UI5 freestyle apps. License them the same way you license other UI5 apps at your organization. abap2UI5 itself is MIT licensed (free for commercial use).
85+
abap2UI5 apps are standard UI5 freestyle apps. License them like any other UI5 app at your organization. abap2UI5 itself is MIT licensed (free for commercial use).
8686

8787
### Launchpad Integration
8888
Embed your apps into:
@@ -91,12 +91,12 @@ Embed your apps into:
9191
- Build Work Zone Websites on BTP
9292

9393
### Installation
94-
Getting started is easy:
95-
1. Import the project via abapGit
96-
2. Set up an HTTP service for browser communication
97-
3. Start building!
94+
Three steps:
95+
1. Import the project via abapGit.
96+
2. Set up an HTTP service for browser communication.
97+
3. Start building.
9898

99-
→ *See the [Installation Guide](/get_started/quickstart) for full instructions*
99+
→ *See the [Quickstart](/get_started/quickstart) for full instructions.*
100100

101101
## Community
102102

‎docs/resources/contribution.md‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,13 +6,123 @@ outline: [2, 3]
66
abap2UI5 is an open-source project built by the ABAP community, often in free time or alongside other projects. All kinds of contributions are welcome.
77

88
## How You Can Contribute
9+
910
There are several ways to get involved and help:
11+
1012
- Extend the view by adding a new property
1113
- Build a control to extend existing features
1214
- Build custom controls for specific scenarios
1315
- Share your demos and apps to showcase what's possible with abap2UI5
1416
- Improve the documentation and polish code snippets to make abap2UI5 easier to learn
1517
- Propose something new — every contribution is appreciated, no matter the size
1618

19+
## Documentation Style
20+
21+
The [docs repository](https://github.com/abap2UI5/docs) uses [VitePress](https://vitepress.dev). When editing or creating pages, follow the conventions below to keep navigation, search, and the in-page outline working.
22+
23+
### Frontmatter
24+
25+
Every page starts with:
26+
27+
```yaml
28+
---
29+
outline: [2, 3]
30+
---
31+
# Page Title
32+
```
33+
34+
`outline: [2, 3]` keeps the right-hand outline focused on `##` and `###` levels.
35+
36+
### Headings
37+
38+
- `# Title` — exactly one per page, matches the sidebar entry.
39+
- `## Section` — major sections; show up in the outline.
40+
- `### Subsection` — used inside a major section.
41+
- Don't skip levels. Don't start a page with `###` (the outline will be empty).
42+
43+
### Admonitions
44+
45+
VitePress callouts use this convention:
46+
47+
```markdown
48+
::: tip Optional Heading
49+
Best practice or helpful pointer.
50+
:::
51+
52+
::: warning Optional Heading
53+
Stolperstein, breaking change, or behavior to watch out for.
54+
:::
55+
56+
::: info Optional Heading
57+
Background context, not strictly required reading.
58+
:::
59+
60+
::: details Optional Heading
61+
Collapsed by default — use for ABAP Cloud variants, long screenshots, or extended examples.
62+
:::
63+
```
64+
65+
The optional heading is plain text — do **not** wrap it in `**bold**`.
66+
67+
### Code Blocks
68+
69+
Always tag the language:
70+
71+
````markdown
72+
```abap
73+
" ABAP code
74+
```
75+
76+
```javascript
77+
// JavaScript
78+
```
79+
80+
```text
81+
Plain text or ASCII diagrams
82+
```
83+
````
84+
85+
For ABAP / ABAP Cloud variants of the same snippet, use `code-group`:
86+
87+
````markdown
88+
::: code-group
89+
90+
```abap [ABAP]
91+
" Standard ABAP version
92+
```
93+
94+
```abap [ABAP Cloud]
95+
" ABAP Cloud version
96+
```
97+
:::
98+
````
99+
100+
### Linking to Samples
101+
102+
When mentioning a demo class (e.g., `Z2UI5_CL_DEMO_APP_167`), link to the [Samples Index](/resources/samples_index) so readers can find it on GitHub:
103+
104+
```markdown
105+
See sample [`Z2UI5_CL_DEMO_APP_167`](/resources/samples_index) for a complete example.
106+
```
107+
108+
### Internal Links
109+
110+
Use absolute, extensionless paths — no `.md`:
111+
112+
```markdown
113+
[Quickstart](/get_started/quickstart)
114+
```
115+
116+
### Images
117+
118+
- Prefer images checked into `docs/public/` over external URLs.
119+
- Always add descriptive alt text.
120+
- For wide images, use the inline `{ width=60% }` syntax to keep page layout balanced.
121+
122+
### Next Steps
123+
124+
Every guide page benefits from a `## Next Steps` section at the bottom that points readers to the obvious follow-up reading.
125+
17126
## Need Help?
127+
18128
If you hit any issues or have questions, open an [issue](https://github.com/abap2UI5/abap2UI5/issues).

‎docs/resources/samples_index.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
---
2+
outline: [2, 3]
3+
---
4+
# Samples Index
5+
6+
The [abap2UI5 samples repository](https://github.com/abap2UI5/abap2ui5-samples) ships 250+ runnable demo apps. Many pages in this documentation reference them by class name (e.g. `Z2UI5_CL_DEMO_APP_167`). This page explains how to locate a sample and lists the ones most often referenced in the docs.
7+
8+
## Naming Convention
9+
10+
Every demo app follows the pattern:
11+
12+
```text
13+
z2ui5_cl_demo_app_NNN
14+
```
15+
16+
Where `NNN` is a zero-padded three-digit number. Sources live under `src/` in the samples repository, grouped into folders (`00/`, `01/`, `02/`, …) by number range.
17+
18+
## Finding a Sample
19+
20+
The fastest ways to locate a class by name:
21+
22+
- **Direct file URL** — replace `NNN`:
23+
`https://github.com/abap2UI5/abap2ui5-samples/blob/main/src/0X/z2ui5_cl_demo_app_NNN.clas.abap`
24+
- **GitHub search** — search the samples repo:
25+
[`https://github.com/abap2UI5/abap2ui5-samples/search?q=z2ui5_cl_demo_app_NNN`](https://github.com/abap2UI5/abap2ui5-samples/search?q=z2ui5_cl_demo_app)
26+
- **In the running app** — press `Ctrl+F12` on any sample to open its source.
27+
- **In your browser, no system needed** — [browse all samples online](https://abap2ui5.github.io/web-abap2ui5-samples/).
28+
29+
## Frequently Referenced Samples
30+
31+
Samples cited from this documentation. Topic shows where in the docs the sample is used; click through to see it on GitHub.
32+
33+
| Sample | Topic |
34+
| ------------------------- | ------------------------------------------------------------- |
35+
| [`Z2UI5_CL_DEMO_APP_000`](https://github.com/abap2UI5/abap2ui5-samples/search?q=z2ui5_cl_demo_app_000) | [App State](/development/navigation/app_state) |
36+
| [`Z2UI5_CL_DEMO_APP_001`](https://github.com/abap2UI5/abap2ui5-samples/search?q=z2ui5_cl_demo_app_001) | [Controller basics](/development/general) |
37+
| [`Z2UI5_CL_DEMO_APP_003`](https://github.com/abap2UI5/abap2ui5-samples/search?q=z2ui5_cl_demo_app_003) | [Cloud Readiness](/technical/cloud) |
38+
| [`Z2UI5_CL_DEMO_APP_027`](https://github.com/abap2UI5/abap2ui5-samples/search?q=z2ui5_cl_demo_app_027) | [Expression Binding](/development/model/expression_binding) |
39+
| [`Z2UI5_CL_DEMO_APP_067`](https://github.com/abap2UI5/abap2ui5-samples/search?q=z2ui5_cl_demo_app_067) | [Formatter](/development/specific/formatter) |
40+
| [`Z2UI5_CL_DEMO_APP_075`](https://github.com/abap2UI5/abap2ui5-samples/search?q=z2ui5_cl_demo_app_075) | [File Handling](/development/specific/files) |
41+
| [`Z2UI5_CL_DEMO_APP_120`](https://github.com/abap2UI5/abap2ui5-samples/search?q=z2ui5_cl_demo_app_120) | [Geolocation](/development/specific/geolocation) |
42+
| [`Z2UI5_CL_DEMO_APP_122`](https://github.com/abap2UI5/abap2ui5-samples/search?q=z2ui5_cl_demo_app_122) | [Device Model](/development/model/device) |
43+
| [`Z2UI5_CL_DEMO_APP_124`](https://github.com/abap2UI5/abap2ui5-samples/search?q=z2ui5_cl_demo_app_124) | [Barcode Scanning](/development/specific/barcodes) |
44+
| [`Z2UI5_CL_DEMO_APP_135`](https://github.com/abap2UI5/abap2ui5-samples/search?q=z2ui5_cl_demo_app_135) | [Statefulness](/advanced/stateful) |
45+
| [`Z2UI5_CL_DEMO_APP_137`](https://github.com/abap2UI5/abap2ui5-samples/search?q=z2ui5_cl_demo_app_137) | [Statefulness](/advanced/stateful) |
46+
| [`Z2UI5_CL_DEMO_APP_139`](https://github.com/abap2UI5/abap2ui5-samples/search?q=z2ui5_cl_demo_app_139) | [URL Handling](/development/specific/url) |
47+
| [`Z2UI5_CL_DEMO_APP_161`](https://github.com/abap2UI5/abap2ui5-samples/search?q=z2ui5_cl_demo_app_161) | [Popups, Popovers](/development/popups) |
48+
| [`Z2UI5_CL_DEMO_APP_167`](https://github.com/abap2UI5/abap2ui5-samples/search?q=z2ui5_cl_demo_app_167) | [Events](/development/events) |
49+
| [`Z2UI5_CL_DEMO_APP_180`](https://github.com/abap2UI5/abap2ui5-samples/search?q=z2ui5_cl_demo_app_180) | [Events](/development/events) |
50+
| [`Z2UI5_CL_DEMO_APP_186`](https://github.com/abap2UI5/abap2ui5-samples/search?q=z2ui5_cl_demo_app_186) | [File Handling](/development/specific/files) |
51+
| [`Z2UI5_CL_DEMO_APP_304`](https://github.com/abap2UI5/abap2ui5-samples/search?q=z2ui5_cl_demo_app_304) | [Barcode Scanning](/development/specific/barcodes) |
52+
| [`Z2UI5_CL_DEMO_APP_306`](https://github.com/abap2UI5/abap2ui5-samples/search?q=z2ui5_cl_demo_app_306) | [Camera](/development/specific/camera) |
53+
| [`Z2UI5_CL_DEMO_APP_307`](https://github.com/abap2UI5/abap2ui5-samples/search?q=z2ui5_cl_demo_app_307) | [Drag & Drop](/development/specific/drag) |
54+
| [`Z2UI5_CL_DEMO_APP_313`](https://github.com/abap2UI5/abap2ui5-samples/search?q=z2ui5_cl_demo_app_313) | [Smart Controls](/development/specific/smart_controls) |
55+
| [`Z2UI5_CL_DEMO_APP_315`](https://github.com/abap2UI5/abap2ui5-samples/search?q=z2ui5_cl_demo_app_315) | [OData](/development/model/odata) |
56+
| [`Z2UI5_CL_DEMO_APP_321`](https://github.com/abap2UI5/abap2ui5-samples/search?q=z2ui5_cl_demo_app_321) | [App State](/development/navigation/app_state) |
57+
58+
::: tip Contributing
59+
The list above is curated from samples referenced in this documentation. The samples repo evolves continuously — for the full set, browse the [samples repository](https://github.com/abap2UI5/abap2ui5-samples) directly.
60+
:::

‎docs/technical/concept.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ outline: [2, 3]
55

66
_The Architecture of abap2UI5_
77

8-
This article introduces the core pattern behind abap2UI5: HTML Over-the-Wire — adapted for the ABAP ecosystem. It shows how this approach cuts traditional frontend complexity by moving UI rendering and app logic to the backend. The result: faster development, simpler deployment, and a UI5 frontend shell that's purely a rendering engine.
8+
This page explains the architectural pattern behind abap2UI5 — HTML Over-the-Wire, applied to UI5 — and why moving UI rendering and app logic to the ABAP backend simplifies development and deployment.
99

1010
## What is HTML Over-the-Wire?
1111

0 commit comments

Comments
 (0)