Skip to content

Commit 2cf8315

Browse files
oblomov-devoblomov-dev
authored
Merge pull request #107 from abap2UI5/claude/ai-app-build-docs-5KVxw
Add comprehensive AI-assisted development guide
2 parents 93bbee1 + 743de96 commit 2cf8315

3 files changed

Lines changed: 272 additions & 4 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/cookbook/view/definition.md‎

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -132,10 +132,6 @@ Every fluent helper ultimately produces an XML element. The lowest-level method
132132

133133
This maps **1:1** to the UI5 XML/SDK API — control names, property names, and aggregation names are written exactly as they appear in the [UI5 SDK](https://sapui5.hana.ondemand.com), in their original camelCase. There is no abstraction layer guessing what to call things.
134134

135-
::: tip Recommended for AI-assisted Development
136-
For AI-assisted coding, prefer the generic builder. It removes the need for the model to know the abap2UI5 naming conventions or guess which controls and properties are wrapped — the SDK documentation can be used directly. The fluent API in `Z2UI5_CL_XML_VIEW` is convenient for humans but its inconsistencies and incomplete coverage make it a poor target for code generation.
137-
:::
138-
139135
The rest of this documentation uses the higher-level fluent API (`->page( )`, `->button( )`, `->multi_combo_box( )`) because it reads better in examples. Both styles can be mixed freely in the same view.
140136

141137
#### Next Steps

‎docs/get_started/ai.md‎

Lines changed: 271 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,271 @@
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+
## Source-Repo Briefings (for Framework / Sample Contributors)
21+
22+
The two source repositories carry `CLAUDE.md` briefings aimed at AI tools that work **inside those repos** — they are not needed for building apps:
23+
24+
- **[abap2UI5/CLAUDE.md](https://github.com/abap2UI5/abap2UI5/blob/main/CLAUDE.md)** — for AI assistants **modifying the framework itself**: layered architecture (`src/00` utilities, `src/01` engine, `src/02` public API), coding rules, naming, abaplint setup, Clean-ABAP exceptions, public-API stability contract.
25+
- **[samples/CLAUDE.md](https://github.com/abap2UI5/samples/blob/main/CLAUDE.md)** — for AI assistants **contributing sample apps**: formatting rules (blank lines, indentation), file/class conventions, abaplint setup.
26+
27+
If you only want to **build an abap2UI5 app**, this page is the single source — you do not need to read those files.
28+
29+
## Quick Briefing — The Mental Model
30+
31+
The minimum an AI must know to write working apps:
32+
33+
#### 1. One interface, one method
34+
35+
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:
36+
37+
```abap
38+
CLASS zcl_my_app DEFINITION PUBLIC.
39+
PUBLIC SECTION.
40+
INTERFACES z2ui5_if_app.
41+
ENDCLASS.
42+
43+
CLASS zcl_my_app IMPLEMENTATION.
44+
METHOD z2ui5_if_app~main.
45+
" everything happens here
46+
ENDMETHOD.
47+
ENDCLASS.
48+
```
49+
50+
#### 2. Dispatch with `CASE abap_true`
51+
52+
`main` is a dispatcher. Three lifecycle checks decide what to do:
53+
54+
```abap
55+
CASE abap_true.
56+
WHEN client->check_on_init( ). " first call
57+
" load data + render view
58+
WHEN client->check_on_event( `POST` ). " user fired event 'POST'
59+
" handle it
60+
WHEN client->check_on_navigated( ). " returned from sub-app / popup
61+
" refresh state
62+
ENDCASE.
63+
```
64+
65+
→ [Life Cycle](/cookbook/event_navigation/life_cycle)
66+
67+
#### 3. State lives in **public** class attributes
68+
69+
Anything bound to the view must be `PUBLIC`. The framework serializes public attributes between roundtrips automatically — no session handling needed.
70+
71+
→ [Binding → Bound Attributes Must Be Public](/cookbook/model/binding#bound-attributes-must-be-public)
72+
73+
#### 4. `client` is the only framework API
74+
75+
Views, events, binding, navigation, messages — everything goes through the `client` reference (`z2ui5_if_client`):
76+
77+
| Category | Methods |
78+
|---|---|
79+
| Views | `view_display`, `view_destroy`, `view_model_update` |
80+
| Popups / popovers | `popup_display`, `popup_destroy`, `popover_display`, `popover_destroy` |
81+
| Binding | `_bind( var )` (read-only), `_bind_edit( var )` (two-way) |
82+
| Events | `_event( 'NAME' )`, `check_on_event( 'NAME' )`, `get_event_arg( i )` |
83+
| Navigation | `nav_app_call( app )`, `nav_app_leave( )`, `get_app_prev( )` |
84+
| Messages | `message_box_display`, `message_toast_display` |
85+
| Lifecycle | `check_on_init`, `check_on_event`, `check_on_navigated` |
86+
87+
Read the full interface at [`z2ui5_if_client.intf.abap`](https://github.com/abap2UI5/abap2UI5/blob/main/src/02/z2ui5_if_client.intf.abap).
88+
89+
#### 5. Views are XML — built with one of two builders
90+
91+
Views are UI5 XML strings passed to `client->view_display( ... )`. The framework ships two builders, both fully supported:
92+
93+
- **`z2ui5_cl_util_xml`** — generic XML builder. Element name + attributes as strings → maps **1:1** to the UI5 SDK. **Recommended for AI-generated code.**
94+
- **`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.
95+
96+
→ [View Definition](/cookbook/view/definition)
97+
98+
## Recommended Builder for AI: `z2ui5_cl_util_xml`
99+
100+
Translate any UI5 XML example from the [UI5 SDK](https://sapui5.hana.ondemand.com/sdk) **1:1** into ABAP — no wrapper, no abstraction:
101+
102+
| UI5 XML | ABAP with `z2ui5_cl_util_xml` |
103+
|---|---|
104+
| `<Button text="Send" />` | `->__( n = `Button` a = `text` v = `Send` )` |
105+
| `press="onPress"` | `v = client->_event( `BUTTON_POST` )` |
106+
| `value="{/name}"` | `v = client->_bind_edit( name )` |
107+
| `<FeedInput><actions>…</actions></FeedInput>` | `->_( `FeedInput` )->_( `actions` )->__( … )` |
108+
109+
Builder methods:
110+
111+
- `_( n, ns, p )` — add child, **go into** it (next call adds a grandchild)
112+
- `__( n, ns, a, v, p )` — add child, **stay** at current level (leaf / sibling)
113+
- `p( n, v )` — add a single attribute to the current node
114+
- `n( 'Name' )` / `n( )` — navigate to named ancestor / parent
115+
- `stringify( indent = abap_true )` — serialize to XML
116+
117+
::: warning Boolean attribute values
118+
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.
119+
:::
120+
121+
Complete worked example: see [Quickstart](/get_started/quickstart), [Hello World](/get_started/hello_world), and [Full Example](/get_started/full_example).
122+
123+
## Canonical App Template
124+
125+
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`.
126+
127+
```abap
128+
CLASS zcl_app_xxx DEFINITION PUBLIC.
129+
130+
PUBLIC SECTION.
131+
INTERFACES z2ui5_if_app.
132+
" bound data (public DATA attributes used by _bind / _bind_edit)
133+
134+
PROTECTED SECTION.
135+
DATA client TYPE REF TO z2ui5_if_client.
136+
137+
METHODS on_init. " first call: load data, render view
138+
METHODS on_event. " user triggered an event
139+
METHODS on_navigation. " returned from sub-app or popup
140+
METHODS view_display. " build and render the view
141+
METHODS data_read. " SELECT
142+
METHODS data_update. " INSERT / UPDATE / DELETE
143+
144+
PRIVATE SECTION.
145+
146+
ENDCLASS.
147+
148+
149+
CLASS zcl_app_xxx IMPLEMENTATION.
150+
151+
METHOD z2ui5_if_app~main.
152+
153+
me->client = client.
154+
IF client->check_on_init( ).
155+
on_init( ).
156+
ELSEIF client->check_on_navigated( ).
157+
on_navigation( ).
158+
ELSEIF client->check_on_event( ).
159+
on_event( ).
160+
ENDIF.
161+
162+
ENDMETHOD.
163+
164+
" on_init / on_event / view_display / data_read / data_update …
165+
166+
ENDCLASS.
167+
```
168+
169+
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).
170+
171+
## Sample Apps — 250+ Working Examples
172+
173+
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.
174+
175+
Browse them online (no system needed): <https://abap2ui5.github.io/web-abap2ui5-samples/>
176+
177+
## Built-In Popups — Do Not Reinvent
178+
179+
Before building a custom dialog, check whether one of the built-in popup classes already covers the case:
180+
181+
`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`
182+
183+
→ [Built-in popups](/cookbook/popup_popover/built_in)
184+
185+
## Deprecated UI5 Controls — Do Not Generate
186+
187+
The authoritative list is at <https://ui5.sap.com/#/api/deprecated>. The most common pitfalls for generated code:
188+
189+
**Whole libraries — never use any control from these:**
190+
191+
| Library | Deprecated since | Use instead |
192+
|---|---|---|
193+
| `sap.ui.commons.*` (Accordion, Button, CheckBox, ComboBox, DatePicker, Dialog, FileUploader, Label, Link, Menu, Panel, RadioButton, SearchField, Slider, TextArea, TextField, TextView, ToggleButton, Toolbar, Tree, Form, SimpleForm, AbsoluteLayout, BorderLayout, MatrixLayout, HorizontalLayout, VerticalLayout, … — entire library) | 1.38 | `sap.m` + `sap.ui.layout` |
194+
| `sap.viz.ui5.*` legacy charts (Bar, Bubble, Bullet, Column, Combination, Donut, Heatmap, Line, Pie, Scatter, StackedColumn, Treemap, Waterfall, …) | 1.32 | `sap.viz.ui5.controls.VizFrame` |
195+
196+
**Individual deprecated controls:**
197+
198+
| Control | Deprecated since | Use instead |
199+
|---|---|---|
200+
| `sap.m.MultiEditField` | 1.120 | — |
201+
| `sap.f.Avatar` | 1.73 | `sap.m.Avatar` |
202+
| `sap.ui.core.XMLComposite` | 1.88 | Custom controls |
203+
| `sap.ui.core.mvc.HTMLView` | 1.108 | `XMLView` |
204+
| `sap.ui.core.mvc.JSONView` | 1.120 | `XMLView` |
205+
| `sap.ui.core.mvc.JSView` | 1.90 | Typed views |
206+
| `sap.ui.core.mvc.TemplateView` | 1.56 | `XMLView` |
207+
| `sap.ui.core.tmpl.TemplateControl` | 1.56 | — |
208+
| `sap.ui.table.ColumnHeader` | 1.120 | `sap.ui.table.Column` |
209+
| `sap.ui.table.TableHelper` | 1.118 | — |
210+
| `sap.f.routing.Router` / `Target` / `TargetHandler` / `Targets` | 1.56 | `sap.m.routing.*` (async) |
211+
| `sap.tnt.IToolHeader` (interface) | 1.135 | Any control as `ToolPage` header |
212+
213+
**Deprecated enums/types to avoid:**
214+
215+
- `sap.m.ValueCSSColor`, `DateTimeInputType` (use `DatePicker` / `TimePicker`), `ListHeaderDesign`, `ListMode.SingleSelect` (1.143 → `SingleSelectLeft`), `FrameType.TwoThirds` / `Auto`, mis-spelled `PlacementType.*Prefered*` variants
216+
- `sap.f.AvatarShape` / `AvatarSize` / `AvatarType` / `AvatarColor` / `AvatarImageFitType` / `IllustratedMessageType` / `IllustratedMessageSize` / `DynamicPageTitleArea` (use the `sap.m.*` equivalents)
217+
- `sap.ui.layout.BlockBackgroundType.Mixed`, `form.GridElementCells`, `SimpleFormLayout.ResponsiveLayout`, `SimpleFormLayout.GridLayout`, `cssgrid.CSSGridGapShortHand`, `GridHelper`
218+
- `sap.ui.table.NavigationMode`, `SortOrder` (use `sap.ui.core.SortOrder`), `VisibleRowCountMode` (use `rowMode` aggregation), `TreeAutoExpandMode`, `ResetAllMode`
219+
- `sap.ui.core.MessageType` (use `module:sap/ui/core/message/MessageType`)
220+
- `sap.ui.unified.ContentSwitcherAnimation` (1.147 — concept discarded)
221+
222+
**Other deprecated framework items:**
223+
224+
- Analysis Path Framework (APF) — deprecated 1.140
225+
- `sap.m.PDFViewer.sourceValidationFailed()` — deprecated 1.141
226+
- Declarative `data-sap-ui-type` attribute — deprecated 1.120 (use XML views)
227+
- Belize, Blue Crystal, and Blue Crystal HCB themes — removed in 1.136 (use Horizon)
228+
229+
**Namespace caveat for `Avatar`:** when using `z2ui5_cl_xml_view->avatar( )`, leave `ns` empty so the element resolves to `sap.m.Avatar` via the View's default xmlns. **Never pass `ns = 'f'`** — that produces `<f:Avatar>`, which is the deprecated `sap.f.Avatar`. (`avatar_group` and `avatar_group_item` correctly use `ns = 'f'` because those controls still live in `sap.f`.)
230+
231+
## Documentation Map — What to Read When
232+
233+
When an AI needs deeper information than this page provides:
234+
235+
| Topic | Best reference |
236+
|---|---|
237+
| Architecture, request roundtrip | [Concept](/technical/concept), [How It All Works](/technical/how_it_all_works) |
238+
| Lifecycle and `CASE abap_true` pattern | [Cookbook → Life Cycle](/cookbook/event_navigation/life_cycle) |
239+
| Building views, control choice | [Cookbook → View Definition](/cookbook/view/definition) |
240+
| Data binding (`_bind`, `_bind_edit`) | [Cookbook → Binding](/cookbook/model/binding) |
241+
| Tables and trees | [Cookbook → Tables](/cookbook/model/tables), [Trees](/cookbook/model/trees) |
242+
| Events, actions, exceptions | [Cookbook → Event, Navigation](/cookbook/event_navigation/life_cycle) |
243+
| Popups and popovers | [Cookbook → Popup, Popover](/cookbook/popup_popover/popup) |
244+
| Messages, toasts, i18n | [Cookbook → Translation, Messages](/cookbook/translation_messages/message) |
245+
| Browser interaction (focus, scroll, URL) | [Cookbook → Browser Interaction](/cookbook/browser_interaction/title) |
246+
| Device features (camera, geo, files) | [Cookbook → Device Capabilities](/cookbook/device_capabilities/info) |
247+
| RAP / CDS / EML integration | [Cookbook → EML, CDS, SQL](/cookbook/eml_cds_sql/rap) |
248+
| Snippets and recurring patterns | [Cookbook → Snippets](/cookbook/expert_more/snippets) |
249+
| Installation / HTTP handler | [Quickstart](/get_started/quickstart) |
250+
251+
## A Ready-Made Prompt for AI Assistants
252+
253+
A prompt that gives an AI assistant enough context to produce a working app:
254+
255+
> You are building an abap2UI5 app. Read <https://abap2ui5.github.io/docs/get_started/ai.html> first — it is the single source of truth for app-building (template, client API, lifecycle, view builder, deprecated controls, documentation map). For working examples, browse <https://github.com/abap2UI5/samples/tree/main/src> (250+ apps, one feature per app). 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. Do not use any control listed in this page's "Deprecated UI5 Controls" section.
256+
257+
## Hard Rules (Cheat Sheet)
258+
259+
| Rule | Why |
260+
|---|---|
261+
| Implement `z2ui5_if_app` with a single `main` method | The only entry point the framework calls |
262+
| Bound attributes must be `PUBLIC` | The framework binds via dynamic ASSIGN; `PROTECTED`/`PRIVATE` are silently ignored |
263+
| Use `CASE abap_true` with `check_on_init` / `check_on_event( 'NAME' )` / `check_on_navigated` | Canonical dispatcher pattern |
264+
| Use `z2ui5_cl_util_xml` for AI-generated views | Maps 1:1 to UI5 SDK; no wrapper to learn |
265+
| Pass XML boolean attributes as string literals `'true'` / `'false'` | `abap_true` / `abap_false` produce invalid or empty attributes |
266+
| Use backtick string literals (`` ` ``), not single quotes | Project-wide convention enforced by abaplint |
267+
| Never use a deprecated control | See list in framework `CLAUDE.md` |
268+
| Use built-in popups (`z2ui5_cl_pop_*`) before building custom ones | Tested, consistent, less code |
269+
| Run `npx abaplint` on every change in the framework / samples repos | Primary quality gate; must report 0 issues |
270+
271+
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)