Central topic to learn about rendering in UI5

Start by reviewing the existing Renderer Methods, Writing a Control Renderer, Extended Change Detection, and Best Practices for Developers topics referenced in the issue. Map the scattered rendering guidance and identify which examples use deprecated or inconsistent APIs. Done means producing one or two coherent rendering topics and updating the control-rendering best-practices section.

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: https://github.com/SAP/openui5/commit/6525fed3d98391146d4c52630429f24f5c2c8fdd
  • 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]
    • Sample code snippet. If needed, possibly in conjunction with the new renderAndFlush API (https://github.com/UI5/openui5/commit/3b37d2f04f1bf5e102864c6e70ec27b2727ae76a Thanks @stopcoder), although new RenderManager() must be avoided as its constructor is not public.
• 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: https://github.com/SAP/openui5/commit/50da9eedc2bf4a024694f2f84dd4c7c13cb2200c
  • 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, e.g. to render user-generated texts without evaluating framework-special characters such as the binding syntax unintentionally.
    Sample issues and fixes: https://github.com/SAP/openui5/issues?q=is%3Aissue+curly+escapeSettingsValue
    • Enhancement in relevant documentation topics: https://github.com/UI5/docs/commit/217a3446f9a142f333882812451e6018e3fa872a
    • Improved escapeSettingsValue API description: https://github.com/UI5/openui5/commit/2a6820b8fcc23d40186512b34ce180d4e210a691 Thanks @Thodd!
  • 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: https://github.com/SAP/openui5/commit/7dddccdedfff78a47e39a3a8bf21cb224b7fa761
  • 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: https://github.com/SAP/openui5/commit/3756b0edcfb0d0e56f03f8a6d7bb287069c67036
  • 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 https://github.com/SAP/openui5/commit/378b5982b6c309d269d52b3807485c1f10762d81.
  • Collection of available interfaces, mixins, CSS classes (e.g. -CTX), and other stuff that control developers must incorporate to align with framework standards.
  • …

Motivation

Currently, it is easy to lose track of what best practices are, in which situation. Trying to understand the above mentioned points to get a full picture is not easy either. 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: https://github.com/SAP/openui5-docs/issues/33)
  • renderer: "sap.m.SomeRenderer"
  • renderer: MyRequiredRenderer (Current best-practice AFAIK. Cf. https://github.com/SAP/openui5/commit/ad5bc4efdd2b7d29cfb88ffe37554c8074eaec98 and https://github.com/SAP/openui5/commit/f0fa93fdfe6d1c5104598e191235c4371c603cb3)
    Note: MyRequiredRenderer or "sap.m.SomeRenderer" might not always exist if a non-sap.ui.core.Control super control switches its renderer implementation to renderer: {/*...*/} internally without any dedicated renderer class. A custom control that extends the super control should use renderer: ThatSuperControl.getMetadata().getRenderer() to stay compatible if the custom control has no own renderer.

• Code snippets with inconsistent renderer definitions:

  • In the control definition itself as 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.