Reorganize documentation structure for events and controller

docs/.vitepress/config.mjs

@@ -60,7 +60,7 @@ export default defineConfig({
         text: "Guide",
         items: [
           { text: "Introduction", link: "/get_started/about" },
-          { text: "Cookbook", link: "/development/general" },
+          { text: "Cookbook", link: "/development/controller/life_cycle" },
           { text: "Configuration", link: "/configuration/setup" },
           { text: "Advanced Topic", link: "/advanced/downporting" },
           { text: "Technical Insight", link: "/technical/concept" },
@@ -114,10 +114,20 @@ export default defineConfig({
       },
       {
         text: "Cookbook",
-        link: "/development/general",
+        link: "/development/controller/life_cycle",
         collapsed: true,
         items: [
-          { text: "Controller", link: "/development/general" },
+          {
+            text: "Controller",
+            link: "/development/controller/life_cycle",
+            collapsed: true,
+            items: [
+              { text: "Life Cycle", link: "/development/controller/life_cycle" },
+              { text: "Init", link: "/development/controller/init" },
+              { text: "Event", link: "/development/controller/event" },
+              { text: "Navigated", link: "/development/controller/navigated" },
+            ],
+          },
           {
             text: "View",
             collapsed: true,
@@ -137,12 +147,22 @@ export default defineConfig({
               { text: "OData", link: "/development/model/odata" },
             ],
           },
-          { text: "Event", link: "/development/events" },
+          {
+            text: "Event",
+            link: "/development/events/backend",
+            collapsed: true,
+            items: [
+              { text: "Backend", link: "/development/events/backend" },
+              { text: "Frontend", link: "/development/events/frontend" },
+              { text: "Follow-up", link: "/development/events/follow_up" },
+            ],
+          },
           {
             text: "Navigation",
-            link: "/development/navigation/navigation",
+            link: "/development/navigation/inner_cross_app",
             collapsed: true,
             items: [
+              { text: "Inner, Cross App", link: "/development/navigation/inner_cross_app" },
               { text: "App State", link: "/development/navigation/app_state" },
               {
                 text: "Share, Bookmark",
@@ -158,10 +178,9 @@ export default defineConfig({
               { text: "Message", link: "/development/messages/messages" },
               { text: "Error", link: "/development/messages/errors" },
               { text: "Logging", link: "/development/messages/logging" },
-              { text: "CL_DEMO_OUTPUT", link: "/development/specific/demo_output" },
+              { text: "Translation, i18n", link: "/development/translation" },
             ],
           },
-          { text: "Translation, i18n", link: "/development/translation" },
           {
             text: "Popup, Popover",
             link: "/development/popups/popup",
@@ -213,6 +232,13 @@ export default defineConfig({
               { text: "Lock", link: "/development/specific/locks" },
               { text: "Statefulness", link: "/development/specific/statefulness" },
               { text: "Logout", link: "/configuration/logout" },
+              {
+                text: "More",
+                collapsed: true,
+                items: [
+                  { text: "Demo Output", link: "/development/specific/demo_output" },
+                ],
+              },
             ],
           },
         ],
@@ -228,7 +254,7 @@ export default defineConfig({
           { text: "Authorization", link: "/configuration/authorization" },
           { text: "Performance", link: "/configuration/performance" },
           { text: "UI5 Version", link: "/configuration/ui5_versions" },
-          { text: "Productive Usage", link: "/configuration/productive_usage" },
+          { text: "Production Use", link: "/configuration/productive_usage" },
           { text: "Debugging", link: "/configuration/troubleshooting" },
           { text: "Fiori Launchpad", link: "/configuration/launchpad" },
           {
@@ -239,7 +265,7 @@ export default defineConfig({
                 text: "S/4 Public Cloud",
                 link: "/configuration/s4_public_cloud",
               },
-              { text: "BTP ABAP Env", link: "/configuration/btp_abap_env" },
+              { text: "BTP ABAP Environment", link: "/configuration/btp_abap_env" },
               { text: "Build Work Zone", link: "/configuration/btp" },
               { text: "Mobile Start", link: "/configuration/mobile_start" },
             ],
@@ -253,8 +279,8 @@ export default defineConfig({
         items: [
           { text: "Downporting", link: "/advanced/downporting" },
           { text: "Renaming", link: "/advanced/renaming" },
-          { text: "Builder", link: "/advanced/builds" },
-          { text: "Local", link: "/advanced/local" },
+          { text: "Build Process", link: "/advanced/builds" },
+          { text: "Local Setup", link: "/advanced/local" },
           { text: "RFC Connector", link: "/advanced/rfc" },
           { text: "HTTP Connector", link: "/advanced/http" },
           { text: "Fiori Elements Integration", link: "/advanced/fiori" },
@@ -267,7 +293,7 @@ export default defineConfig({
                 text: "User Exit",
                 link: "/advanced/extensibility/user_exits",
               },
-              { text: "Custom JS", link: "/advanced/extensibility/custom_js" },
+              { text: "Custom JavaScript", link: "/advanced/extensibility/custom_js" },
               { text: "Frontend", link: "/advanced/extensibility/frontend" },
               {
                 text: "Custom Control",
@@ -300,14 +326,15 @@ export default defineConfig({
           {
             text: "Technology",
             link: "/technical/technology/overview",
+            collapsed: true,
             items: [
               { text: "RAP", link: "/technical/technology/rap" },
               { text: "UI5 Freestyle", link: "/technical/technology/ui5" },
             ],
           },
           {
             text: "Tool",
-            collapsed: false,
+            collapsed: true,
             items: [
               { text: "abapGit", link: "/technical/tools/abapgit" },
               { text: "ajson", link: "/technical/tools/ajson" },

docs/configuration/launchpad.md

@@ -16,6 +16,16 @@ Use these parameters for target mapping in your Launchpad configuration:
 - ID: `z2ui5`
 - Parameter: `app_start / Z2UI5_CL_MY_APP`
 
+### Cross App Navigation
+We recommend backend communication only for view changes or popup calls. With a Launchpad, consider navigating via the Launchpad to use browser navigation and history:
+```abap
+client->_event_client(
+    val   = client->cs_event-cross_app_nav_to_ext
+    t_arg = VALUE #( (
+        `{ semanticObject: "Z2UI5_CL_LP_SAMPLE_04",  action: "display" }`
+    ) ) ).
+```
+
 ### Troubleshooting
 Sometimes installation via abapGit causes cache-related issues. Here's how to clear them:
 

docs/development/controller/controller.md

@@ -0,0 +1,4 @@
+---
+outline: [2, 4]
+---
+# Controller

docs/development/controller/event.md

@@ -0,0 +1,29 @@
+---
+outline: [2, 4]
+---
+# Event
+
+`client->check_on_event` returns `abap_true` when the request was triggered by a user event. Read the event name with `client->get( )-event` and dispatch to the matching handler.
+
+```abap
+  METHOD z2ui5_if_app~main.
+
+    me->client = client.
+    CASE abap_true.
+      WHEN client->check_on_event( ).
+        on_event( ).
+    ENDCASE.
+
+  ENDMETHOD.
+
+  METHOD on_event.
+
+    DATA(lt_arg) = client->get_event_arg( ).
+
+    CASE client->get( )-event.
+      WHEN `BUTTON_POST`.
+        client->message_toast_display( |{ mv_value } - send to the server| ).
+    ENDCASE.
+
+  ENDMETHOD.
+```

docs/development/controller/init.md

@@ -0,0 +1,41 @@
+---
+outline: [2, 4]
+---
+# Init
+
+`client->check_on_init` returns `abap_true` on the first request. Use this branch to initialize app data and render the initial view.
+
+```abap
+  METHOD z2ui5_if_app~main.
+
+    me->client = client.
+    CASE abap_true.
+      WHEN client->check_on_init( ).
+        on_init( ).
+        display_view( ).
+    ENDCASE.
+
+  ENDMETHOD.
+
+  METHOD on_init.
+
+    mv_value  = `value`.
+
+  ENDMETHOD.
+
+  METHOD display_view.
+
+    DATA(view) = z2ui5_cl_xml_view=>factory( ).
+    view->shell( )->page(
+        )->simple_form( title = `Form Title` editable = abap_true
+                   )->content( `form`
+                       )->title( `Input`
+                       )->label( `value`
+                       )->input( client->_bind_edit( mv_value )
+                       )->button(
+                           text  = `post`
+                           press = client->_event( `BUTTON_POST` ) ).
+    client->view_display( view->stringify( ) ).
+
+  ENDMETHOD.
+```

docs/development/general.md → docs/development/controller/life_cycle.md

@@ -1,11 +1,11 @@
 ---
 outline: [2, 4]
 ---
-# Controller
+# Life Cycle
 
 abap2UI5 gives you great flexibility in how you structure apps. Most sample apps follow the pattern below. Use it as a starting point, and tweak it or build a wrapper around abap2UI5 for more specific behavior.
 
-The idea: every request enters the `main` method, and you use `CASE` to dispatch between initialization, navigation returns, and user events.
+The idea: every request enters the `main` method, and you use `CASE` to dispatch between initialization, navigation returns, and user events. The recommended pattern uses `CASE abap_true` together with `client->check_on_init`, `client->check_on_event`, and `client->check_on_navigated` to dispatch to the matching handler method.
 
 ```abap
 CLASS z2ui5_cl_demo_app_001 DEFINITION PUBLIC.
@@ -45,45 +45,7 @@ CLASS z2ui5_cl_demo_app_001 IMPLEMENTATION.
 
   ENDMETHOD.
 
-  METHOD on_init.
-
-    mv_value  = `value`.
-
-  ENDMETHOD.
-
-  METHOD display_view.
-
-    DATA(view) = z2ui5_cl_xml_view=>factory( ).
-    view->shell( )->page(
-        )->simple_form( title = `Form Title` editable = abap_true
-                   )->content( `form`
-                       )->title( `Input`
-                       )->label( `value`
-                       )->input( client->_bind_edit( mv_value )
-                       )->button(
-                           text  = `post`
-                           press = client->_event( `BUTTON_POST` ) ).
-    client->view_display( view->stringify( ) ).
-
-  ENDMETHOD.
-
-  METHOD on_event.
-
-    DATA(lt_arg) = client->get_event_arg( ).
-
-    CASE client->get( )-event.
-      WHEN `BUTTON_POST`.
-        client->message_toast_display( |{ mv_value } - send to the server| ).
-    ENDCASE.
-
-  ENDMETHOD.
-
-  METHOD on_navigated.
-
-    DATA(lo_app_prev) = client->get_app_prev( ).
-
-  ENDMETHOD.
-
 ENDCLASS.
 ```
+
 See the dedicated sections of this development guide for full details on views, events, data binding, and navigation.

docs/development/controller/navigated.md

@@ -0,0 +1,24 @@
+---
+outline: [2, 4]
+---
+# Navigated
+
+`client->check_on_navigated` returns `abap_true` when the user returns from another app. Use `client->get_app_prev` to access the previous app instance and read any data it returns.
+
+```abap
+  METHOD z2ui5_if_app~main.
+
+    me->client = client.
+    CASE abap_true.
+      WHEN client->check_on_navigated( ).
+        on_navigated( ).
+    ENDCASE.
+
+  ENDMETHOD.
+
+  METHOD on_navigated.
+
+    DATA(lo_app_prev) = client->get_app_prev( ).
+
+  ENDMETHOD.
+```