Review main Merged

67464[FEATURE] Introduce backend module web component router

Benjamin Franzke CR +2 V +2 Hard +648 −74 updated 04/30/21, 16:22

Commit message

A custom Lit-based web componenent router is added which
reflects module URLs into the browser adress bar and
at the same time prepares for native web components to
be used as future iframe module alternatives.

Such modules will be implemented as JavaScript modules,
that provide an implementation for a custom HTML Web
Component. The first of such components (added within
this change) is a wrapper component for traditional
iframe-based backend modules.

Module state changes are advertised via DOM events and
propagated to the browser address bar, browser title,
and the module menu.

Adress bar updates
==================

The module URL to address bar synchronisation enables sharable
module deeplinks to be copied from the browser address bar.
Whenever a component advertises a state change (e.g.
iframe change), a sharable deep link is generated and
shown in the browser adressbar.

Technical preparation for the required deeplinking has been
added with #93674.

History Management
==================

Browser history state is managed via the iframe
history context of the content module frame
(that is unlike other modern Single Page Applications
which use history.pushState and history.replaceState).

This approach required some synchronisation work, but there are
technical limitations that prevent a combination of iframe history
updates in combination for newer API like history.pushState.
(The limitation is: state added by history.pushState is skipped
by iframe history handling).

The advantage of this compromise is: All "traditional" modules will
preserve their state handling as before, no breaking/behavioral
changes for iframe-based modules.

Routing
=======

The router uses two parameters to perform routing:
 * module – Module name as defined in ext_tables.php
 * endpoint – (json) api to be used by the component (= module URL)
The module attribute is used to perform the actual routing
to the respective backend module component, while the endpoint
attribute serves as API to parse/fetch the state of the module.

A named slot is used to switch between the available module components.
That means only one of the routers childNodes will be visible at a
time, while all modules are actively attached to the DOM.
State is therefore preserved when switching between modules
and the iframe is always kept active, allowing to act as history
state-container (as described in "History Management").

Example of two modules that are attached to the DOM, where
only <typo3-configuration-module> is visible as the <slot>
in the shadow root puts a reference to this childNode:

<typo3-backend-module-router module="system_config" endpoint="…">
  #shadow-root
    <slot name="TYPO3/CMS/Lowlevel/ConfigurationModule"></slot>
  <typo3-iframe-module endpoint="…"
    slot="TYPO3/CMS/Backend/Module/Iframe"></…>
  <typo3-configuration-module endpoint="…"
    slot="TYPO3/CMS/Lowlevel/ConfigurationModule"></…>
</typo3-backend-module-router>

Note: The "TYPO3/CMS/Lowlevel/ConfigurationModule" component is not
yet part of this commit, and only serves as an example (will be
implemented later on). The slot name is resolved from
the module key.

Out of scope for this patch (will follow later)
===============================================

 * Link based routing interception via data-module tag for anchor tags.
   To be added as an additional convenience API on top of the
   router module and endpoint attribute (current API).
 * Convenience components for module layout
 * Integration into shortcut handler
 * Install-tool URLs do not reflect into addressbar right now
   Install-tool modules are redirected, therefore url updates can not
   be mapped as backend URLs right now
   Solution will probably be to integrate the install tool
   components as web component into the backend.

Review

  • Code review CR +2 Done
    • Benjamin Franzke +2
    • Oli Bartsch +1
    • Andreas Kienast +1
  • Verified V +2 Done
    • Benjamin Franzke +2
    • Oli Bartsch +1
    • Andreas Kienast +1
    • core-ci +1 CI

Issues 2

Files 24

Show 4 more files

Review log 5196

