Central topic to learn about rendering in UI5

[boghyon]

It would be nice if there is a central place to learn about how renderings are done in UI5 (Especially for new developers with experience in popular frameworks).

1. General understanding

For newcomers and researchers:

• Basics: what does "rendering" mean in the first place in the context of UI5? (I feel people often confound "rendering" with the paint event of the browser)
• When, in which situation, or by which actions do controls get invalidated to rerender in UI5?
• When rerendering, how is the DOM update in UI5 realized? String-based? VDOM? Incremental DOM / in-place DOM patching / semantic rendering? Using a third-party lib like lit-HTML (e.g. in case of UI5 Web Components)? Or something else? How does it work?
  And: how does the current rendering approach differ from other popular concepts? Is the rendering engine itself tree-shakable? Lower memory consumption? Any performance or complexity analysis (Big O)? Does UI5 require diffing the DOM trees to detect changes? Or is the DOM manipulation done directly without diffing?
• What other concepts does UI5 provide to optimize DOM manipulation?
  Linking to other resources like Extended Change Detection, InvisibleRenderer.render, etc…

2. Implementing renderers

For advanced UI5 developers:

• Moving Renderer Methods and Multiple ways to specify a renderer to Writing a Control Renderer?
• How to migrate from the legacy string-based rendering to the new semantic rendering?
  • Since the rendering behavior has changed, control developers might need to double-check their handling of focus, scroll position, ResizeHandler or other event registration in onAfterRendering. Simply replacing the legacy (now-deprecated) APIs with the new ones might be insufficient since the existing element in DOM will be reused with apiVersion 2 or higher.
    Sample commit: SAP/openui5@6525fed
  • How to deal with foreign non-HTMLElements, such as SVGs? (SO question #75424952)
    Related talk by @akudev: Embedding 3rd-party widget as UI5 control [video]
• What else should control developers keep in mind besides the standard quality criteria and avoiding deprecated APIs?
  • @abstract controls should have renderer: null assigned. Otherwise, MyControlRenderer.js can be accidentally fetched in some cases, leading to a 404 error. Abstract controls don't have renderers by definition.
    Sample commit: SAP/openui5@50da9ee
  • When instantiating some text-containing controls internally, either ManagedObject.escapeSettingsValue in the constructor settings object (since v1.52) or the mutator (e.g. setText) after the control instantiation should be used.
    Sample issues and fixes: https://github.com/SAP/openui5/issues?q=is%3Aissue+curly+escapeSettingsValue
  • When using RenderManager#icon, the renderer module for the control should require sap/ui/core/IconPool in order to avoid synchronous loading of the dependency.
    Sample commit: SAP/openui5@7dddccd
  • For inner elements, too, start with openStart and provide an ID as a 2nd argument (control.getId() + "-myInnerEl") instead of using attr("id", "...") so that the Patcher can reuse the existing DOM elements again when rerendering.
    Sample commit: SAP/openui5@3756b0e
  • Neither rerender nor invalidate is designed to be overwritten by controls, that intend to further manipulate the DOM there, which should be avoided in favor of onAfterRendering. Controls should not rely on rerender being called anyway since SAP/openui5@378b598.
  • Collection of available interfaces, mixins, and other stuff which control developers must incorporate in certain cases in order to align with the framework specification and behaviors.
  • …

Motivation

Currently, it's easy for new developers to get lost when trying to understand the above mentioned points. When going through the documentation:

• Information about rendering seems scattered in different topics.

• Code snippets in some topics still use the deprecated rendering APIs (write*(), add*(), …)
  Some use the new semantic rendering APIs (openStart(), class(), attr(), …)
  For beginners, it's not clear which one is new and which one is old.

• Code snippets with inconsistent renderer assignments:

  • renderer: { render: <fn> } (should include at least apiVersion: 2 or higher to enable the DOM-patching)
  • renderer: <fn> (should be avoided: Assigning function directly to "renderer" should no longer be encouraged #33)
  • renderer: "sap.m.SomeRenderer"
  • renderer: MyRequiredRenderer (Current best-practice AFAIK. Cf. SAP/openui5@ad5bc4e and SAP/openui5@f0fa93f)

• Code snippets with inconsistent renderer definitions:

  • In the control definition itself at renderer
  • A separate renderer module (e.g. MyControlRenderer.js)
    • Returning a plain object with bExport true (Not intended to be used for non-SAP developers)
    • Returning Renderer.extend(/*…*/); whereas Renderer is required from sap/ui/core/Renderer (Current best-practice AFAIK)

• One or two topics that explain all the above points would help people to grasp rendering in UI5 quickly. Additionally, the Best Practices for Developers section "Control rendering" should be also enhanced afterwards.

[boghyon]

For future UI5 control development based on UI5 Web Components, follow SAP/ui5-webcomponents#2926

[flovogt]

Hello @boghyon ,
Thank you for sharing this awesome summary. Sorry, that we've not responded to your input so long. I've created an internal incident 2280031660. The status of the issue will be updated here in GitHub.

[Thodd]

@boghyon & @flovogt:
I consolidated this issue and the one about function usage in an internal backlog item: CPOUI5FRAMEWORK-343
See also my other comment on #33

[i556484]

Controls should not rely on rerender being called anyway since SAP/openui5@378b598.

SNOW: CS20240007695164