You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/cookbook/event_navigation/life_cycle.md
+21Lines changed: 21 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -49,3 +49,24 @@ ENDCLASS.
49
49
```
50
50
51
51
See the dedicated sections of this development guide for full details on views, events, data binding, and navigation.
52
+
53
+
## Lifecycle Pitfalls
54
+
55
+
A few details of the request lifecycle are easy to miss and produce bugs that look like framework issues but are actually pattern mistakes. These are not enforced by the compiler and not reported at runtime.
56
+
57
+
### Bound Attributes Must Be Public
58
+
`client->_bind( )` and `client->_bind_edit( )` access controller attributes from outside the class via dynamic ASSIGN. Attributes in `PROTECTED` or `PRIVATE SECTION` are invisible to the framework and silently fail to bind — the view shows nothing for one-way binding, and edits never sync back for two-way binding. There is no error.
59
+
60
+
Declare all attributes that participate in binding in `PUBLIC SECTION`. Helper variables that never appear in a `_bind( )` call can stay private. See [Binding → Bound Attributes Must Be Public](/cookbook/model/binding#bound-attributes-must-be-public).
61
+
62
+
### The View Is Only Sent When You Call `view_display`
63
+
abap2UI5 does not re-render the view automatically. After an event, if you do **not** call `client->view_display( ... )` again, the frontend keeps the previous view tree and only the model data is updated from the serialized state. This is the common case — most event handlers should mutate state and return, leaving the view alone.
64
+
65
+
Call `view_display( )` again only when the **structure** of the view needs to change: different controls, different bindings, a new dialog, navigation to a different screen. Rebuilding and re-sending the view on every event is wasteful and can cause visible flicker, lost scroll position, and lost focus.
66
+
67
+
### `check_on_event` Fires Once Per Roundtrip
68
+
Every HTTP request carries at most one event. `check_on_event( )` returns `abap_true` exactly once per call to `main`, for that single event. If the user clicks two buttons in quick succession, the framework dispatches them as two independent `main` invocations — they are never batched into one request.
69
+
70
+
Two consequences follow:
71
+
-**Do not assume event ordering inside one `main`.** You cannot look at "the previous event" from within an event handler; the previous event ran in a separate request and the work process has been released since.
72
+
-**State across events lives in public class attributes.** Between two events, abap2UI5 serializes the controller to the client and deserializes it on the next request. Anything stored in public attributes (and in serializable types) survives; local variables, open cursors, and acquired locks do not. For sessions that need surviving server-side resources, see [Statefulness](/cookbook/expert_more/statefulness).
Copy file name to clipboardExpand all lines: docs/cookbook/model/binding.md
+4-2Lines changed: 4 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -63,8 +63,10 @@ CLASS z2ui5_cl_app_hello_world IMPLEMENTATION.
63
63
ENDCLASS.
64
64
```
65
65
66
-
::: tip **Data in Public Attributes**
67
-
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.
66
+
::: warning **Bound Attributes Must Be Public**
67
+
`_bind( )` and `_bind_edit( )` access your class attributes from outside the controller via dynamic ASSIGN. This only works for attributes in the `PUBLIC SECTION` — `PROTECTED` and `PRIVATE` attributes are not visible to the framework and silently fail to bind: the view renders empty for one-way binding, and edits never sync back for two-way binding. There is no compile-time or runtime error.
68
+
69
+
Always declare bound data in `PUBLIC SECTION`. This resembles the PAI/PBO logic, where data lived in global variables. See also [Life Cycle → Lifecycle Pitfalls](/cookbook/event_navigation/life_cycle#lifecycle-pitfalls).
Copy file name to clipboardExpand all lines: docs/cookbook/view/definition.md
+41-1Lines changed: 41 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -37,7 +37,7 @@ You can use any UI5 control from the [UI5 SDK](https://sapui5.hana.ondemand.com)
37
37
38
38
Tips for working with views:
39
39
- Use code completion on `Z2UI5_CL_XML_VIEW` to find controls and properties
40
-
- See the [samples repository](/get_started/samples) for ready-made XML examples to copy and adapt
40
+
- See the [samples repository](/get_started/next#sample-apps) for ready-made XML examples to copy and adapt
41
41
42
42
::: warning Respect the UI5 Control Aggregation Rules
43
43
`Z2UI5_CL_XML_VIEW` is intentionally permissive — its fluent API lets you nest **any** control inside **any** other control. UI5 itself is not. Every UI5 control defines specific aggregations (e.g. `sap.m.Page` has `content`, `headerContent`, `footer`) and each aggregation accepts only certain child control types (often a particular interface or base class).
@@ -52,5 +52,45 @@ Combining controls in a way that violates these rules can lead to broken renderi
52
52
The ABAP compiler cannot catch these mistakes — they are pure UI5 concerns and must be verified against the SDK documentation.
53
53
:::
54
54
55
+
## Mapping UI5 XML ↔ ABAP Fluent API
56
+
57
+
`Z2UI5_CL_XML_VIEW` is a hand-curated wrapper around UI5 controls. It does not cover every UI5 control, and the naming is not always a strict 1:1 mapping of the UI5 SDK:
58
+
59
+
- Control names follow snake_case of the UI5 control class — `sap.m.MultiComboBox` becomes `->multi_combo_box( )`, `sap.m.Text` becomes `->text( )`.
60
+
- Properties are passed as named parameters in snake_case (`enabled`, `placeholder`, `selected_key`).
61
+
- Aggregations are exposed as methods named after the aggregation itself (`->items( )`, `->content( )`, `->custom_data( )`) — not as `add_item( )` / `add_content( )`. Calling the aggregation method returns the parent builder so you can chain children inside it.
62
+
- Coverage is incomplete and occasionally inconsistent: some controls or properties are missing, some method signatures don't match the SDK exactly. When in doubt, check the source of `Z2UI5_CL_XML_VIEW` or fall back to the generic builder below.
63
+
64
+
### The Fully Generic Builder
65
+
66
+
Every fluent helper ultimately produces an XML element. The lowest-level method `_generic( name = ... ns = ... )` lets you emit **any** XML element with **any** attributes, regardless of whether `Z2UI5_CL_XML_VIEW` knows the control:
67
+
68
+
```abap
69
+
DATA(view) = z2ui5_cl_xml_view=>factory( ).
70
+
71
+
view->_generic( name = `Page` ns = `sap.m`
72
+
)->_generic( name = `MultiComboBox` ns = `sap.m`
73
+
t_prop = VALUE #(
74
+
( n = `selectedKeys` v = `{/keys}` )
75
+
( n = `placeholder` v = `Pick one` )
76
+
)
77
+
)->_generic( name = `items` ns = `sap.m`
78
+
)->_generic( name = `core:Item` ns = `sap.ui.core`
79
+
t_prop = VALUE #(
80
+
( n = `key` v = `{key}` )
81
+
( n = `text` v = `{text}` )
82
+
) ).
83
+
84
+
client->view_display( view->stringify( ) ).
85
+
```
86
+
87
+
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.
88
+
89
+
::: tip Recommended for AI-assisted Development
90
+
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.
91
+
:::
92
+
93
+
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.
94
+
55
95
#### Next Steps
56
96
This produces a static view. The next section walks through binding and sharing data between the view and the app logic.
0 commit comments