Skip to content
  • Benjamin Franzke's avatar
    [FEATURE] Introduce backend module web component router · de74be87
    Benjamin Franzke authored
    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.
    
    Resolves: #93988
    Related: #93674
    Releases: master
    Change-Id: I682e89649b597c8c74b6a0a8f198f6bcf5bbc347
    Reviewed-on: https://review.typo3.org/c/Packages/TYPO3.CMS/+/67464
    
    
    Tested-by: default avatarcore-ci <typo3@b13.com>
    Tested-by: default avatarOliver Bartsch <bo@cedev.de>
    Tested-by: default avatarAndreas Fernandez <a.fernandez@scripting-base.de>
    Tested-by: default avatarBenjamin Franzke <bfr@qbus.de>
    Reviewed-by: default avatarOliver Bartsch <bo@cedev.de>
    Reviewed-by: default avatarAndreas Fernandez <a.fernandez@scripting-base.de>
    Reviewed-by: default avatarBenjamin Franzke <bfr@qbus.de>
    de74be87