Add explanatory text to 12 documentation pages with unexplained code

Context paragraphs added before code snippets in fiori.md, xlsx.md,
translation.md, custom_js.md, demo_output.md, barcodes.md, device.md,
app_state.md, user_exits.md, btp.md, authorization.md, and launchpad.md.
Each addition explains what the code does, which APIs are used, and
when/why the pattern is needed.

https://claude.ai/code/session_01AaA4EMw83KMzGP6kaDZPJU

Author: claude

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.
 

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

@@ -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_lp_kpi_hello_world'
 ```

docs/development/model/device.md

@@ -3,9 +3,11 @@ outline: [2, 4]
 ---
 # Device Model
 
+abap2UI5 offers two ways to access device information: directly in the view via the UI5 device model (frontend), or by collecting it in ABAP attributes via a custom control (backend).
+
 ### Frontend
 
-The device model is bound to the view by default with the name `device`. You can access it easily in your view. For example:
+The device model is bound to the view by default with the name `device`. You can use standard UI5 binding syntax to display device properties directly — no backend roundtrip needed. For example:
 ```abap
 page->input( 
   description = `device model - resize - width` 
@@ -14,7 +16,7 @@ page->input(
 Explore all available parameters in the [UI5 Documentation.](https://sapui5.hana.ondemand.com/sdk/#/api/sap.ui.Device)
 
 ### Backend
-You can also retrieve detailed device information on the backend using a custom info frontend control. This allows you to access UI5 version, device type, OS, browser details, and screen dimensions. Below is an example implementation, which demonstrates how to collect and use this information:
+If you need device information in your ABAP logic (e.g. to adapt behavior based on the browser or screen size), use the `info_frontend` custom control. It collects the values on the frontend and sends them back to the backend via two-way binding (`_bind_edit`). Once the `finished` event fires, all bound attributes are populated and available in ABAP:
 ```abap
 CLASS z2ui5_cl_sample_device DEFINITION PUBLIC.
 

docs/development/navigation/app_state.md

@@ -3,7 +3,9 @@
 abap2UI5 supports saving the current app state so you can return to it later -- similar to how standard UI5 applications handle state management.
 
 ### Usage
-Each state is saved as a draft with a unique ID, you can display this ID in the URL using the `client->set_app_state_active` method. This command generates a URL that you can copy and paste into another browser window. An example URL looks like this: <br>
+Each state is saved as a draft with a unique ID. Calling `client->set_app_state_active` appends this ID as a hash fragment to the URL. The resulting URL is shareable — you can copy it and open it in another browser window (or send it to a colleague) to restore the exact same app state. The hash value (`z2ui5-xapp-state=...`) is a server-side key that references the persisted draft. Drafts expire after a configurable time (default: 4 hours, adjustable via [User Exits](/advanced/extensibility/user_exits)).
+
+An example URL looks like this: <br>
 `.../sap/bc/z2ui5?sap-client=001&app_start=z2ui5_cl_demo_app_000#/z2ui5-xapp-state=024251849E5A1EDFB1DAE2C97C8CE8C2`
 
 ### Sample Code

docs/development/specific/barcodes.md

@@ -49,7 +49,9 @@ This feature is only available when using the UI5 framework and is not supported
 #### Focus Handling
 Most scanner devices have an integrated scanning function. In such cases, you can create an input field and ensure that focus is properly set. The scanned data will populate the input field as if it were typed via a keyboard.
 
-Here’s an example that demonstrates how to handle input focus and manage transitions between fields after scanning and pressing ENTER:
+The key mechanism is the `_z2ui5()->focus()` custom control, which accepts a bound `focus_id` attribute. When the user presses ENTER (triggering the `submit` event), the backend updates `focus_id` to the next input field's ID and calls `view_model_update` — the framework then automatically moves focus to the corresponding field on the frontend:
+
+Here's an example that demonstrates how to handle input focus and manage transitions between fields after scanning and pressing ENTER:
 
 ```abap
 CLASS z2ui5_cl_sample_focus DEFINITION PUBLIC.

docs/development/specific/demo_output.md

@@ -2,7 +2,11 @@
 
 If you're familiar with `CL_DEMO_OUTPUT` from classic ABAP, you can display its HTML output inside an abap2UI5 app as well. This is handy for quick data visualization or when migrating existing demo code.
 
-The approach: generate the HTML with `cl_demo_output=>get( )`, inject CSS styles via `_cc_plain_xml`, and render the result with the `html` control:
+The approach: generate the HTML with `cl_demo_output=>get( )`, inject CSS styles via `_cc_plain_xml` (which inserts raw XML/HTML into the view), and render the result with the UI5 `html` control. The CSS block is needed because `CL_DEMO_OUTPUT` produces HTML with specific class names (e.g. `heading1`, `header`, `body`) that require matching style definitions to display correctly.
+
+::: tip
+This technique is best suited for prototyping or migrating existing demo programs. For production apps, consider building proper UI5 views instead.
+:::
 
 ```abap
 METHOD z2ui5_if_app~main.