Merge pull request #40 from abap2UI5/claude/review-docs-snippets-ab7yz

optimize language and add explanations

Author: oblomov-dev

docs/advanced/extensibility/custom_js.md

@@ -7,14 +7,14 @@ If the standard UI5 framework functionalities do not fulfill all your requiremen
 
 The idea is to send the custom JavaScript function along with the view to the frontend and invoke it later when an event is triggered.
 
-Below is a working example that you can use as a starting point:
+Below is a working example that you can use as a starting point. The `_generic` method creates an arbitrary XML/HTML element — here an HTML `<script>` tag (namespace `html`). The `_cc_plain_xml` method injects raw content into that element, in this case the JavaScript function definition. On the backend side, `client->follow_up_action` then executes the function by name on the frontend:
 
 ```abap
   METHOD z2ui5_if_app~main.
 
   IF client->check_on_init( ).
       DATA(view) = z2ui5_cl_xml_view=>factory( ).
-      view->_generic( name = `script` ns = `html` 
+      view->_generic( name = `script` ns = `html`
         )->_cc_plain_xml(
           |function myFunction() \{ console.log( `Hello World` ); \}| 
         ).

docs/advanced/extensibility/user_exits.md

@@ -2,7 +2,11 @@
 
 abap2UI5 contains predefined user exits which can be used to modify the standard behavior. The user exits are exposed by the interface [`Z2UI5_IF_EXIT`](https://github.com/abap2UI5/abap2UI5/blob/main/src/02/z2ui5_if_exit.intf.abap). To use them in your system you have to create a new class which implements the interface and its methods. They're called dynamically by abap2UI5 class [`Z2UI5_CL_EXIT`](https://github.com/abap2UI5/abap2UI5/blob/main/src/02/z2ui5_cl_exit.clas.abap). You should **not** include your class into abap2UI5 packages but in any other custom package.
 
-The following example changes the title, theme and the time drafts are saved in the backend:
+The interface provides two exit methods:
+* **`set_config_http_get`** — called during the initial HTTP GET request (page load). Use it to customize frontend settings like the page title, UI5 theme, or UI5 version.
+* **`set_config_http_post`** — called on every subsequent HTTP POST request (each roundtrip). Use it to configure backend behavior like the draft expiration time.
+
+Both methods receive a `cs_config` changing parameter whose fields you can set as needed. The following example changes the title, theme and the time drafts are saved in the backend:
 
 ```abap
 CLASS zcl_a2ui5_user_exit DEFINITION PUBLIC.

docs/advanced/fiori.md

