Merge pull request #120 from abap2UI5/claude/documentation-clarity-1oqk7y

Documentation improvements and consistency updates

Author: oblomov-dev

docs/advanced/addons.md

@@ -5,7 +5,7 @@ outline: [2, 4]
 
 abap2UI5 focuses on core capabilities — rendering views, handling events, and exchanging data. This keeps the framework lean and easy to maintain. The real strength lies in the ecosystem: **ready-to-use add-ons and community projects** that extend abap2UI5 for specific needs.
 
-#### Add-ons
+#### Available Add-ons
 
 Browse the [abap2UI5-addons](https://github.com/abap2UI5-addons) organization to find what you need. Features include:
 - Layout variant handling, similar to classic SAP GUI selection screens or ALV reports

docs/advanced/agent.md

@@ -54,10 +54,10 @@ ENDCLASS.
 ```abap
 IF client->check_on_init( ).            " first call
   " load data + render view
+ELSEIF client->check_on_navigated( ).   " returned from a called sub-app (nav_app_call), incl. built-in popup apps
+  " refresh state
 ELSEIF client->check_on_event( `POST` ). " user fired event 'POST'
   " handle it
-ELSEIF client->check_on_navigated( ).   " returned from sub-app / popup
-  " refresh state
 ENDIF.
 ```
 
@@ -101,8 +101,8 @@ Translate any UI5 XML example from the [UI5 SDK](https://sapui5.hana.ondemand.co
 | UI5 XML | ABAP with `z2ui5_cl_util_xml` |
 |---|---|
 | `<Button text="Send" />` | `->__( n = `Button` a = `text` v = `Send` )` |
-| `press="onPress"` | `v = client->_event( `BUTTON_POST` )` |
-| `value="{/name}"` | `v = client->_bind_edit( name )` |
+| `press="onPress"` | `a = `press` v = client->_event( `BUTTON_POST` )` |
+| `value="{/name}"` | `a = `value` v = client->_bind_edit( name )` |
 | `<FeedInput><actions>…</actions></FeedInput>` | `->_( `FeedInput` )->_( `actions` )->__( … )` |
 
 Builder methods:
@@ -135,7 +135,7 @@ CLASS zcl_app_xxx DEFINITION PUBLIC.
 
     METHODS on_init.        " first call: load data, render view
     METHODS on_event.       " user triggered an event
-    METHODS on_navigation.  " returned from sub-app or popup
+    METHODS on_navigation.  " returned from a sub-app called via nav_app_call
     METHODS view_display.   " build and render the view
     METHODS data_read.      " SELECT
     METHODS data_update.    " INSERT / UPDATE / DELETE

docs/advanced/builds.md

@@ -3,12 +3,12 @@ outline: [2, 4]
 ---
 # Builder
 
-For heavy abap2UI5 use, consider building your own version by defining a custom namespace and including the add-ons you need:
+If you run abap2UI5 in production or across several systems, consider building your own version — a release under a custom namespace that includes exactly the add-ons and frontend components you need:
 - Use abap2UI5 in the `z2ui5` namespace for improvements and pull requests, and keep a separate namespace for your production version.
 - Install multiple instances of abap2UI5 and upgrade each one at its own pace.
 - Build a custom abap2UI5 release with frontend components and add-ons matched to your needs.
 
-#### Builder
+#### The Builder Tool
 Make your own abap2UI5 build with the [builder](https://github.com/abap2UI5/builder).
 
 <img width="700" alt="abap2UI5 builder interface for generating custom namespaced builds" src="https://github.com/user-attachments/assets/7c7f55d4-6667-4036-bc71-4cd7472f2ae9" />

docs/advanced/downporting.md

@@ -14,5 +14,17 @@ To install on an older system, use the `702` branch:
 
 Some sample projects and other repositories also ship a downported version. Check whether a `702` branch is available.
 
-#### Functionality
-For more on the downport feature, see the blog post [Running abap2UI5 on older R/3 Releases](https://www.linkedin.com/pulse/running-abap2ui5-older-r3-releases-downport-compatibility-abaplint-mjkle).
+#### How It Works
+The `702` branch is not maintained by hand — it is **generated** from `main` by an automated GitHub Actions workflow on every change. The pipeline runs [abaplint](https://abaplint.org)'s downport rule (`abaplint --fix` with a 7.02 target configuration), which rewrites modern syntax into 7.02-compatible equivalents, for example:
+
+- inline declarations `DATA(x) = ...` → separate `DATA` statements
+- constructor expressions (`VALUE #( )`, `NEW #( )`, `CONV #( )`) → classic statements
+- `xsdbool( )` → `boolc( )`
+- string templates → concatenation where needed
+
+A few small compatibility fix-ups follow (e.g. replacing exception types that don't exist on old releases), and the result is committed to the `702` branch. Because the transformation is fully automatic, the downported version stays feature-identical with `main` — you never wait for a manual backport.
+
+The same mechanism runs in this project's CI (`npm run auto_downport`) to guarantee every change on `main` stays downportable.
+
+#### Further Reading
+Background article: [Running abap2UI5 on older R/3 Releases](https://www.linkedin.com/pulse/running-abap2ui5-older-r3-releases-downport-compatibility-abaplint-mjkle).

docs/advanced/extensibility/custom_control.md

@@ -9,7 +9,7 @@ First, set up your VS Code environment with the abap2UI5 frontend artifacts, fol
 
 #### Frontend
 
-Write the JS code for your new custom control. Copy an existing control from [App.controller.js](https://github.com/abap2UI5/abap2UI5/blob/main/app/webapp/controller/App.controller.js) and adapt it.
+Write the JavaScript for your new custom control. Each custom control lives in its own file under [app/webapp/cc/](https://github.com/abap2UI5/abap2UI5/tree/main/app/webapp/cc) — copy an existing one (e.g. `Timer.js`) and adapt it to your needs.
 
 #### Backend
 Extend the custom control view class by adding a method and defining the new control's properties:

docs/advanced/extensibility/frontend.md

@@ -9,15 +9,14 @@ The abap2UI5 frontend artifacts live in the `app` folder. To adjust them:
 Open VS Code (or your editor of choice), then run in the terminal:
 ```sh
 git clone https://github.com/abap2UI5/abap2UI5
-cd app
+cd abap2UI5/app
 ```
-Next replace `<<system>>` and let all three files point to your ABAP backend system:
+Next replace `<<system>>` in the three config files — `ui5.yaml`, `ui5-local.yaml` and `ui5-mock.yaml` — so they all point to your ABAP backend system:
 
 <img width="400" alt="Frontend config files where the backend system URL must be replaced" src="https://github.com/user-attachments/assets/155c9a3f-8a0a-494b-8fc4-a4bba2bf0e90">
 
 #### Build & Test
-Set the backend system in the YAML files.<br>
-Replace `/sap/bc/z2ui5` with your endpoint in the manifest, then run:
+If your HTTP service uses a different path, also replace `/sap/bc/z2ui5` with your endpoint in the manifest. Then run:
 ```sh
 npm i
 npm run start-noflp

docs/advanced/fiori.md

@@ -42,7 +42,7 @@ sap.ui.core.Component.create({
 				oVBox.addItem(oCompContainer);
 
 				//Overwrite default height of object page section
-				var oSection = that.getView().byId("[This is the ID of your object page section::Section]");
+				var oSection = that.getView().byId("<your-object-page-section-id>"); // replace with the ID of your object page section
 				oSection.addStyleClass("customSectionHeight");
 
 			});
@@ -66,15 +66,21 @@ sap.ui.core.Component.create({
 
 5. Create abap2UI5 app class
 
-On the ABAP side, the app receives the Fiori startup parameters (like the app class name and any custom key-value pairs) via `client->get( )-t_comp_params`. The `check_initialized` flag ensures the parameters are read only once, on the first roundtrip. Setting `backgrounddesign = 'List'` gives the page a white background matching the Fiori object page:
+On the ABAP side, the app receives the Fiori startup parameters (like the app class name and any custom key-value pairs) via `client->get( )-t_comp_params`. The `check_initialized` flag — a public `abap_bool` attribute of the app class — ensures the parameters are read only once, on the first roundtrip. Setting `backgrounddesign = 'List'` gives the page a white background matching the Fiori object page:
 ```abap
+  " class definition:
+  " PUBLIC SECTION.
+  "   INTERFACES z2ui5_if_app.
+  "   DATA check_initialized TYPE abap_bool.
+
   METHOD z2ui5_if_app~main.
 
     IF check_initialized = abap_false.
       check_initialized = abap_true.
 
 * ---------- Get startup parameters ---------------------------------------------------------------
       DATA(lt_startup_params) = client->get( )-t_comp_params.
+      " ... evaluate the startup parameters here
 
     ENDIF.
 

docs/advanced/http.md

@@ -18,12 +18,12 @@ The system that calls the app (the frontend system) ships with the UI5 library a
 
 #### Installation
 
-_Prerequisite: Set up an SM59 HTTP destination pointing to the source system. Install abap2UI5 on both systems._
+_Prerequisite: Set up an SM59 HTTP destination pointing to the backend system (the system that runs the apps). Install abap2UI5 on both systems._
 
 Steps:
 1. Install the [abap2UI5 HTTP Connector](https://github.com/abap2UI5-addons/http-connector) via abapGit on both systems
-2. In the HTTP handler, configure the destination to point to your source system
-3. In your browser, call the endpoint of the HTTP Connector
+2. In the HTTP handler, configure the destination to point to the backend system
+3. In your browser, call the HTTP Connector's endpoint on the frontend system (the ICF service installed with the connector — analogous to `.../sap/bc/2ui5_rfc` for the RFC Connector)
 
 #### Further Information
 For the latest details, source code, and updates, see the [HTTP Connector repository on GitHub](https://github.com/abap2UI5-addons/http-connector).

docs/advanced/local.md

@@ -3,6 +3,6 @@ outline: [2, 4]
 ---
 # Local
 
-abap2UI5-local is a special build that bundles all artifacts into a single HTTP handler. Create one extra database table, and you can run abap2UI5 independently of any other installation on the system.
+abap2UI5-local is a special build that bundles all framework classes into a single HTTP handler class. Besides that, you only need to create one additional database table. This gives you a self-contained copy of abap2UI5 that runs independently of any other abap2UI5 installation on the same system.
 
 For full details, see the repository: [abap2UI5-local](https://github.com/abap2UI5/abap2UI5-local)

docs/advanced/renaming.md

@@ -10,9 +10,22 @@ The entire abap2UI5 project lives under the `z2ui5` namespace. You may need to r
 
 abap2UI5 works with the abaplint renaming feature and supports namespaces up to 9 characters, e.g., `zabap2ui5`.
 
-#### Functionality
-For more on renaming ABAP artifacts, see:
-[Automagic standalone renaming of ABAP objects](https://community.sap.com/t5/application-development-blog-posts/automagic-standalone-renaming-of-abap-objects/ba-p/13499851)
+#### How It Works
+[abaplint](https://abaplint.org) can rename ABAP artifacts across a whole repository: you define rename patterns (old name → new name, including regular expressions) in an abaplint configuration, and `abaplint --rename` rewrites every class, interface, and reference consistently, writing the result to an output folder:
 
-For more background, see the blog post:
-[Renaming of ABAP Artifacts - The Power of abaplint and abapGit in ABAP Development](https://www.linkedin.com/pulse/renaming-abap-artifacts-power-abaplint-github-actions-development-kqede/).
+```jsonc
+"rename": {
+  "output": "output",
+  "patterns": [
+    { "type": "CLAS|INTF", "oldName": "z2ui5(.*)", "newName": "zmyns$1" }
+  ]
+}
+```
+
+The renamed copy is a complete, installable abapGit project under your own namespace — install it side by side with the original, pin it to a release, or ship it inside your product. The abap2UI5 CI runs this transformation on every change (`npm run rename`, workflow `test_rename.yaml`) to guarantee the codebase stays renameable.
+
+For a ready-made pipeline that builds a renamed release with your chosen add-ons included, see the [Builder](/advanced/builds).
+
+#### Further Reading
+- [Automagic standalone renaming of ABAP objects](https://community.sap.com/t5/application-development-blog-posts/automagic-standalone-renaming-of-abap-objects/ba-p/13499851)
+- [Renaming of ABAP Artifacts — The Power of abaplint and abapGit in ABAP Development](https://www.linkedin.com/pulse/renaming-abap-artifacts-power-abaplint-github-actions-development-kqede/)