Show 3371 earlier messages
  1. Benjamin Franzke uploaded patch set 1 01/19/21, 14:46

  2. TYPO3com voted on patch set 1 V -1 01/19/21, 14:56 Completed build in 10m 13s on Tue, 19 Jan, 02:56 PM Test Summary: 79 of 32836 failed Find logs and detail information at https://bamboo.typo3.com/browse/CORE-GTC-8915

  3. Benjamin Franzke uploaded patch set 2 01/19/21, 15:08

  4. TYPO3com voted on patch set 2 V -1 01/19/21, 15:20 Completed build in 12m 10s on Tue, 19 Jan, 03:20 PM Test Summary: 79 of 32836 failed Find logs and detail information at https://bamboo.typo3.com/browse/CORE-GTC-8917

  5. Benjamin Franzke uploaded patch set 3 01/19/21, 19:00

  6. TYPO3com voted on patch set 3 V -1 01/19/21, 19:11 Completed build in 11m 22s on Tue, 19 Jan, 07:11 PM Test Summary: 19 of 32837 failed Find logs and detail information at https://bamboo.typo3.com/browse/CORE-GTC-8923

  7. Benjamin Franzke uploaded patch set 4 01/23/21, 01:31

  8. TYPO3com voted on patch set 4 V -1 01/23/21, 01:40 Completed build in 08m 36s on Sat, 23 Jan, 01:40 AM Test Summary: 9 of 32842 failed Find logs and detail information at https://bamboo.typo3.com/browse/CORE-GTC-9014

  9. TYPO3com commented on patch set 4 01/23/21, 01:50 Completed build in 27m 16s on Sat, 23 Jan, 01:50 AM Test Summary: 9 of 32842 failed Find logs and detail information at https://bamboo.typo3.com/browse/CORE-GTC-9014

  10. Benjamin Franzke uploaded patch set 5 01/23/21, 07:43

  11. TYPO3com voted on patch set 5 V -1 01/23/21, 07:53 Completed build in 09m 43s on Sat, 23 Jan, 07:53 AM Test Summary: 4 of 32843 failed Find logs and detail information at https://bamboo.typo3.com/browse/CORE-GTC-9015

  12. TYPO3com voted on patch set 5 V +1 01/23/21, 08:17 Completed build in 43m 21s on Sat, 23 Jan, 08:17 AM Test Summary: 32601 passed Find logs and detail information at https://bamboo.typo3.com/browse/CORE-GTC-9015

  13. Benjamin Franzke uploaded patch set 6 01/23/21, 12:17

  14. TYPO3com voted on patch set 6 V -1 01/23/21, 12:27 Completed build in 10m 13s on Sat, 23 Jan, 12:27 PM Test Summary: 2 of 32842 failed Find logs and detail information at https://bamboo.typo3.com/browse/CORE-GTC-9016

  15. Benjamin Franzke uploaded patch set 7 01/23/21, 12:52

  16. TYPO3com voted on patch set 7 V +1 01/23/21, 13:02 Completed build in 09m 43s on Sat, 23 Jan, 01:02 PM Test Summary: 32601 passed Find logs and detail information at https://bamboo.typo3.com/browse/CORE-GTC-9017

  17. Oliver Hader commented on patch set 7 01/25/21, 19:45

    ModuleRouter.ts:27

    nitpick on structuring ESMs: Module/Router.ts instead?

    ModuleRouter.ts:59

    could we use `instanceof WhateverModuleElement` or is that still "dropped" on the way compiling these modules?
  18. Benjamin Franzke commented on patch set 7 01/28/21, 15:04

    ModuleRouter.ts:27 Reply

    Yea, fine be me. I tried to name according to ModuleMenu. But it's fine for me to structure this into Module/ as well. :+1: (Becuase there might be a `Module/Menu` at some point and `ModuleMenu` is then just a deprecated wrapper.)

    ModuleRouter.ts:59 Reply

    Yes, technically we could do that, but practically we don't have Custom Elements constructor available: a) because that would be the Element Class would need to be exported as default export b) because the tag name can be checked without having to wait for the module to be lazy loaded
  19. Benjamin Franzke wrote 02/09/21, 08:50

    Topic set to lit
  20. Benjamin Franzke uploaded patch set 8 03/06/21, 14:46

  21. TYPO3com voted on patch set 8 V +1 03/06/21, 14:53 Completed build in 06m 53s on Sat, 6 Mar, 02:53 PM Test Summary: 32745 passed Find logs and detail information at https://bamboo.typo3.com/browse/CORE-GTC-9880

  22. core-ci voted on patch set 8 V +1 03/06/21, 14:58 Core CI is happy: https://core.b13.com/typo3-core/typo3.cms/-/pipelines/1219

  23. Benjamin Franzke uploaded patch set 9 03/07/21, 08:32

  24. TYPO3com voted on patch set 9 V -1 03/07/21, 08:32 Completed build in 20s on Sun, 7 Mar, 08:32 AM Test Summary: No tests found Find logs and detail information at https://bamboo.typo3.com/browse/CORE-GTC-9896

  25. core-ci voted on patch set 9 V -1 03/07/21, 08:45 Core CI is not happy: https://core.b13.com/typo3-core/typo3.cms/-/pipelines/1238

  26. Benjamin Franzke uploaded patch set 10 03/09/21, 19:24

  27. TYPO3com voted on patch set 10 V -1 03/09/21, 19:25 Completed build in 19s on Tue, 9 Mar, 07:24 PM Test Summary: No tests found Find logs and detail information at https://bamboo.typo3.com/browse/CORE-GTC-9987

  28. core-ci voted on patch set 10 V -1 03/09/21, 19:26 Core CI is not happy: https://core.b13.com/typo3-core/typo3.cms/-/pipelines/1342

  29. Benjamin Franzke uploaded patch set 11 03/09/21, 19:31

  30. TYPO3com voted on patch set 11 V -1 03/09/21, 19:32 Completed build in 22s on Tue, 9 Mar, 07:32 PM Test Summary: No tests found Find logs and detail information at https://bamboo.typo3.com/browse/CORE-GTC-9990

  31. core-ci voted on patch set 11 V +1 03/09/21, 19:47 Core CI is happy: https://core.b13.com/typo3-core/typo3.cms/-/pipelines/1345

  32. Benjamin Franzke uploaded patch set 12 04/08/21, 11:51

  33. TYPO3com voted on patch set 12 V +1 04/08/21, 11:58 Completed build in 07m 26s on Thu, 8 Apr, 11:58 AM Test Summary: 33267 passed Find logs and detail information at https://bamboo.typo3.com/browse/CORE-GTC-10547

  34. core-ci voted on patch set 12 V +1 04/08/21, 12:06 Core CI is happy: https://core.b13.com/typo3-core/typo3.cms/-/pipelines/2107

  35. Benjamin Franzke uploaded patch set 13 04/08/21, 12:10

  36. Benjamin Franzke commented on patch set 13 04/08/21, 12:11

    ModuleRouter.ts:27 Reply

    Done
  37. TYPO3com voted on patch set 13 V +1 04/08/21, 12:18 Completed build in 07m 16s on Thu, 8 Apr, 12:18 PM Test Summary: 33267 passed Find logs and detail information at https://bamboo.typo3.com/browse/CORE-GTC-10551

  38. core-ci voted on patch set 13 V +1 04/08/21, 12:23 Core CI is happy: https://core.b13.com/typo3-core/typo3.cms/-/pipelines/2112

  39. Benjamin Franzke uploaded patch set 14 04/12/21, 16:06

  40. TYPO3com voted on patch set 14 V +1 04/12/21, 16:14 Completed build in 07m 39s on Mon, 12 Apr, 04:14 PM Test Summary: 33267 passed Find logs and detail information at https://bamboo.typo3.com/browse/CORE-GTC-10619

  41. core-ci voted on patch set 14 V +1 04/12/21, 16:22 Core CI is happy: https://core.b13.com/typo3-core/typo3.cms/-/pipelines/2196

  42. Benni Mack uploaded patch set 15 04/12/21, 21:28

  43. Benni Mack uploaded patch set 16 04/12/21, 21:30

  44. TYPO3com voted on patch set 15 V -1 04/12/21, 21:36 Completed build in 07m 49s on Mon, 12 Apr, 09:36 PM Test Summary: 33267 passed Find logs and detail information at https://bamboo.typo3.com/browse/CORE-GTC-10632

  45. TYPO3com voted on patch set 16 V +1 04/12/21, 21:37 Completed build in 06m 46s on Mon, 12 Apr, 09:37 PM Test Summary: 33267 passed Find logs and detail information at https://bamboo.typo3.com/browse/CORE-GTC-10633

  46. core-ci voted on patch set 15 V -1 04/12/21, 21:39 Core CI is not happy: https://core.b13.com/typo3-core/typo3.cms/-/pipelines/2210

  47. core-ci voted on patch set 16 V +1 04/12/21, 21:45 Core CI is happy: https://core.b13.com/typo3-core/typo3.cms/-/pipelines/2211

  48. Benni Mack commented on patch set 16 04/13/21, 11:15

    Main.html:22

    personally, I found the naming confusing. I think it's actually the wrapper for the Content Container, and not just bound to modules (finally).
  49. Benjamin Franzke uploaded patch set 17 04/17/21, 07:40

    Rebase
  50. TYPO3com voted on patch set 17 V +1 04/17/21, 07:47 Completed build in 07m 07s on Sat, 17 Apr, 07:47 AM Test Summary: 33273 passed Find logs and detail information at https://bamboo.typo3.com/browse/CORE-GTC-10703

  51. core-ci voted on patch set 17 V +1 04/17/21, 07:54 Core CI is happy: https://core.b13.com/typo3-core/typo3.cms/-/pipelines/2302

  52. Benjamin Franzke uploaded patch set 18 04/19/21, 05:10

  53. TYPO3com voted on patch set 18 V +1 04/19/21, 05:18 Completed build in 08m 23s on Mon, 19 Apr, 05:18 AM Test Summary: 33273 passed Find logs and detail information at https://bamboo.typo3.com/browse/CORE-GTC-10710

  54. core-ci voted on patch set 18 V +1 04/19/21, 05:23 Core CI is happy: https://core.b13.com/typo3-core/typo3.cms/-/pipelines/2315

  55. Oliver Hader commented on patch set 18 04/19/21, 08:39

    Router.ts:103

    So, that's "using the event object as DTO", correct? Since modifying the event won't have an impact on any other event handler...

    Router.ts:153

    Per default that seems to be `typo3-iframe-module` slot, as define in Fluid template. When would that be different → probably, please add a short description here

    Router.ts:170

    In general, I'd suggest to use web API here as well: * properly parsing URL parts * properly decoding/encoding URL components ('&ampersands=%26%26%26') ``` const url = new URL(state.url); const params = new URLSearchParams(url.search); if (params.has('token')) { ... } ```
  56. Benjamin Franzke commented on patch set 18 04/23/21, 05:13

    Router.ts:103 Reply

    Yes, it's used s DTO. But the change actually has an effect on outer event handlers (the intention is to notify the ModuleMenu event handler about the new module state, e.g. when navigating with browser back-button between modules). Here is a quick demo how a middle-event-handler can modify event data and thus act as a middleware: const outer = document.createElement('div'), modifier = document.createElement('div'), inner = document.createElement('div'); // will log {bar: 0, foo: 1} due to middleware modification outer.addEventListener('my-event', e => console.log(e.detail)); modifier.addEventListener('my-event', e => e.detail.foo = 1); outer.appendChild(modifier); modifier.appendChild(inner); document.documentElement.appendChild(outer); inner.dispatchEvent(new CustomEvent('my-event', {bubbles: true, detail: {bar: 0}})); But it's good you mention this. I feel like this is to implicit in here. Also it's kinda an intermixture between regular iframe event and fake state events :\ I hope I can come up with a better middle-layer that makes this "processing" more explicit, or maybe it should be another event that is transformed into "typo3-module-loaded". But I don't know yet.

    Router.ts:153 Reply

    There is actually no default slot, it is always derived from the `module` attribute. The fluid template contains the <typo3-iframe-module> by default in order to set some default classes. Will try to comment this in a better way.
  57. Benjamin Franzke uploaded patch set 19 04/24/21, 04:14

  58. TYPO3com voted on patch set 19 V -1 04/24/21, 04:22 Completed build in 07m 49s on Sat, 24 Apr, 04:22 AM Test Summary: 33307 passed Find logs and detail information at https://bamboo.typo3.com/browse/CORE-GTC-10849

  59. core-ci voted on patch set 19 V -1 04/24/21, 04:28 Core CI is not happy: https://gitlab.typo3.org/TYPO3/CI/cms/-/pipelines/10671

  60. Benjamin Franzke uploaded patch set 20 04/26/21, 12:05

  61. TYPO3com voted on patch set 20 V +1 04/26/21, 12:11 Completed build in 05m 53s on Mon, 26 Apr, 12:11 PM Test Summary: 33312 passed Find logs and detail information at https://bamboo.typo3.com/browse/CORE-GTC-10862

  62. core-ci voted on patch set 20 V +1 04/26/21, 12:17 Core CI is happy: https://gitlab.typo3.org/TYPO3/CI/cms/-/pipelines/10701

  63. Benjamin Franzke uploaded patch set 21 04/26/21, 17:08

  64. Benjamin Franzke commented on patch set 21 04/26/21, 17:08

    Router.ts:103 Reply

    To help readability I've now added proper interfaces for the event (instead of relying on `any`). interface ModuleState is passed in to the `detail` argument of events. interface DecorateModuleState is tracked by the state-tracker iframe and contains the `ModuleState` data plus an additional tagName.

    Router.ts:153 Reply

    Update Fluid template to reflect that there is no "default" state, as default state would depend on the module to be loaded on startup. Therefore the fluid template now rendered an empty <typo3-backend-module-router> tag. and <typo3-backend-module-router> will create <typo3-iframe-module> ondemand.

    Router.ts:170 Reply

    Done
  65. Benjamin Franzke commented on patch set 21 04/26/21, 17:11

    ModuleLoader.php:169

    Maybe I will merge this into a single `component = TYPO3/CMS/Ext/TheModule` property. The tagName would then be exported by a named export called `componentName`. Makes registration more clean, but means the tag can only be created by the router, once the module is loaded. But the advantage will be: In case the module (javascript) can not be loaded, the router can show proper errors.
  66. core-ci voted on patch set 21 V +1 04/26/21, 17:18 Core CI is happy: https://gitlab.typo3.org/TYPO3/CI/cms/-/pipelines/10710

  67. Benjamin Franzke uploaded patch set 22 04/26/21, 20:32

  68. core-ci voted on patch set 22 V +1 04/26/21, 20:43 Core CI is happy: https://gitlab.typo3.org/TYPO3/CI/cms/-/pipelines/10714

  69. Benjamin Franzke uploaded patch set 23 04/26/21, 22:01

  70. core-ci voted on patch set 23 V +1 04/26/21, 22:16 Core CI is happy: https://gitlab.typo3.org/TYPO3/CI/cms/-/pipelines/10715

  71. Benjamin Franzke uploaded patch set 24 04/27/21, 23:07

  1. core-ci voted on patch set 24 V +1 04/27/21, 23:19 Core CI is happy: https://gitlab.typo3.org/TYPO3/CI/cms/-/pipelines/10810

  2. Benjamin Franzke uploaded patch set 25 04/28/21, 00:02

  3. Benjamin Franzke commented on patch set 25 04/28/21, 00:02

    Router.ts:103 Reply

    I've additionally splitted the events to make it clear that there are differences between regular module events and the iframe events. Therefore the events are now no longer modified during propapagation.

    ModuleRouter.ts:59 Reply

    Refactored this code. This is no longer needed. Component is now referenced by javascript module name. The HTML Tag (implementation detail) is advertised as named export by the module (benni and me decided on the same approach for navigation components, hope that makes sense.) Closing as this code is no longer available.

    ModuleLoader.php:169 Reply

    Done

    Main.html:22 Reply

    As discussed in slack, its a router componenents.
  4. Benjamin Franzke commented on patch set 25 04/28/21, 00:06

    Note: It helps to checkout https://review.typo3.org/c/Packages/TYPO3.CMS/+/68200 (from the relation chain of this patch) to have "Configuration" module implemented as a web component. Allows to to fully test the router state synchronization.
  5. core-ci voted on patch set 25 V +1 04/28/21, 00:16 Core CI is happy: https://gitlab.typo3.org/TYPO3/CI/cms/-/pipelines/10813

  6. Benni Mack commented on patch set 25 04/28/21, 08:03

    Just a quick info about this "state tracker" thingy. We do have a DummyController with `/empty` entry point (route target "dummy"). We could use this one. What do you think?
  7. Benni Mack updated the commit message in patch set 26 04/28/21, 08:07

  8. core-ci voted on patch set 26 V +1 04/28/21, 08:18 Core CI is happy: https://gitlab.typo3.org/TYPO3/CI/cms/-/pipelines/10824

  9. Benni Mack commented on patch set 26 V +1 CR +1 04/28/21, 18:18

    I think this patch is OK as is, we need to do some fine-tuning for the deeplinking in a separate patch (also making this next step the actual "feature"), but this is a great step forward.
  10. Benjamin Franzke uploaded patch set 27 04/29/21, 06:17

  11. core-ci voted on patch set 27 V +1 04/29/21, 06:31 Core CI is happy: https://gitlab.typo3.org/TYPO3/CI/cms/-/pipelines/10876

  12. Benjamin Franzke uploaded patch set 28 04/30/21, 12:56

  13. core-ci voted on patch set 28 V +1 04/30/21, 13:07 Core CI is happy: https://gitlab.typo3.org/TYPO3/CI/cms/-/pipelines/10971

  14. Oli Bartsch commented on patch set 28 V +1 CR +1 04/30/21, 13:50

    Great work!
  15. Benjamin Franzke commented on patch set 28 CR -1 04/30/21, 14:10

    Hm, maybe would should add a Feature.rst for the updating URLs. Will try to add it real quick..
  16. Benjamin Franzke uploaded patch set 29 04/30/21, 14:34

  17. Benjamin Franzke uploaded patch set 30 04/30/21, 14:42

  18. core-ci voted on patch set 29 V +1 04/30/21, 14:46 Core CI is happy: https://gitlab.typo3.org/TYPO3/CI/cms/-/pipelines/10973

  19. core-ci voted on patch set 30 V +1 04/30/21, 14:53 Core CI is happy: https://gitlab.typo3.org/TYPO3/CI/cms/-/pipelines/10974

  20. Oli Bartsch voted on patch set 30 V +1 CR +1 04/30/21, 15:05

  21. Andreas Kienast commented on patch set 30 V +1 04/30/21, 15:12

    StateTrackerController.php:27

    What's the purpose of this controller? Is this a preparation for something or a left-over?
  22. Benjamin Franzke commented on patch set 30 04/30/21, 15:18

    StateTrackerController.php:27 Reply

    Yes it is a preparation for web component based backend modules, as shown in patch relation chain: https://review.typo3.org/c/Packages/TYPO3.CMS/+/68200/14 The idea is to prepare for such modules right from the start (meaning: do not just care for adressbar updates for iframe modules but also for upcoming native-web-component based backend modules). The state tracker will be used to track state of web components (kind of as polyfill/history.pushState which cannot be combined with iframes – tried to document that in the commit message).
  23. Andreas Kienast commented on patch set 30 CR +1 04/30/21, 15:20

    StateTrackerController.php:27 Reply Unresolved

    Alright, thanks for your explanation!
  24. Benjamin Franzke voted on patch set 30 V +2 CR +2 04/30/21, 16:20

  25. Benjamin Franzke merged patch set 31 04/30/21, 16:22