@@ -65,6 +65,8 @@ sap.ui.core.Component.create({
 ```
 
 5. Create abap2UI5 app class
+
+On the ABAP side, the app receives the Fiori startup parameters (such as the app class name and any custom key-value pairs) via `client->get( )-t_comp_params`. The `check_initialized` flag ensures the parameters are only read once on the first roundtrip. Setting `backgrounddesign = 'List'` gives the page a white background that blends in with the Fiori object page:
 ```abap
   METHOD z2ui5_if_app~main.
 

docs/configuration/authorization.md

@@ -9,7 +9,7 @@ abap2UI5 offers flexible ways to manage authorization handling. It doesn't inclu
 One of the easiest ways to manage access to different apps is by implementing checks within the HTTP handler. This approach lets you restrict access to individual apps based on the APP_START parameter, directly in the ICF service handler class.
 
 ##### Example: Restricting Access Based on URL Parameters
-In this example, we use the ICF handler class to control which apps can be accessed based on the APP_START parameter in the HTTP request. If an unauthorized app is requested, access is denied.
+In this example, we use the ICF handler class to control which apps can be accessed based on the APP_START parameter in the HTTP request. The `get_header_field( 'APP_START' )` method reads the URL query parameter that specifies which abap2UI5 app class to launch. If an unauthorized app is requested, access is denied.
 ```abap
 CLASS z2ui5_cl_launchpad_handler DEFINITION PUBLIC.
 
@@ -36,7 +36,7 @@ CLASS z2ui5_cl_launchpad_handler IMPLEMENTATION.
 ENDCLASS.
 ```
 ##### Example: Authorization Objects in Service Handlers
-You can also use the SAP authorization objects:
+You can also combine this with SAP authorization objects. The example below uses a custom authorization object `Z_APP_AUTH` with a field `APP` — you need to create this object in transaction `SU21` and assign it to the relevant roles in your system:
 ```abap
 CLASS z2ui5_cl_launchpad_handler DEFINITION PUBLIC.
 
@@ -85,8 +85,8 @@ CLASS z2ui5_cl_app IMPLEMENTATION.
 
   METHOD z2ui5_if_app~main.
     " Perform an authorization check before launching the app
-    AUTHORITY-CHECK OBJECT 'Z_APP_AUTH'
-                    ID 'APP' FIELD 'Z2UI5_APP_001'.
+    AUTHORITY-CHECK OBJECT `Z_APP_AUTH`
+                    ID `APP` FIELD `Z2UI5_APP_001`.
 
     IF sy-subrc <> 0.
       " Authorization failed, deny access

docs/configuration/btp.md

@@ -24,8 +24,12 @@ Integrate your abap2UI5 apps into BTP Services like Build Workzone. Find all inf
 
 ##### Additional Properties
 
-* HTML5.DynamicDestination true 
-* product.name ABAP System 
-* sap-client (client) 
-* WebIDEEnabled true 
-* WebIDEUsage odata_abap,dev_abap
+These properties are required by SAP Build Work Zone to correctly route requests to your ABAP backend:
+
+| Property | Value | Description |
+|---|---|---|
+| HTML5.DynamicDestination | `true` | Allows HTML5 apps to resolve this destination at runtime |
+| product.name | `ABAP System` | Identifies the backend type for the Work Zone tile configuration |
+| sap-client | *(your client number)* | The SAP system client to connect to (e.g. `001`) |
+| WebIDEEnabled | `true` | Enables the destination for SAP Business Application Studio |
+| WebIDEUsage | `odata_abap,dev_abap` | Declares supported protocols for development tools |

docs/configuration/launchpad.md

@@ -25,15 +25,15 @@ Sometimes, installation via abapGit can cause cache-related issues. Here's how t
 #### Cache Management
 
 1. Recalculate app index of z2ui5 with report /UI5/APP_INDEX_CALCULATE
-![389816897-f18e791e-1e07-4381-a8a8-deb5af3ec02c](https://github.com/user-attachments/assets/50c505ab-c58e-46a6-999e-67c4e4cdb929)
-![389816886-093d087f-4d7d-48b3-b7c4-75c16046af5b](https://github.com/user-attachments/assets/81f8feae-fcfe-4175-aa91-28ce8d681539)
+![App index calculation report selection screen](https://github.com/user-attachments/assets/50c505ab-c58e-46a6-999e-67c4e4cdb929)
+![App index calculation report output](https://github.com/user-attachments/assets/81f8feae-fcfe-4175-aa91-28ce8d681539)
 
 2. Recalculate index of distribution layer with report /UI5/APP_INDEX_CALCULATE (if tab isn't visible try switching to another tab, then it usually appears)
-![389817086-2a480005-f9f9-46e8-a432-456494957665](https://github.com/user-attachments/assets/3fce0f2e-96f9-4487-9226-7940336582b1)
-![389817130-389f2be1-d75b-4dbb-aa81-e5b5e4202440](https://github.com/user-attachments/assets/dc149874-6731-496d-90bf-79cb83d8c97d)
+![Distribution layer tab in app index calculation report](https://github.com/user-attachments/assets/3fce0f2e-96f9-4487-9226-7940336582b1)
+![Distribution layer recalculation output](https://github.com/user-attachments/assets/dc149874-6731-496d-90bf-79cb83d8c97d)
 
 3. Invalidate http caches in transaction SMICM
-![389817432-f6568b5e-0588-4a98-83cc-f1bd58e0dd64](https://github.com/user-attachments/assets/497b7677-8009-472e-9b50-34719105a12e)
+![HTTP cache invalidation in transaction SMICM](https://github.com/user-attachments/assets/497b7677-8009-472e-9b50-34719105a12e)
 
 4. Clear browser caches and hard reload
 
@@ -59,7 +59,9 @@ Find more information in the blog article on [LinkedIn.](https://www.linkedin.co
 <br>
 
 #### Approach
-(1/3) Use a single Interface:
+The integration works in three steps: you implement a simple interface, the Launchpad calls a generic OData proxy service, and the proxy delegates to your ABAP class to calculate the KPI count.
+
+(1/3) Implement the `z2ui5_if_lp_kpi` interface. The `count` method receives an optional `filter` string (from the OData `$filter` parameter) and returns the KPI value as an integer:
 ```abap
 INTERFACE z2ui5_if_lp_kpi
   PUBLIC.
@@ -72,7 +74,7 @@ INTERFACE z2ui5_if_lp_kpi
 
 ENDINTERFACE.
 ```
-(2/3) Which can be used on app level to return KPIs:
+(2/3) Implement the interface in your app class alongside `z2ui5_if_app`. The `count` method contains your custom KPI calculation logic (e.g. counting open items from the database):
 ```abap
 CLASS z2ui5_cl_lp_kpi_hello_world DEFINITION PUBLIC.
 
@@ -95,7 +97,7 @@ CLASS z2ui5_cl_lp_kpi_hello_world IMPLEMENTATION.
 
 ENDCLASS.
 ```
-(3/3) A generic OData service takes care of everything else (which just returns n dummy entries). Just maintain the KPI at the Launchpad with the following endpoint:
+(3/3) A generic OData proxy service (`Z2UI5_PROXY_KPI_SRV`) handles the rest. It receives the `$filter` parameter containing your class name, instantiates the class, calls `count`, and returns that many dummy OData entries. The Launchpad displays the `$count` result as the tile KPI. Configure the tile with this endpoint:
 ```
-.../sap/opu/odata/sap/Z2UI5_PROXY_KPI_SRV/ENTITYCollection/$count?$filter=CLASS eq 'z2ui5_cl_proxy_kpi_hello_world'
+.../sap/opu/odata/sap/Z2UI5_PROXY_KPI_SRV/ENTITYCollection/$count?$filter=CLASS eq 'z2ui5_cl_lp_kpi_hello_world'
 ```

docs/configuration/performance.md

@@ -10,10 +10,38 @@ Frontend logic is kept to a minimum: no business logic runs in the browser. Ever
 
 abap2UI5 has been successfully tested with tables containing large numbers of entries and columns. So, you can confidently develop your app — performance shouldn't be a concern.
 
+### view_display vs view_model_update
+
+The most impactful optimization is choosing the right update method:
+
+- **`client->view_display( )`** — sends a new XML view and model to the frontend. UI5 destroys the current view and creates a new one from scratch. Use this only on initialization or when the view structure changes.
+- **`client->view_model_update( )`** — sends only updated model data. UI5 refreshes the existing view via data binding — only the changed controls are re-rendered. This preserves UI state (scroll position, focus, etc.) and is significantly faster.
+
+```abap
+METHOD z2ui5_if_app~main.
+
+  CASE abap_true.
+
+    WHEN client->check_on_init( ).
+      DATA(view) = z2ui5_cl_xml_view=>factory(
+        )->page( `My App`
+        )->text( client->_bind( mv_text )
+        )->button( text = `update` press = client->_event( `UPDATE` ) ).
+      client->view_display( view->stringify( ) ).
+
+    WHEN client->check_on_event( `UPDATE` ).
+      mv_text = `new value`.
+      client->view_model_update( ).
+
+  ENDCASE.
+
+ENDMETHOD.
+```
+
 ### Suggestions
 Want to optimize your app even more? Here are a few tips:
-* Only call the `client->view_display` method when necessary. Instead, prefer using `client->model_update` so the UI5 framework only re-renders the controls that have actually changed
-* Prefer using `client->bind` and use `client->bind_edit` only when users need to make changes that are processed in the backend. Otherwise, it leads to unnecessary data transfers
+* Only call `client->view_display` when necessary. Prefer `client->view_model_update` so the UI5 framework only re-renders controls that have actually changed
+* Prefer `client->_bind` and use `client->_bind_edit` only when users need to make changes that are processed in the backend. Otherwise, it leads to unnecessary data transfers
 * Declare public attributes in your app class only for variables displayed in the frontend. This helps prevent the framework from accessing unused values
 * Follow standard ABAP best practices, such as reducing loops and using sorted tables, as you would in any other ABAP development project
 

docs/configuration/productive_usage.md

@@ -18,7 +18,7 @@ The project will be continuously further developed, so there's no specific "stab
 
 #### Transport
 Install the project using abapGit into your development system. Then, use the normal transport process for deployment to production:
-![alt text](image-3.png){ width=80% }
+![Transport process from development to production via abapGit](image-3.png){ width=80% }
 
 #### Renaming
 If you're starting new development but already have abap2UI5 apps running in production, and you're worried about updating to the latest release, consider installing abap2UI5 multiple times in your system using the [renaming feature](/advanced/renaming). This way, you can safely continue development without affecting your existing apps in production.

docs/configuration/troubleshooting.md

@@ -13,7 +13,7 @@ On the frontend, abap2UI5 behaves like a standard UI5 app, so you can use all ty
 
 ##### Debugging Tools
 To begin, press `Ctrl+F12` to open the built-in debugger tools in abap2UI5
-![alt text](debug.png)
+![Built-in debugger showing XML View and Data Model inspection](debug.png)
 Here, you can inspect the XML View and check the Data Model bound to the view.
 
 ##### UI5 Inspector

docs/development/events.md

@@ -22,69 +22,76 @@ METHOD z2ui5_if_app~main.
 
     CASE client->get( )-event.
         WHEN `BUTTON_POST`.
-            client->message_box_display( |Your name is { name }| ).
+            client->message_box_display( `The button was pressed` ).
     ENDCASE.
  
 ENDMETHOD.
 ```
-If the backend needs additional information about the specific event, use parameters like `$event`, `$source`, and `$params` to send further details. Use the t_arg parameter to include these details. Check out [this documentation](https://openui5.hana.ondemand.com/#/topic/b0fb4de7364f4bcbb053a99aa645affe) for more information, and refer to sample `Z2UI5_CL_DEMO_APP_167`.
+If the backend needs additional information about the specific event, use the `t_arg` parameter to include additional details. Three special prefixes are available:
+
+- **`$source`** — the UI5 control that triggered the event (e.g. `${$source>/text}` returns the button text)
+- **`$parameters`** — the event parameters as defined by the UI5 control (e.g. `${$parameters>/id}` returns the element ID)
+- **`$event`** — the UI5 event object itself (e.g. `$event>sId` returns the event type like `press`)
+
+Check out [this documentation](https://openui5.hana.ondemand.com/#/topic/b0fb4de7364f4bcbb053a99aa645affe) for more information, and refer to sample `Z2UI5_CL_DEMO_APP_167`.
 
 #### Source
-Send properties of the event source control to the backend:
+Send properties of the event source control to the backend. The syntax `${$source>/text}` reads the `text` property from the UI5 control that fired the event — here the button itself, so the result is the button's label (`post`):
 ```abap
 METHOD z2ui5_if_app~main.
 
     client->view_display( z2ui5_cl_xml_view=>factory(
-        )->button( text = `post` press = client->_event( 
-            val = `BUTTON_POST` 
-            t_arg = VALUE #( ( `${$source>/text}` ) ) ) 
+        )->button( text = `post` press = client->_event(
+            val = `BUTTON_POST`
+            "reads button text → result: "post"
+            t_arg = VALUE #( ( `${$source>/text}` ) ) )
         )->stringify( ) ).
- 
+
     CASE client->get( )-event.
       WHEN `BUTTON_POST`.
           client->message_box_display( |The button text is { client->get_event_arg( ) }| ).
     ENDCASE.
- 
+
 ENDMETHOD.
 ```
 
 #### Parameters
-Retrieve parameters of the event:
+Retrieve parameters of the event. The syntax `${$parameters>/id}` reads the `id` parameter from the event's parameter map — UI5 generates a qualified ID like `mainView--button_id`:
 ```abap
 METHOD z2ui5_if_app~main.
 
     client->view_display( z2ui5_cl_xml_view=>factory(
-        )->button( text = `post` id = `button_id` press = client->_event( 
-            val = `BUTTON_POST` 
-            t_arg = VALUE #( ( `${$parameters>/id}` ) ) ) 
+        )->button( text = `post` id = `button_id` press = client->_event(
+            val = `BUTTON_POST`
+            "reads event parameter 'id' → result: "mainView--button_id"
+            t_arg = VALUE #( ( `${$parameters>/id}` ) ) )
         )->stringify( ) ).
- 
+
     CASE client->get( )-event.
         WHEN `BUTTON_POST`.
-            "mainView--button_id
             client->message_box_display( |The button id is { client->get_event_arg( ) }| ).
     ENDCASE.
- 
+
 ENDMETHOD.
 ```
 
 #### Event
-Retrieve specific properties of the event:
+Retrieve specific properties of the event object. The syntax `$event>sId` accesses the `sId` attribute of the UI5 event — here it returns the event type name (`press`). Note: no `${...}` wrapper here because `$event` directly references the event object:
 ```abap
 METHOD z2ui5_if_app~main.
 
     client->view_display( z2ui5_cl_xml_view=>factory(
-        )->button( text = `post` press = client->_event( 
-            val = `BUTTON_POST` 
-            t_arg = VALUE #( ( `$event>sId` ) ) ) 
+        )->button( text = `post` press = client->_event(
+            val = `BUTTON_POST`
+            "reads event object attribute → result: "press"
+            t_arg = VALUE #( ( `$event>sId` ) ) )
         )->stringify( ) ).
- 
+
     CASE client->get( )-event.
         WHEN `BUTTON_POST`.
-            "press
             client->message_box_display( |The event id is { client->get_event_arg( ) }| ).
     ENDCASE.
- 
+
 ENDMETHOD.
 ```
 ::: warning
@@ -127,7 +134,14 @@ This is just a demonstration. In this case, it would be easier to access `name`
 :::
 
 ### Frontend
-If you don't want to process the event in the backend, you can also directly trigger actions at the frontend. The following frontend events are available:
+If you don't want to process the event in the backend, you can directly trigger actions at the frontend using `client->_event_client`. The difference between the two methods:
+
+- **`client->_event( )`** — triggers a backend roundtrip, the event is processed in the `main` method
+- **`client->_event_client( )`** — executes an action directly in the browser, no backend call
+
+To use a frontend event on a UI5 control property (like `press`), wrap `_event_client` inside `_event`. To execute a frontend event after backend processing, pass `_event_client` to `client->follow_up_action`.
+
+The following frontend events are available:
 ```abap
   CONSTANTS:
     BEGIN OF cs_event,