docs: second clarity pass — beginner journey, code correctness, consistency

claude · claude · commit 7a0bb7e4b583 · 2026-07-04T14:16:53.000Z
- quickstart: state the endpoint URL (SICF Test Service), map the ABAP/ABAP Cloud tabs to system types, explain the Handler List step, how to launch your own class, abapGit prerequisite, and a naming tip (customer namespace vs. reserved Z2UI5_ prefix) - hello_world/full_example: explain why bound attributes must be public, the me->client pattern, shell( )/get_parent( ) and get( )-event vs get_event_arg( ) on first use - life_cycle: drop the false "used by every tutorial" claim and acknowledge the equivalent IF/ELSEIF dispatch used by the tutorials and samples - snippets: replace the non-compiling "sorting/filtering" table example (growing_threshold, sort_property/filter_property do not exist in the builder or sap.m.Column) with a real backend-sorting example - definition: fix Dialog cross-reference (Popup, not Popover) and the builder property naming rule (selectedkey, not selected_key) - binding: rename example class out of the reserved framework namespace - smaller fixes: LO→L0 template variable, misleading button label, Cookbook link target, ITS vs ITS Mobile, dispatch style unified within abap_sql page, changelog note on check_on_event status Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EC2cWJafPETwcMbh3NCsgH
diff --git a/docs/cookbook/eml_cds_sql/abap_sql.md b/docs/cookbook/eml_cds_sql/abap_sql.md
@@ -28,7 +28,7 @@ CLASS z2ui5_cl_sample_sql IMPLEMENTATION.
         INTO TABLE @mt_flights
         UP TO 50 ROWS.
 
