Skip to content

Commit ece4503

Browse files
claudeclaude
committed
docs: add AI-Assisted Development guide for Getting Started
1 parent 93bbee1 commit ece4503

2 files changed

Lines changed: 250 additions & 0 deletions

File tree

‎docs/.vitepress/config.mjs‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -114,6 +114,7 @@ export default defineConfig({
114114
{ text: "Full Example", link: "/get_started/full_example" },
115115
],
116116
},
117+
{ text: "AI-Assisted Development", link: "/get_started/ai" },
117118
{ text: `What's Next?`, link: "/get_started/next" },
118119
],
119120
},

‎docs/get_started/ai.md‎

Lines changed: 249 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,249 @@
1+
---
2+
outline: [2, 4]
3+
---
4+
# AI-Assisted Development
5+
6+
This page is the entry point for any AI assistant (Claude, Copilot, Cursor, …) that should build abap2UI5 apps. It collects, in one place, every source of information the model needs and points to the canonical references in the three project repositories.
7+
8+
If you are pasting context into an AI tool, **start here**, then follow the links — the linked files (especially the `CLAUDE.md` files in the source repositories) are kept up to date with every release and are the source of truth.
9+
10+
## The Three Repositories
11+
12+
abap2UI5 lives in three repositories. Each carries information an AI assistant should know:
13+
14+
| Repository | What's in it | Why an AI needs it |
15+
|---|---|---|
16+
| **[abap2UI5/abap2UI5](https://github.com/abap2UI5/abap2UI5)** | Core framework — interfaces, view builder, runtime | The public API (`z2ui5_if_app`, `z2ui5_if_client`, `z2ui5_cl_xml_view`, `z2ui5_cl_util_xml`) the app interacts with |
17+
| **[abap2UI5/samples](https://github.com/abap2UI5/samples)** | 250+ working demo apps + app-development guide | Canonical patterns and a copy-pastable example for almost every UI5 control and feature |
18+
| **[abap2UI5/docs](https://github.com/abap2UI5/docs)** | This documentation site | Conceptual background, lifecycle, cookbook recipes |
19+
20+
## Primary AI Briefings — The `CLAUDE.md` Files
21+
22+
Two `CLAUDE.md` files in the source repositories are written specifically as briefings for AI assistants. They are the **first** thing to read:
23+
24+
- **[abap2UI5/CLAUDE.md](https://github.com/abap2UI5/abap2UI5/blob/main/CLAUDE.md)** — framework-level briefing
25+
- Project overview, architecture, the request/response roundtrip
26+
- Repository layout (`src/00` utilities, `src/01` engine, `src/02` public API)
27+
- Coding rules, naming, style guide (Clean ABAP exceptions)
28+
- **Deprecated UI5 controls** to avoid
29+
- Important rules for AI assistants (do/don't list)
30+
31+
- **[samples/CLAUDE.md](https://github.com/abap2UI5/samples/blob/main/CLAUDE.md)** — app-development briefing
32+
- Canonical app structure (`on_init`, `on_event`, `view_display`, `data_read`, `data_update`)
33+
- Formatting rules (blank lines, indentation, parameter alignment)
34+
- When to use inline vs. handler methods
35+
- Navigation patterns and event dispatching
36+
- `z2ui5_cl_xml_view` vs. `z2ui5_cl_util_xml` style rules
37+
38+
If an AI assistant only reads two files in this project, these are the two.
39+
40+
## Quick Briefing — The Mental Model
41+
42+
The minimum an AI must know to write working apps:
43+
44+
#### 1. One interface, one method
45+
46+
Every app implements `z2ui5_if_app` and has a single `main` method. The framework calls `main` on every HTTP roundtrip — initial load *and* every user interaction:
47+
48+
```abap
49+
CLASS zcl_my_app DEFINITION PUBLIC.
50+
PUBLIC SECTION.
51+
INTERFACES z2ui5_if_app.
52+
ENDCLASS.
53+
54+
CLASS zcl_my_app IMPLEMENTATION.
55+
METHOD z2ui5_if_app~main.
56+
" everything happens here
57+
ENDMETHOD.
58+
ENDCLASS.
59+
```
60+
61+
#### 2. Dispatch with `CASE abap_true`
62+
63+
`main` is a dispatcher. Three lifecycle checks decide what to do:
64+
65+
```abap
66+
CASE abap_true.
67+
WHEN client->check_on_init( ). " first call
68+
" load data + render view
69+
WHEN client->check_on_event( `POST` ). " user fired event 'POST'
70+
" handle it
71+
WHEN client->check_on_navigated( ). " returned from sub-app / popup
72+
" refresh state
73+
ENDCASE.
74+
```
75+
76+
→ [Life Cycle](/cookbook/event_navigation/life_cycle)
77+
78+
#### 3. State lives in **public** class attributes
79+
80+
Anything bound to the view must be `PUBLIC`. The framework serializes public attributes between roundtrips automatically — no session handling needed.
81+
82+
→ [Binding → Bound Attributes Must Be Public](/cookbook/model/binding#bound-attributes-must-be-public)
83+
84+
#### 4. `client` is the only framework API
85+
86+
Views, events, binding, navigation, messages — everything goes through the `client` reference (`z2ui5_if_client`):
87+
88+
| Category | Methods |
89+
|---|---|
90+
| Views | `view_display`, `view_destroy`, `view_model_update` |
91+
| Popups / popovers | `popup_display`, `popup_destroy`, `popover_display`, `popover_destroy` |
92+
| Binding | `_bind( var )` (read-only), `_bind_edit( var )` (two-way) |
93+
| Events | `_event( 'NAME' )`, `check_on_event( 'NAME' )`, `get_event_arg( i )` |
94+
| Navigation | `nav_app_call( app )`, `nav_app_leave( )`, `get_app_prev( )` |
95+
| Messages | `message_box_display`, `message_toast_display` |
96+
| Lifecycle | `check_on_init`, `check_on_event`, `check_on_navigated` |
97+
98+
Read the full interface at [`z2ui5_if_client.intf.abap`](https://github.com/abap2UI5/abap2UI5/blob/main/src/02/z2ui5_if_client.intf.abap).
99+
100+
#### 5. Views are XML — built with one of two builders
101+
102+
Views are UI5 XML strings passed to `client->view_display( ... )`. The framework ships two builders, both fully supported:
103+
104+
- **`z2ui5_cl_util_xml`** — generic XML builder. Element name + attributes as strings → maps **1:1** to the UI5 SDK. **Recommended for AI-generated code.**
105+
- **`z2ui5_cl_xml_view`** — fluent builder with one ABAP method per UI5 control (~446 methods). Convenient for humans, but has naming inconsistencies and incomplete coverage → harder for an AI to use correctly.
106+
107+
→ [View Definition + AI Tip](/cookbook/view/definition#recommended-for-ai-assisted-development)
108+
109+
## Recommended Builder for AI: `z2ui5_cl_util_xml`
110+
111+
Translate any UI5 XML example from the [UI5 SDK](https://sapui5.hana.ondemand.com/sdk) **1:1** into ABAP — no wrapper, no abstraction:
112+
113+
| UI5 XML | ABAP with `z2ui5_cl_util_xml` |
114+
|---|---|
115+
| `<Button text="Send" />` | `->__( n = `Button` a = `text` v = `Send` )` |
116+
| `press="onPress"` | `v = client->_event( `BUTTON_POST` )` |
117+
| `value="{/name}"` | `v = client->_bind_edit( name )` |
118+
| `<FeedInput><actions>…</actions></FeedInput>` | `->_( `FeedInput` )->_( `actions` )->__( … )` |
119+
120+
Builder methods:
121+
122+
- `_( n, ns, p )` — add child, **go into** it (next call adds a grandchild)
123+
- `__( n, ns, a, v, p )` — add child, **stay** at current level (leaf / sibling)
124+
- `p( n, v )` — add a single attribute to the current node
125+
- `n( 'Name' )` / `n( )` — navigate to named ancestor / parent
126+
- `stringify( indent = abap_true )` — serialize to XML
127+
128+
::: warning Boolean attribute values
129+
Always pass `'true'` or `'false'` as **string literals** — never `abap_true` / `abap_false`. `abap_false` (space) is silently dropped; `abap_true` (`'X'`) produces an invalid XML attribute value.
130+
:::
131+
132+
Complete worked example: see [Quickstart](/get_started/quickstart), [Hello World](/get_started/hello_world), [Full Example](/get_started/full_example), and the `CLAUDE.md` in [abap2UI5](https://github.com/abap2UI5/abap2UI5/blob/main/CLAUDE.md#building-views--two-supported-apis).
133+
134+
## Canonical App Template
135+
136+
For anything beyond ~50 lines in `main`, extract `on_init` and `on_event` first, then add helpers (`view_display`, `data_read`, `data_update`) only when needed. Class names lowercase, no `FINAL`, definition order `TYPES` → `DATA` → `METHODS`.
137+
138+
```abap
139+
CLASS zcl_app_xxx DEFINITION PUBLIC.
140+
141+
PUBLIC SECTION.
142+
INTERFACES z2ui5_if_app.
143+
" bound data (public DATA attributes used by _bind / _bind_edit)
144+
145+
PROTECTED SECTION.
146+
DATA client TYPE REF TO z2ui5_if_client.
147+
148+
METHODS on_init. " first call: load data, render view
149+
METHODS on_event. " user triggered an event
150+
METHODS on_navigation. " returned from sub-app or popup
151+
METHODS view_display. " build and render the view
152+
METHODS data_read. " SELECT
153+
METHODS data_update. " INSERT / UPDATE / DELETE
154+
155+
PRIVATE SECTION.
156+
157+
ENDCLASS.
158+
159+
160+
CLASS zcl_app_xxx IMPLEMENTATION.
161+
162+
METHOD z2ui5_if_app~main.
163+
164+
me->client = client.
165+
IF client->check_on_init( ).
166+
on_init( ).
167+
ELSEIF client->check_on_navigated( ).
168+
on_navigation( ).
169+
ELSEIF client->check_on_event( ).
170+
on_event( ).
171+
ENDIF.
172+
173+
ENDMETHOD.
174+
175+
" on_init / on_event / view_display / data_read / data_update …
176+
177+
ENDCLASS.
178+
```
179+
180+
The full template (with formatting and blank-line rules) lives in [samples/CLAUDE.md](https://github.com/abap2UI5/samples/blob/main/CLAUDE.md#app-structure).
181+
182+
## Sample Apps — 250+ Working Examples
183+
184+
The fastest way for an AI to ground a generation in working code is to look up a similar app in the [samples repository](https://github.com/abap2UI5/samples/tree/main/src). Each `z2ui5_cl_demo_app_*` class is a self-contained, abapGit-installable app demonstrating a single feature or control.
185+
186+
Browse them online (no system needed): <https://abap2ui5.github.io/web-abap2ui5-samples/>
187+
188+
## Built-In Popups — Do Not Reinvent
189+
190+
Before building a custom dialog, check whether one of the built-in popup classes already covers the case:
191+
192+
`Z2UI5_CL_POP_TO_CONFIRM`, `Z2UI5_CL_POP_TO_INFORM`, `Z2UI5_CL_POP_TO_SELECT`, `Z2UI5_CL_POP_FILE_UL`, `Z2UI5_CL_POP_FILE_DL`, `Z2UI5_CL_POP_TABLE`, `Z2UI5_CL_POP_TEXTEDIT`, `Z2UI5_CL_POP_PDF`, `Z2UI5_CL_POP_HTML`, `Z2UI5_CL_POP_MESSAGES`, `Z2UI5_CL_POP_ERROR`, `Z2UI5_CL_POP_GET_RANGE`, `Z2UI5_CL_POP_GET_RANGE_M`, `Z2UI5_CL_POP_INPUT_VAL`, `Z2UI5_CL_POP_JS_LOADER`, `Z2UI5_CL_POP_ITAB_JSON_DL`
193+
194+
→ [Built-in popups](/cookbook/popup_popover/built_in)
195+
196+
## Deprecated UI5 Controls — Do Not Generate
197+
198+
Whole libraries to **never** use: `sap.ui.commons.*`, legacy `sap.viz.ui5.*` charts.
199+
200+
Individual deprecated items: `sap.m.MultiEditField`, `sap.f.Avatar` (use `sap.m.Avatar`), `sap.ui.core.XMLComposite`, `HTMLView`, `JSONView`, `JSView`, `TemplateView`, `sap.ui.table.ColumnHeader`, `sap.f.routing.*`, deprecated `Avatar*` enums, Belize / Blue Crystal themes, …
201+
202+
The authoritative list is at <https://ui5.sap.com/#/api/deprecated>. A condensed, AI-friendly version is in the [abap2UI5 CLAUDE.md → Deprecated UI5 Controls](https://github.com/abap2UI5/abap2UI5/blob/main/CLAUDE.md#deprecated-ui5-controls--do-not-use) section.
203+
204+
## Documentation Map — What to Read When
205+
206+
When an AI needs deeper information than this page provides:
207+
208+
| Topic | Best reference |
209+
|---|---|
210+
| Architecture, request roundtrip | [Concept](/technical/concept), [How It All Works](/technical/how_it_all_works) |
211+
| Lifecycle and `CASE abap_true` pattern | [Cookbook → Life Cycle](/cookbook/event_navigation/life_cycle) |
212+
| Building views, control choice | [Cookbook → View Definition](/cookbook/view/definition) |
213+
| Data binding (`_bind`, `_bind_edit`) | [Cookbook → Binding](/cookbook/model/binding) |
214+
| Tables and trees | [Cookbook → Tables](/cookbook/model/tables), [Trees](/cookbook/model/trees) |
215+
| Events, actions, exceptions | [Cookbook → Event, Navigation](/cookbook/event_navigation/life_cycle) |
216+
| Popups and popovers | [Cookbook → Popup, Popover](/cookbook/popup_popover/popup) |
217+
| Messages, toasts, i18n | [Cookbook → Translation, Messages](/cookbook/translation_messages/message) |
218+
| Browser interaction (focus, scroll, URL) | [Cookbook → Browser Interaction](/cookbook/browser_interaction/title) |
219+
| Device features (camera, geo, files) | [Cookbook → Device Capabilities](/cookbook/device_capabilities/info) |
220+
| RAP / CDS / EML integration | [Cookbook → EML, CDS, SQL](/cookbook/eml_cds_sql/rap) |
221+
| Snippets and recurring patterns | [Cookbook → Snippets](/cookbook/expert_more/snippets) |
222+
| Installation / HTTP handler | [Quickstart](/get_started/quickstart) |
223+
224+
## A Ready-Made Prompt for AI Assistants
225+
226+
A prompt that gives an AI assistant enough context to produce a working app:
227+
228+
> You are building an abap2UI5 app. Before writing any code, read these two briefings:
229+
>
230+
> 1. <https://github.com/abap2UI5/abap2UI5/blob/main/CLAUDE.md> — framework, API, rules
231+
> 2. <https://github.com/abap2UI5/samples/blob/main/CLAUDE.md> — app structure, formatting
232+
>
233+
> Then consult <https://abap2ui5.github.io/docs/get_started/ai.html> for the documentation map and <https://github.com/abap2UI5/samples/tree/main/src> for 250+ working examples. Use `z2ui5_cl_util_xml` as the view builder. Look up any UI5 control at <https://ui5.sap.com/#/api> and translate the XML 1:1 to ABAP. Avoid any control listed in the "Deprecated UI5 Controls" section of the framework `CLAUDE.md`.
234+
235+
## Hard Rules (Cheat Sheet)
236+
237+
| Rule | Why |
238+
|---|---|
239+
| Implement `z2ui5_if_app` with a single `main` method | The only entry point the framework calls |
240+
| Bound attributes must be `PUBLIC` | The framework binds via dynamic ASSIGN; `PROTECTED`/`PRIVATE` are silently ignored |
241+
| Use `CASE abap_true` with `check_on_init` / `check_on_event( 'NAME' )` / `check_on_navigated` | Canonical dispatcher pattern |
242+
| Use `z2ui5_cl_util_xml` for AI-generated views | Maps 1:1 to UI5 SDK; no wrapper to learn |
243+
| Pass XML boolean attributes as string literals `'true'` / `'false'` | `abap_true` / `abap_false` produce invalid or empty attributes |
244+
| Use backtick string literals (`` ` ``), not single quotes | Project-wide convention enforced by abaplint |
245+
| Never use a deprecated control | See list in framework `CLAUDE.md` |
246+
| Use built-in popups (`z2ui5_cl_pop_*`) before building custom ones | Tested, consistent, less code |
247+
| Run `npx abaplint` on every change in the framework / samples repos | Primary quality gate; must report 0 issues |
248+
249+
That's the briefing. Hand the link to this page (or the two `CLAUDE.md` files it points to) to any AI tool and it has everything it needs to build a working abap2UI5 app.

0 commit comments

Comments
 (0)