-      DATA(view)  = z2ui5_cl_xml_view=>factory( )->page( ).
+      DATA(view)  = z2ui5_cl_xml_view=>factory( )->shell( )->page( ).
       DATA(table) = view->table( client->_bind( mt_flights ) ).
 
       table->columns(
@@ -55,17 +55,17 @@ ENDCLASS.
 
 Bind the search term with `_bind_edit( )` and re-run the `SELECT` on every `SEARCH` event:
 ```abap
-CASE abap_true.
+IF client->check_on_init( ).
 
-  WHEN client->check_on_init( ).
-    load_data( ).
-    render( ).
+  load_data( ).
+  render( ).
 
-  WHEN client->check_on_event( `SEARCH` ).
-    load_data( ).
-    client->view_model_update( ).
+ELSEIF client->check_on_event( `SEARCH` ).
 
-ENDCASE.
+  load_data( ).
+  client->view_model_update( ).
+
+ENDIF.
 ```
 
 ```abap
diff --git a/docs/cookbook/eml_cds_sql/cds.md b/docs/cookbook/eml_cds_sql/cds.md
@@ -3,7 +3,7 @@ outline: [2, 4]
 ---
 # CDS
 
-All examples in these docs work without CDS. But on a recent ABAP release, you can also use this feature in abap2UI5 apps.
+All examples in these docs work without CDS. On a recent ABAP release, you can also read data through CDS views in your abap2UI5 apps.
 
 ### ABAP CDS
 ABAP Core Data Services (CDS) let you define structured views and read data straight from the database. The example below fetches sales orders from the `I_SalesOrder` view of the Virtual Data Model (VDM) and shows them in a UI5 table:
diff --git a/docs/cookbook/eml_cds_sql/draft_handling.md b/docs/cookbook/eml_cds_sql/draft_handling.md
@@ -269,7 +269,7 @@ ENDMETHOD.
 `%is_draft = if_abap_behv=>mk-off` makes the read return the **active** row, not any open draft.
 
 #### 2. Entering Edit Mode — Check for an Existing Draft
-When the user clicks **Switch to Edit Mode**, the app first looks in the BO's draft-shadow table (here `cabnk_bank_d`) joined with `sdraft_admin` to find out whether a draft already exists for this key — and who owns it.
+When the user clicks **Switch to Edit Mode**, the app first looks in the BO's draft-shadow table (here `cabnk_bank_d`) joined with `sdraft_admin` to find out whether a draft already exists for this key — and who owns it. (Simplified here; the full snippet at the end of the page additionally reads the draft's timestamp.)
 ```abap
 METHOD check_existing_draft.
   SELECT SINGLE a~created_by, a~last_changed_at
diff --git a/docs/cookbook/eml_cds_sql/fuzzy_search.md b/docs/cookbook/eml_cds_sql/fuzzy_search.md
@@ -61,7 +61,7 @@ CLASS z2ui5_cl_sample_fuzzy IMPLEMENTATION.
     DATA(tab)  = view->table( client->_bind( mt_customers ) growing = abap_true ).
 
     tab->header_toolbar( )->overflow_toolbar(
-        )->title( `Customers`
+        )->title( `Customer List`
         )->toolbar_spacer( )
         )->search_field(
             value       = client->_bind_edit( mv_search )
diff --git a/docs/cookbook/event_navigation/frontend.md b/docs/cookbook/event_navigation/frontend.md
@@ -44,7 +44,7 @@ METHOD z2ui5_if_app~main.
 
     client->view_display( z2ui5_cl_xml_view=>factory(
         )->button(
-            text  = `post`
+            text  = `open new tab`
             press = client->_event_client(
                 val   = client->cs_event-open_new_tab
                 t_arg = VALUE #( ( `https://github.com/abap2UI5` ) ) )
diff --git a/docs/cookbook/event_navigation/life_cycle.md b/docs/cookbook/event_navigation/life_cycle.md
@@ -3,7 +3,7 @@ outline: [2, 4]
 ---
 # Life Cycle
 
-Every request enters the `main` method. `CASE abap_true` dispatches between initialization, navigation returns, and user events using `client->check_on_init( )`, `client->check_on_event( 'EVENT_NAME' )`, and `client->check_on_navigated( )`. Each branch either does the work inline (tiny apps) or calls a named handler method (typical apps) — the **structure is always the same**.
+Every request enters the `main` method. `CASE abap_true` dispatches between initialization, navigation returns, and user events using `` client->check_on_init( ) ``, `` client->check_on_event( `EVENT_NAME` ) ``, and `` client->check_on_navigated( ) ``. Each branch either does the work inline (tiny apps) or calls a named handler method (typical apps) — the **structure is always the same**.
 
 ```abap
 CLASS z2ui5_cl_demo_app_001 DEFINITION PUBLIC.
@@ -42,10 +42,10 @@ CLASS z2ui5_cl_demo_app_001 IMPLEMENTATION.
 ENDCLASS.
 ```
 
-Three things make this the recommended shape, used by every tutorial in this guide:
+Whether you dispatch with `CASE abap_true` (as above) or with an equivalent `IF` / `ELSEIF` chain (as the [Hello World](/get_started/hello_world) and [Full Example](/get_started/full_example) tutorials do) is a matter of taste — the structure is what counts. Three things make this the recommended shape:
 
 1. **Store `client` on `me->client`** so handler methods can use it without passing it around.
-2. **Dispatch by event name** — `check_on_event( 'POST' )` rather than a generic `check_on_event( )` followed by a second `CASE`. Each event gets its own `WHEN`.
+2. **Dispatch by event name** — `` check_on_event( `POST` ) `` rather than a generic `` CASE client->get( )-event `` with a second dispatch level. Each event gets its own `WHEN`. (With many events or extracted handler methods, the `CASE client->get( )-event` form is a fine alternative — the [Full Example](/get_started/full_example) uses it.)
 3. **One render method per view** — call it from any `WHEN` that should rebuild the screen (`check_on_init`, after a search, after a navigation return). Event handlers that only mutate state and reuse the existing view (a button press inside a popup, a toast) skip it — see [The View Is Only Sent When You Call `view_display`](#the-view-is-only-sent-when-you-call-view-display) below.
 
 For a tiny app with one or two events, inline the view and the handler directly in the `WHEN` branches and skip the handler methods entirely. [Hello World](/get_started/hello_world) shows this variant; [Full Example](/get_started/full_example) shows the full version with multiple handler methods, a popup, and persistence. Both follow the same pattern — only the amount of code inside each branch differs.
diff --git a/docs/cookbook/expert_more/snippets.md b/docs/cookbook/expert_more/snippets.md
@@ -174,12 +174,12 @@ CLASS z2ui5_cl_app_table_basic IMPLEMENTATION.
 ENDCLASS.
 ```
 
-## Table with Filtering, Sorting
+## Table with Sorting
 
-Enable UI5's built-in column sorting and filtering by setting `sortProperty` and `filterProperty` on each column header. The `p13n` settings expose the personalization icon.
+`sap.m.Table` has no built-in column sorting — in abap2UI5, sorting (and filtering) is backend work: react to an event, `SORT` the internal table in ABAP, and push the new order to the rendered view with `view_model_update`. No re-render needed:
 
 ```abap
-CLASS z2ui5_cl_app_table_p13n DEFINITION PUBLIC.
+CLASS z2ui5_cl_app_table_sort DEFINITION PUBLIC.
 
   PUBLIC SECTION.
     INTERFACES z2ui5_if_app.
@@ -193,7 +193,7 @@ CLASS z2ui5_cl_app_table_p13n DEFINITION PUBLIC.
 
 ENDCLASS.
 
-CLASS z2ui5_cl_app_table_p13n IMPLEMENTATION.
+CLASS z2ui5_cl_app_table_sort IMPLEMENTATION.
   METHOD z2ui5_if_app~main.
 
     IF client->check_on_init( ).
@@ -206,22 +206,28 @@ CLASS z2ui5_cl_app_table_p13n IMPLEMENTATION.
           ) INTO TABLE rows.
       ENDDO.
 
-      DATA(view) = z2ui5_cl_xml_view=>factory( )->page( `Sortable / Filterable Table` ).
+      DATA(view) = z2ui5_cl_xml_view=>factory( )->page( `Sortable Table` ).
 
       DATA(tab) = view->table(
-          items                = client->_bind( rows )
-          growing              = abap_true
-          growing_threshold    = `10`
-          mode                 = `MultiSelect`
-          sticky               = `ColumnHeaders` ).
+          items            = client->_bind( rows )
+          growing          = abap_true
+          growingthreshold = `10`
+          sticky           = `ColumnHeaders` ).
+
+      tab->header_toolbar( )->toolbar(
+          )->title( `Orders`
+          )->toolbar_spacer(
+          )->button(
+              text  = `Sort by Name`
+              press = client->_event( `SORT_NAME` )
+          )->button(
+              text  = `Sort by Status`
+              press = client->_event( `SORT_STATUS` ) ).
 
       tab->columns(
-          )->column( sort_property = `ID`     filter_property = `ID`
-              )->text( `ID` )->get_parent(
-          )->column( sort_property = `NAME`   filter_property = `NAME`
-              )->text( `Name` )->get_parent(
-          )->column( sort_property = `STATUS` filter_property = `STATUS`
-              )->text( `Status` ).
+          )->column( )->text( `ID` )->get_parent(
+          )->column( )->text( `Name` )->get_parent(
+          )->column( )->text( `Status` ).
 
       tab->items( )->column_list_item( )->cells(
           )->text( `{ID}`
@@ -230,6 +236,16 @@ CLASS z2ui5_cl_app_table_p13n IMPLEMENTATION.
 
       client->view_display( view->stringify( ) ).
 
+    ELSEIF client->check_on_event( `SORT_NAME` ).
+
+      SORT rows BY name.
+      client->view_model_update( ).
+
+    ELSEIF client->check_on_event( `SORT_STATUS` ).
+
+      SORT rows BY status.
+      client->view_model_update( ).
+
     ENDIF.
 
   ENDMETHOD.
diff --git a/docs/cookbook/model/binding.md b/docs/cookbook/model/binding.md
@@ -9,15 +9,15 @@ In abap2UI5, there are two ways to share data between your ABAP code and the UI5
 Use one-way binding to show data on the frontend without allowing edits. The `client->_bind` method sends data to the frontend and binds it to the view:
 
 ```abap
-CLASS z2ui5_cl_app_hello_world DEFINITION PUBLIC.
+CLASS zcl_app_hello_world DEFINITION PUBLIC.
 
   PUBLIC SECTION.
     INTERFACES z2ui5_if_app.
     DATA name TYPE string.
 
 ENDCLASS.
 
-CLASS z2ui5_cl_app_hello_world IMPLEMENTATION.
+CLASS zcl_app_hello_world IMPLEMENTATION.
   METHOD z2ui5_if_app~main.
 
     client->view_display( z2ui5_cl_xml_view=>factory(
@@ -35,15 +35,15 @@ This method works with tables, trees, and other nested data structures — see [
 When users need to edit data, use two-way binding to keep it in sync with the ABAP backend. Call the `client->_bind_edit` method — after an event, the framework syncs the data back to your ABAP class:
 
 ```abap
-CLASS z2ui5_cl_app_hello_world DEFINITION PUBLIC.
+CLASS zcl_app_hello_world DEFINITION PUBLIC.
 
   PUBLIC SECTION.
     INTERFACES z2ui5_if_app.
     DATA name TYPE string.
 
 ENDCLASS.
 
-CLASS z2ui5_cl_app_hello_world IMPLEMENTATION.
+CLASS zcl_app_hello_world IMPLEMENTATION.
   METHOD z2ui5_if_app~main.
 
     client->view_display( z2ui5_cl_xml_view=>factory(
diff --git a/docs/cookbook/view/definition.md b/docs/cookbook/view/definition.md
@@ -5,7 +5,7 @@ outline: [2, 4]
 
 abap2UI5 uses [SAP UI5](https://sapui5.hana.ondemand.com) on the frontend without modification. Whatever your ABAP code sends to the browser is a **standard UI5 XML view** — the same XML you would write in any UI5 freestyle project.
 
-The consequence: **everything in the UI5 SDK works in abap2UI5 1:1**. Any control, any property, any namespace from the [UI5 Demo Kit](https://sapui5.hana.ondemand.com/sdk) is available. Copy the XML, paste it into your ABAP class, and it renders.
+The consequence: **everything in the UI5 SDK works in abap2UI5 1:1 when you write the XML directly**. Any control, any property, any namespace from the [UI5 Demo Kit](https://sapui5.hana.ondemand.com/sdk) is available. Copy the XML, paste it into your ABAP class, and it renders.
 
 #### Sending a View
 
@@ -94,7 +94,7 @@ The UI5 SDK is large. The table below covers the choices that come up in almost
 | Multi-select dropdown             | `sap.m.MultiComboBox`                                 | Pills appear inside the field.                                                     |
 | Date / time input                 | `sap.m.DatePicker` / `sap.m.TimePicker` / `sap.m.DateTimePicker` | Needs a formatter — see [Binding → Data-Type Mapping](/cookbook/model/binding#data-type-mapping). |
 | Status indicator                  | `sap.m.ObjectStatus`                                  | Colored text + icon for state.                                                     |
-| Modal dialog                      | `sap.m.Dialog` (built with `factory_popup`)           | See [Popover](/cookbook/popup_popover/popover).                                    |
+| Modal dialog                      | `sap.m.Dialog` (built with `factory_popup`)           | See [Popup](/cookbook/popup_popover/popup).                                        |
 
 When two controls fit, prefer the simpler one: `Table` over `TreeTable`, `SimpleForm` over `Form`, `Select` over `ComboBox`. Switch to the richer variant only when a concrete requirement justifies it.
 
@@ -103,7 +103,7 @@ When two controls fit, prefer the simpler one: `Table` over `TreeTable`, `Simple
 `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:
 
 - Control names follow snake_case of the UI5 control class — `sap.m.MultiComboBox` becomes `->multi_combo_box( )`, `sap.m.Text` becomes `->text( )`.
-- Properties are passed as named parameters in snake_case (`enabled`, `placeholder`, `selected_key`).
+- Properties are passed as named parameters, lowercased without underscores (`enabled`, `placeholder`, `selectedkey`, `growingthreshold`). Only the *method* names use snake_case (e.g. `multi_combo_box`).
 - 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.
 - 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.
 
diff --git a/docs/cookbook/view/xml_templating.md b/docs/cookbook/view/xml_templating.md
@@ -111,7 +111,7 @@ DATA(lo_view_nested) = z2ui5_cl_xml_view=>factory( ).
 lo_view_nested->shell( )->page( `Nested View`
   )->table( client->_bind( mt_data )
   )->columns(
-    )->template_repeat( list = `{template>/MT_LAYOUT}` var = `LO`
+    )->template_repeat( list = `{template>/MT_LAYOUT}` var = `L0`
       )->column( ... ) " ...
 
 client->nest_view_display( val           = lo_view_nested->stringify( )
diff --git a/docs/get_started/about.md b/docs/get_started/about.md
@@ -20,7 +20,7 @@ CLASS zcl_my_app IMPLEMENTATION.
 ENDCLASS.
 ```
 
-That's it — your first UI5 app is ready.
+That's it — your first UI5 app is ready. (`client` is the single parameter of `main`, passed in by the framework — explained on the [Hello World](/get_started/hello_world) page.)
 
 ### Background
 Since launching in 2023, abap2UI5 has grown from a small side project into a community-driven framework used by ABAP developers worldwide. The framework absorbs frontend complexity, so you can focus on business logic with your existing ABAP skills.
diff --git a/docs/get_started/full_example.md b/docs/get_started/full_example.md
@@ -58,7 +58,7 @@ CLASS zcl_app_full_example DEFINITION PUBLIC.
 ENDCLASS.
 ```
 
-The `main` method is a pure dispatcher — the same pattern as in [Hello World](/get_started/hello_world), just with the branches extracted into methods:
+The `main` method is a pure dispatcher — the same pattern as in [Hello World](/get_started/hello_world), just with the branches extracted into methods. We stash `client` in a protected attribute first, so the handler methods below can use it without passing it around:
 
 ```abap
   METHOD z2ui5_if_app~main.
@@ -77,6 +77,8 @@ The `main` method is a pure dispatcher — the same pattern as in [Hello World](
 
 `view_display` builds the entire screen: a form with the selection criteria on top and the result table below. It is called exactly once, on the first roundtrip — every later interaction only updates data on this view.
 
+Two things are new compared to Hello World: `shell( )` wraps the page in the standard UI5 app frame, and the `navbuttonpress` / `shownavbutton` parameters add a back button when the app was called from another app (details under [Navigation](/cookbook/event_navigation/navigation)). Further down, `get_parent( )` moves one level back up in the builder tree, so the next `column( )` becomes a sibling instead of a child — see [View → Definition](/cookbook/view/definition).
+
 The two date pickers and the customer input use `_bind_edit`, so whatever the user types travels back to the ABAP attributes automatically. The table uses read-only `_bind` since the rows are only displayed:
 
 ```abap
@@ -304,6 +306,8 @@ CLASS zcl_app_full_example IMPLEMENTATION.
 
   METHOD on_event.
 
+    " client->get( )-event holds the name passed to _event( );
+    " get_event_arg( ) returns the extra argument attached via t_arg
     CASE client->get( )-event.
       WHEN `READ`.
         data_read( ).
diff --git a/docs/get_started/hello_world.md b/docs/get_started/hello_world.md
@@ -114,7 +114,7 @@ Use the lifecycle checks to tell these phases apart:
 Each `check_*` method returns `abap_true` only for its own phase, so the `IF`/`ELSEIF` chain acts as a dispatcher.
 
 ### Data Flow
-Finally, add a public attribute and bind it to an input field to send data back to the server:
+Finally, add a public attribute and bind it to an input field to send data back to the server. The attribute must be in the `PUBLIC SECTION` — the framework accesses it dynamically and silently ignores private or protected attributes (full rules on the [Binding](/cookbook/model/binding) page):
 ```abap
 CLASS zcl_app_hello_world DEFINITION PUBLIC.
   PUBLIC SECTION.
diff --git a/docs/get_started/next.md b/docs/get_started/next.md
@@ -17,7 +17,7 @@ The samples evolve all the time. Have one to share? Open a PR so others can lear
 :::
 
 #### Development
-Build views, handle events, share data, and work with tables. The [Cookbook](/cookbook/event_navigation/life_cycle) walks through the patterns you need for everyday work — start with the Life Cycle page.
+Build views, handle events, share data, and work with tables. The [Cookbook](/cookbook/overview) walks through the patterns you need for everyday work — start with the [Life Cycle](/cookbook/event_navigation/life_cycle) page.
 
 #### Configuration
 Before going live, set up security, performance tuning, Launchpad integration, and more. Start with the [Configuration guide](/configuration/setup).
diff --git a/docs/get_started/quickstart.md b/docs/get_started/quickstart.md
@@ -5,7 +5,7 @@ outline: [2, 4]
 
 ### 1. Installation via abapGit
 
-Install [abap2UI5](https://github.com/abap2UI5/abap2UI5) with [abapGit](https://abapgit.org):
+Install [abap2UI5](https://github.com/abap2UI5/abap2UI5) with [abapGit](https://abapgit.org). (New to abapGit? Install it first — see [abapGit](/technical/tools/abapgit); it's the one-time tool used to pull abap2UI5 into your system.)
 
 ![abapGit repository installation screen for abap2UI5](/get_started/image.png)
 
@@ -14,7 +14,7 @@ Install [abap2UI5](https://github.com/abap2UI5/abap2UI5) with [abapGit](https://
 :::
 
 ### 2. Set Up HTTP Handler and Service
-Create a package and define an HTTP handler class:
+Create a package and define an HTTP handler class. Use the **ABAP** tab for Standard ABAP systems (R/3 NetWeaver, S/4 On-Premise / Private Cloud); use the **ABAP Cloud** tab only on BTP ABAP Environment or S/4 Public Cloud:
 
 ::: code-group
 
@@ -45,7 +45,7 @@ ENDCLASS.
 ```
 :::
 
-Next, use transaction `SICF` to set up an HTTP service that uses the handler above:
+Next, use transaction `SICF` to create an HTTP service and enter your handler class in the service's **Handler List** tab, then activate the node:
 
 ![SICF service creation dialog in transaction SICF](https://github.com/user-attachments/assets/b76d9459-79be-40e1-a00e-b4e8cbbab9d4) <br>
 ![HTTP handler class assignment in SICF service configuration](/get_started/image-5.png)
@@ -61,7 +61,7 @@ abap2UI5 talks only to the HTTP service you define, giving you full control over
 :::
 
 ### 3. First Launch
-Open the HTTP endpoint in your browser:
+Open the HTTP endpoint in your browser — in `SICF`, right-click your service node and choose **Test Service** (the URL looks like `https://<host>:<port>/sap/bc/<your_service>`). This startup page is also where you will launch your own apps later:
 <img width="800" alt="abap2UI5 startup page with check button and test app launcher" src="https://github.com/user-attachments/assets/c8962298-068d-4efb-a853-c44a9b9cda56">
 Press `check` to verify your installation, then launch the bundled test app to confirm everything works. That's it — you can now build your own abap2UI5 apps.
 
@@ -79,4 +79,8 @@ CLASS zcl_my_app IMPLEMENTATION.
   ENDMETHOD.
 ENDCLASS.
 ```
-Launch your app in place of the test app — and that's it: you've built your first abap2UI5 app.
+Back on the startup page, enter your class name `ZCL_MY_APP` in the input field and launch it — that's it: you've built your first abap2UI5 app.
+
+::: tip **Naming**
+Name your own apps in your customer namespace (`Z...`/`Y...`). The `Z2UI5_` prefix is reserved for the framework and its samples.
+:::
diff --git a/docs/resources/changelog.md b/docs/resources/changelog.md
diff --git a/docs/technical/technology/overview.md b/docs/technical/technology/overview.md
diff --git a/docs/technical/tools/open_abap.md b/docs/technical/tools/open_abap.md
