class sap.ui.core.RenderManager

Control sample: sap.ui.core.RenderManager
Visiblity: public
UX Guidelines:
Implements:
Available since: N/A
Extends: Object
Module: sap/ui/core/RenderManager
Application Component: CA-UI5-COR

A class that handles the rendering of controls.

For the default rendering task of UI5, a shared RenderManager is created and owned by sap.ui.core.Core. Controls or other code that want to render controls outside the default rendering task can create a private instance of RenderManager by calling the sap.ui.getCore().createRenderManager() method. When such a private instance is no longer needed, it should be destroyed.

Control renderers only have access to a subset of the public and protected instance methods of this class. The instance methods #flush, #render and #destroy are not part of that subset and are reserved to the owner of the corresponding RenderManager instance. Renderers will use the provided methods to create their HTML output. The RenderManager will collect the HTML output and inject the final HTML DOM at the desired location.

Renderers

When the #renderControl method of the RenderManager is invoked, it will retrieve the default renderer for that control. By convention, the default renderer is implemented in its own namespace (static class) which matches the name of the control's class with the additional suffix 'Renderer'. So for a control sap.m.Input the default renderer will be searched for under the global name sap.m.InputRenderer.

Semantic Rendering

As of 1.67, RenderManager provides a set of new APIs to describe the structure of the DOM that can be used by the control renderers.


  myButtonRenderer.render = function(rm, oButton) {

      rm.openStart("button", oButton);
      rm.attr("tabindex", 1);
      rm.class("myButton");
      rm.style("width", oButton.getWidth());
      rm.openEnd();
          rm.text(oButton.getText());
      rm.close("button");

  };

By default, when the control is invalidated (e.g. a property is changed, an aggregation is removed, or an association is added), it will be registered for re-rendering. During the (re)rendering, the render method of the control renderer is executed via a specified RenderManager interface and the control instance.

Traditional string-based rendering creates a new HTML structure of the control in every rendering cycle and removes the existing control DOM structure from the DOM tree.

The set of new semantic RenderManager APIs lets us understand the structure of the DOM, walk along the live DOM tree, and figure out changes as new APIs are called. If there is a change, then RenderManager patches only the required parts of the live DOM tree. This allows control developers to remove their DOM-related custom setters.

Note: To enable the new in-place rendering technology, the apiVersion property of the control renderer must be set to 2. This property is not inherited by subclass renderers. It has to be set anew by each subclass to assure that the extended contract between framework and renderer is fulfilled (see next paragraph).


  var myButtonRenderer = {
      apiVersion: 2    // enable semantic rendering
  };

  myButtonRenderer.render = function(rm, oButton) {

      rm.openStart("button", oButton);
      ...
      ...
      rm.close("button");

  };

Contract for Renderer.apiVersion 2

To allow a more efficient in-place DOM patching and to ensure the compatibility of the control, the following prerequisites must be fulfilled for the controls using the new rendering technology:



Documentation links:


Constructor

Creates an instance of the RenderManager.

Applications or controls must not call the RenderManager constructor on their own but should use the sap.ui.getCore().createRenderManager() method to create an instance for their exclusive use.

new sap.ui.core.RenderManager()

Methods Overview

Method Description
accessibilityState

Collects accessibility related attributes for an Element and renders them as part of the currently rendered DOM element.

See the WAI-ARIA specification for a general description of the accessibility related attributes. Attributes are only rendered when the accessibility feature is activated in the UI5 runtime configuration.

The values for the attributes are collected from the following sources (last one wins):

  1. from the properties and associations of the given oElement, using a heuristic mapping (described below)
  2. from the mProps parameter, as provided by the caller
  3. from the parent of the given oElement, if it has a parent and if the parent implements the method enhanceAccessibilityState
If no oElement is given, only mProps will be taken into account.

Heuristic Mapping

The following mapping from properties/values to ARIA attributes is used (if the element does have such properties):

  • editable===false => aria-readonly="true"
  • enabled===false => aria-disabled="true"
  • visible===false => aria-hidden="true"
  • required===true => aria-required="true"
  • selected===true => aria-selected="true"
  • checked===true => aria-checked="true"

In case of the required property, all label controls which reference the given element in their labelFor relation are additionally taken into account when determining the value for the aria-required attribute.

Additionally, the associations ariaDescribedBy and ariaLabelledBy are used to determine the lists of IDs for the ARIA attributes aria-describedby and aria-labelledby.

Label controls that reference the given element in their labelFor relation are automatically added to the aria-labelledby attribute.

Note: This function is only a heuristic of a control property to ARIA attribute mapping. Control developers have to check whether it fulfills their requirements. In case of problems (for example the RadioButton has a selected property but must provide an aria-checked attribute) the auto-generated result of this function can be influenced via the parameter mProps as described below.

The parameter mProps can be used to either provide additional attributes which should be rendered and/or to avoid the automatic generation of single ARIA attributes. The 'aria-' prefix will be prepended automatically to the keys (Exception: Attribute role does not get the prefix 'aria-').

Examples:
{hidden : true} results in aria-hidden="true" independent of the presence or absence of the visibility property.
{hidden : null} ensures that no aria-hidden attribute is written independent of the presence or absence of the visibility property.

The function behaves in the same way for the associations ariaDescribedBy and ariaLabelledBy. To append additional values to the auto-generated aria-describedby and aria-labelledby attributes, the following format can be used:

  {describedby : {value: "id1 id2", append: true}} =>  aria-describedby = "ida idb id1 id2"
(assuming that "ida idb" is the auto-generated part based on the association ariaDescribedBy).

addClass

Adds a class to the class collection if the name is not empty or null. The class collection is flushed if it is written to the buffer using #writeClasses

Since 1.92 Instead use {@link sap.ui.core.RenderManager#class} of the {@link sap.ui.core.RenderManager Semantic Rendering API}.
addStyle

Adds a style property to the style collection if the value is not empty or null The style collection is flushed if it is written to the buffer using #writeStyle

Since 1.92 Instead use {@link sap.ui.core.RenderManager#style} of the {@link sap.ui.core.RenderManager Semantic Rendering API}.
sap.ui.core.RenderManager.attachPreserveContent

Attaches a listener which is called on sap.ui.core.RenderManager.preserveContent call

attr

Adds an attribute name-value pair to the last open HTML element.

This is only valid when called between openStart/voidStart and openEnd/voidEnd. The attribute name must not be equal to style or class. Styles and classes must be set via dedicated class or style methods. To update the DOM correctly, all attribute names have to be used in their canonical form. For HTML elements, attribute names must all be set in lowercase. For foreign elements, such as SVG, attribute names can be set in upper camel case (e.g. viewBox).

HTML entities are not supported by this method, use unicode escaping or the unicode character to implement HTML entities. For further information see https://html.spec.whatwg.org/multipage/named-characters.html#named-character-references .

class

Adds a class name to the class collection of the last open HTML element.

This is only valid when called between openStart/voidStart and openEnd/voidEnd. Class name must not contain any whitespace.

cleanupControlWithoutRendering

Cleans up the rendering state of the given control without rendering it.

A control is responsible for the rendering of all its child controls. But in some cases it makes sense that a control only renders a subset of its children based on some criterion. For example, a typical carousel control might, for performance reasons, only render the currently visible children (and maybe some child before and after the visible area to facilitate slide-in / slide-out animations), but not all children. This leads to situations where a child had been rendered before, but shouldn't be rendered anymore after an update of the carousel's position. The DOM related state of that child then must be cleaned up correctly, e.g. by de-registering resize handlers or native event handlers. cleanupControlWithoutRendering helps with that task by triggering the same activities that the normal rendering triggers before the rendering of a control (e.g. it fires the BeforeRendering event). It just doesn't call the renderer and the control will not receive an AfterRendering event.

The following example shows how renderControl and cleanupControlWithoutRendering should be used:

  CarouselRenderer.render = function(rm, oCarousel){

    ...

    oCarousel.getPages().forEach( function( oPage ) {
       if ( oCarousel.isPageToBeRendered( oPage ) ) {
          rm.renderControl( oPage ); // onBeforeRendering, render, later onAfterRendering
       } else {
          rm.cleanupControlWithoutRendering( oPage ); // onBeforeRendering
       }
    });

    ...

  };

DOM Removal

The method does not remove the DOM of the given control. The caller of this method has to take care to remove it at some later point in time. It should indeed be later, not before as the onBeforeRendering hook of the control might need access to the old DOM for a proper cleanup.

For parents which are rendered with the normal mechanism as shown in the example above, the removal of the old child DOM is guaranteed. The whole DOM of the parent control (including the DOM of the no longer rendered child) will be replaced with new DOM (no longer containing the child) when the rendering cycle finishes.

Note:: the functionality of this method is different from the default handling for invisible controls (controls with visible == false). The standard rendering for invisible controls still renders a placeholder DOM. This allows re-rendering of the invisible control once it becomes visible again without a need to render its parent, too. Children that are cleaned up with this method here, are supposed to have no more DOM at all. Rendering them later on therefore requires an involvement (typically: a rendering) of their parent.

close

Closes an open tag started with openStart and ended with openEnd.

This indicates that there are no more children to append to the open tag.

sap.ui.core.RenderManager.createInvisiblePlaceholderId

Creates the ID to be used for the invisible Placeholder DOM element. This method can be used to get direct access to the placeholder DOM element. Also statically available as RenderManager.createInvisiblePlaceholderId()

destroy

Cleans up the resources associated with this instance.

After the instance has been destroyed, it must not be used anymore. Applications should call this function if they don't need the instance any longer.

sap.ui.core.RenderManager.detachPreserveContent

Detaches a sap.ui.core.RenderManager.preserveContent listener

sap.ui.core.RenderManager.findPreservedContent

Searches "to-be-preserved" nodes for the given control id.

flush

Renders the content of the rendering buffer into the provided DOM node.

This function must not be called within control renderers.

Usage:


  // Create a new instance of the RenderManager
  var rm = sap.ui.getCore().createRenderManager();

  // Use the writer API to fill the buffers
  rm.write(...);
  rm.renderControl(oControl);
  rm.write(...);
  ...

  // Finally flush the buffer into the provided DOM node (The current content is removed)
  rm.flush(oDomNode);

  // If the instance is not needed anymore, destroy it
  rm.destroy();

getConfiguration

Returns the configuration object Shortcut for sap.ui.getCore().getConfiguration()

Since 1.92 Instead, use the {@link sap.ui.core.Core#getConfiguration} API.
getHTML

Renders the given sap.ui.core.Control and finally returns the content of the rendering buffer. Ensures the buffer is restored to the state before calling this method.

Since 0.15.0 Use <code>flush()</code> instead render content outside the rendering phase.
sap.ui.core.RenderManager.getPreserveAreaRef

Returns the hidden area reference belonging to the current window instance.

getRenderer

Returns the renderer class for a given control instance

sap.ui.core.RenderManager.getRenderer

Returns the renderer class for a given control instance

icon

Writes either an <img> tag for normal URI or a <span> tag with needed properties for an icon URI.

Additional classes and attributes can be added to the tag with the second and third parameter. All of the given attributes are escaped when necessary for security consideration.

When an <img> tag is rendered, the following two attributes are added by default and can be overwritten with corresponding values in the mAttributes parameter:

  • role: "presentation"
  • alt: ""

Note: This function requires the sap.ui.core.IconPool module. Ensure that the module is loaded before this function is called to avoid syncXHRs.

openEnd

Ends an open tag started with openStart.

This indicates that there are no more attributes to set to the open tag.

openStart

Opens the start tag of an HTML element.

This must be followed by openEnd and concluded with close. To allow a more efficient DOM update, all tag names have to be used in their canonical form. For HTML elements, tag names must all be set in lowercase. For foreign elements, such as SVG, tag names can be set in upper camel case (e.g. linearGradient).

sap.ui.core.RenderManager.preserveContent

Collects descendants of the given root node that need to be preserved before the root node is wiped out. The "to-be-preserved" nodes are moved to a special, hidden 'preserve' area.

A node is declared "to-be-preserved" when it has the data-sap-ui-preserve attribute set. When the optional parameter bPreserveNodesWithId is set to true, then nodes with an id are preserved as well and their data-sap-ui-preserve attribute is set automatically. This option is used by UIAreas when they render for the first time and simplifies the handling of predefined HTML content in a web page.

The "to-be-preserved" nodes are searched with a depth first search and moved to the 'preserve' area in the order that they are found. So for direct siblings the order should be stable.

render

Renders the given control to the provided DOMNode.

If the control is already rendered in the provided DOMNode the DOM of the control is replaced. If the control is already rendered somewhere else the current DOM of the control is removed and the new DOM is appended to the provided DOMNode.

This function must not be called within control renderers.

renderControl

Turns the given control into its HTML representation and appends it to the rendering buffer.

If the given control is undefined or null, then nothing is rendered.

style

Adds a style name-value pair to the style collection of the last open HTML element.

This is only valid when called between openStart/voidStart and openEnd/voidEnd. To allow a more efficient DOM update, the CSS property names and values have to be used in their canonical form. In general, CSS properties are lower-cased in their canonical form, except for parts that are not under the control of CSS. For more information, see https://www.w3.org/TR/CSS/#indices .

text

Sets the text content with the given text.

Line breaks are not supported by this method, use CSS white-space: pre-line option to implement line breaks.

HTML entities are not supported by this method, use unicode escaping or the unicode character to implement HTML entities. For further information see https://html.spec.whatwg.org/multipage/named-characters.html#named-character-references .

translate
Since 1.1 never has been implemented - DO NOT USE
unsafeHtml

Sets the given HTML markup without any encoding or sanitizing.

This must not be used for plain texts; use the text method instead.

voidEnd

Ends an open self-closing tag started with voidStart.

This indicates that there are no more attributes to set to the open tag. For self-closing tags close must not be called.

voidStart

Starts a self-closing tag, such as img or input.

This must be followed by voidEnd. For self-closing tags, the close method must not be called. To allow a more efficient DOM update, void tag names have to be set in lowercase. This API is specific for void elements and must not be used for foreign elements. For more information, see https://www.w3.org/TR/html5/syntax.html#void-elements .

write

Write the given texts to the buffer.

Since 1.92 Instead, use the {@link sap.ui.core.RenderManager Semantic Rendering API}. There is no 1:1 replacement for <code>write</code>. Typically, <code>write</code> is used to create a longer sequence of HTML markup (e.g. an element with attributes and children) in a single call. Such a markup sequence has to be split into the individual calls of the Semantic Rendering API. <br><br>Example:<br> oRm.write("&lt;span id=\"" + oCtrl.getId() + "-outer\" class=\"myCtrlOuter\"&gt;" + "&amp;nbsp;" + oResourceBundle.getText("TEXT_KEY") + "&amp;nbsp;&lt;/span&gt;"); <br><br> has to be transformed to <br><br> oRm.openStart("span", oCtrl.getId() + "-outer").class("myCtrlOuter").openEnd().text("\u00a0" + oResourceBundle.getText("TEXT_KEY") + "\u00a0").close("span"); <br><br> Note that "&amp;nbsp;" was replaced with "\u00a0" (no-break-space). In general, HTML entities have to be replaced by the corresponding Unicode character escapes. A mapping table can be found at {@link https://html.spec.whatwg.org/multipage/named-characters.html#named-character-references}.
writeAcceleratorKey
Since 1.1 never has been implemented - DO NOT USE
writeAccessibilityState

Collects accessibility related attributes for an Element and renders them as part of the currently rendered DOM element.

See the WAI-ARIA specification for a general description of the accessibility related attributes. Attributes are only rendered when the accessibility feature is activated in the UI5 runtime configuration.

The values for the attributes are collected from the following sources (last one wins):

  1. from the properties and associations of the given oElement, using a heuristic mapping (described below)
  2. from the mProps parameter, as provided by the caller
  3. from the parent of the given oElement, if it has a parent and if the parent implements the method enhanceAccessibilityState
If no oElement is given, only mProps will be taken into account.

Heuristic Mapping

The following mapping from properties/values to ARIA attributes is used (if the element does have such properties):

  • editable===false => aria-readonly="true"
  • enabled===false => aria-disabled="true"
  • visible===false => aria-hidden="true"
  • required===true => aria-required="true"
  • selected===true => aria-selected="true"
  • checked===true => aria-checked="true"

In case of the required property, all label controls which reference the given element in their labelFor relation are additionally taken into account when determining the value for the aria-required attribute.

Additionally, the associations ariaDescribedBy and ariaLabelledBy are used to determine the lists of IDs for the ARIA attributes aria-describedby and aria-labelledby.

Label controls that reference the given element in their labelFor relation are automatically added to the aria-labelledby attributes.

Note: This function is only a heuristic of a control property to ARIA attribute mapping. Control developers have to check whether it fulfills their requirements. In case of problems (for example the RadioButton has a selected property but must provide an aria-checked attribute) the auto-generated result of this function can be influenced via the parameter mProps as described below.

The parameter mProps can be used to either provide additional attributes which should be rendered and/or to avoid the automatic generation of single ARIA attributes. The 'aria-' prefix will be prepended automatically to the keys (Exception: Attribute role does not get the prefix 'aria-').

Examples:
{hidden : true} results in aria-hidden="true" independent of the presence or absence of the visibility property.
{hidden : null} ensures that no aria-hidden attribute is written independent of the presence or absence of the visibility property.

The function behaves in the same way for the associations ariaDescribedBy and ariaLabelledBy. To append additional values to the auto-generated aria-describedby and aria-labelledby attributes, the following format can be used:

  {describedby : {value: "id1 id2", append: true}} =>  aria-describedby = "ida idb id1 id2"
(assuming that "ida idb" is the auto-generated part based on the association ariaDescribedBy).

Since 1.92 Instead use {@link sap.ui.core.RenderManager#accessibilityState} of the {@link sap.ui.core.RenderManager Semantic Rendering API}.
writeAttribute

Writes the attribute and its value into the HTML.

For details about the escaping refer to jQuery.sap.encodeHTML

Since 1.92 Instead use {@link sap.ui.core.RenderManager#attr} of the {@link sap.ui.core.RenderManager Semantic Rendering API}.
writeAttributeEscaped

Writes the attribute and a value into the HTML, the value will be encoded.

The value is properly encoded to avoid XSS attacks.

Since 1.92 Instead use {@link sap.ui.core.RenderManager#attr} of the {@link sap.ui.core.RenderManager Semantic Rendering API}.
writeClasses

Writes and flushes the class collection (all CSS classes added by "addClass()" since the last flush). Also writes the custom style classes added by the application with "addStyleClass(...)". Custom classes are added by default from the currently rendered control. If an oElement is given, this Element's custom style classes are added instead. If oElement === false, no custom style classes are added.

Since 1.92 Not longer needed, when using the {@link sap.ui.core.RenderManager Semantic Rendering API} the actual writing of classes happens when {@link sap.ui.core.RenderManager#openEnd} or {@link sap.ui.core.RenderManager#voidEnd} are used.
writeControlData

Writes the controls data into the HTML. Control Data consists at least of the id of a control

Since 1.92 Instead use {@link sap.ui.core.RenderManager#openStart} or {@link sap.ui.core.RenderManager#voidStart} of the {@link sap.ui.core.RenderManager Semantic Rendering API} and pass the desired control data as the second parameter to the new API.
writeElementData

Writes the elements data into the HTML. Element Data consists at least of the id of an element

Since 1.92 Instead use {@link sap.ui.core.RenderManager#openStart} or {@link sap.ui.core.RenderManager#voidStart} of the {@link sap.ui.core.RenderManager Semantic Rendering API} and pass the desired element data as the second parameter to the new API.
writeEscaped

Escape text for HTML and write it to the buffer.

For details about the escaping refer to jQuery.sap.encodeHTML

Since 1.92 Instead use {@link sap.ui.core.RenderManager#text} of the {@link sap.ui.core.RenderManager Semantic Rendering API}.
writeIcon

Writes either an <img> tag for normal URI or a <span> tag with needed properties for an icon URI.

Additional classes and attributes can be added to the tag with the second and third parameter. All of the given attributes are escaped for security consideration.

When an <img> tag is rendered, the following two attributes are added by default and can be overwritten with corresponding values in the mAttributes parameter:

  • role: "presentation"
  • alt: ""

Since 1.92 Instead use {@link sap.ui.core.RenderManager#icon} of the {@link sap.ui.core.RenderManager Semantic Rendering API}.
writeStyles

Writes and flushes the style collection

Since 1.92 Not longer needed, when using the {@link sap.ui.core.RenderManager Semantic Rendering API} the actual writing of styles happens when {@link sap.ui.core.RenderManager#openEnd} or {@link sap.ui.core.RenderManager#voidEnd} are used.

accessibilityState

Collects accessibility related attributes for an Element and renders them as part of the currently rendered DOM element.

See the WAI-ARIA specification for a general description of the accessibility related attributes. Attributes are only rendered when the accessibility feature is activated in the UI5 runtime configuration.

The values for the attributes are collected from the following sources (last one wins):

  1. from the properties and associations of the given oElement, using a heuristic mapping (described below)
  2. from the mProps parameter, as provided by the caller
  3. from the parent of the given oElement, if it has a parent and if the parent implements the method enhanceAccessibilityState
If no oElement is given, only mProps will be taken into account.

Heuristic Mapping

The following mapping from properties/values to ARIA attributes is used (if the element does have such properties):

In case of the required property, all label controls which reference the given element in their labelFor relation are additionally taken into account when determining the value for the aria-required attribute.

Additionally, the associations ariaDescribedBy and ariaLabelledBy are used to determine the lists of IDs for the ARIA attributes aria-describedby and aria-labelledby.

Label controls that reference the given element in their labelFor relation are automatically added to the aria-labelledby attribute.

Note: This function is only a heuristic of a control property to ARIA attribute mapping. Control developers have to check whether it fulfills their requirements. In case of problems (for example the RadioButton has a selected property but must provide an aria-checked attribute) the auto-generated result of this function can be influenced via the parameter mProps as described below.

The parameter mProps can be used to either provide additional attributes which should be rendered and/or to avoid the automatic generation of single ARIA attributes. The 'aria-' prefix will be prepended automatically to the keys (Exception: Attribute role does not get the prefix 'aria-').

Examples:
{hidden : true} results in aria-hidden="true" independent of the presence or absence of the visibility property.
{hidden : null} ensures that no aria-hidden attribute is written independent of the presence or absence of the visibility property.

The function behaves in the same way for the associations ariaDescribedBy and ariaLabelledBy. To append additional values to the auto-generated aria-describedby and aria-labelledby attributes, the following format can be used:

  {describedby : {value: "id1 id2", append: true}} =>  aria-describedby = "ida idb id1 id2"
(assuming that "ida idb" is the auto-generated part based on the association ariaDescribedBy).

Param Type DefaultValue Description
oElement sap.ui.core.Element

The Element whose accessibility state should be rendered

mProps object

A map of additional properties that should be added or changed.

addClass

Adds a class to the class collection if the name is not empty or null. The class collection is flushed if it is written to the buffer using #writeClasses

Since 1.92 Instead use {@link sap.ui.core.RenderManager#class} of the {@link sap.ui.core.RenderManager Semantic Rendering API}.
Param Type DefaultValue Description
sName string

name of the class to be added; null values are ignored

addStyle

Adds a style property to the style collection if the value is not empty or null The style collection is flushed if it is written to the buffer using #writeStyle

Since 1.92 Instead use {@link sap.ui.core.RenderManager#style} of the {@link sap.ui.core.RenderManager Semantic Rendering API}.
Param Type DefaultValue Description
sName string

Name of the CSS property to write

vValue string float int

Value to write

sap.ui.core.RenderManager.attachPreserveContent

Attaches a listener which is called on sap.ui.core.RenderManager.preserveContent call

Param Type DefaultValue Description
fnListener function

listener function

oContext object RenderManager

context for the listener function

attr

Adds an attribute name-value pair to the last open HTML element.

This is only valid when called between openStart/voidStart and openEnd/voidEnd. The attribute name must not be equal to style or class. Styles and classes must be set via dedicated class or style methods. To update the DOM correctly, all attribute names have to be used in their canonical form. For HTML elements, attribute names must all be set in lowercase. For foreign elements, such as SVG, attribute names can be set in upper camel case (e.g. viewBox).

HTML entities are not supported by this method, use unicode escaping or the unicode character to implement HTML entities. For further information see https://html.spec.whatwg.org/multipage/named-characters.html#named-character-references .

Param Type DefaultValue Description
sName string

Name of the attribute

vValue any

Value of the attribute

class

Adds a class name to the class collection of the last open HTML element.

This is only valid when called between openStart/voidStart and openEnd/voidEnd. Class name must not contain any whitespace.

Param Type DefaultValue Description
sClass string

Class name to be written

cleanupControlWithoutRendering

Cleans up the rendering state of the given control without rendering it.

A control is responsible for the rendering of all its child controls. But in some cases it makes sense that a control only renders a subset of its children based on some criterion. For example, a typical carousel control might, for performance reasons, only render the currently visible children (and maybe some child before and after the visible area to facilitate slide-in / slide-out animations), but not all children. This leads to situations where a child had been rendered before, but shouldn't be rendered anymore after an update of the carousel's position. The DOM related state of that child then must be cleaned up correctly, e.g. by de-registering resize handlers or native event handlers. cleanupControlWithoutRendering helps with that task by triggering the same activities that the normal rendering triggers before the rendering of a control (e.g. it fires the BeforeRendering event). It just doesn't call the renderer and the control will not receive an AfterRendering event.

The following example shows how renderControl and cleanupControlWithoutRendering should be used:

  CarouselRenderer.render = function(rm, oCarousel){

    ...

    oCarousel.getPages().forEach( function( oPage ) {
       if ( oCarousel.isPageToBeRendered( oPage ) ) {
          rm.renderControl( oPage ); // onBeforeRendering, render, later onAfterRendering
       } else {
          rm.cleanupControlWithoutRendering( oPage ); // onBeforeRendering
       }
    });

    ...

  };

DOM Removal

The method does not remove the DOM of the given control. The caller of this method has to take care to remove it at some later point in time. It should indeed be later, not before as the onBeforeRendering hook of the control might need access to the old DOM for a proper cleanup.

For parents which are rendered with the normal mechanism as shown in the example above, the removal of the old child DOM is guaranteed. The whole DOM of the parent control (including the DOM of the no longer rendered child) will be replaced with new DOM (no longer containing the child) when the rendering cycle finishes.

Note:: the functionality of this method is different from the default handling for invisible controls (controls with visible == false). The standard rendering for invisible controls still renders a placeholder DOM. This allows re-rendering of the invisible control once it becomes visible again without a need to render its parent, too. Children that are cleaned up with this method here, are supposed to have no more DOM at all. Rendering them later on therefore requires an involvement (typically: a rendering) of their parent.

Param Type DefaultValue Description
oControl sap.ui.core.Control

Control that should be cleaned up

close

Closes an open tag started with openStart and ended with openEnd.

This indicates that there are no more children to append to the open tag.

Param Type DefaultValue Description
sTagName string

Tag name of the HTML element

sap.ui.core.RenderManager.createInvisiblePlaceholderId

Creates the ID to be used for the invisible Placeholder DOM element. This method can be used to get direct access to the placeholder DOM element. Also statically available as RenderManager.createInvisiblePlaceholderId()

Param Type DefaultValue Description
oElement sap.ui.core.Element

The Element instance for which to create the placeholder ID

destroy

Cleans up the resources associated with this instance.

After the instance has been destroyed, it must not be used anymore. Applications should call this function if they don't need the instance any longer.

sap.ui.core.RenderManager.detachPreserveContent

Detaches a sap.ui.core.RenderManager.preserveContent listener

Param Type DefaultValue Description
fnListener function

listener function

sap.ui.core.RenderManager.findPreservedContent

Searches "to-be-preserved" nodes for the given control id.

Param Type DefaultValue Description
sId string

control id to search content for.

flush

Renders the content of the rendering buffer into the provided DOM node.

This function must not be called within control renderers.

Usage:


  // Create a new instance of the RenderManager
  var rm = sap.ui.getCore().createRenderManager();

  // Use the writer API to fill the buffers
  rm.write(...);
  rm.renderControl(oControl);
  rm.write(...);
  ...

  // Finally flush the buffer into the provided DOM node (The current content is removed)
  rm.flush(oDomNode);

  // If the instance is not needed anymore, destroy it
  rm.destroy();

Param Type DefaultValue Description
oTargetDomNode Element

Node in the DOM where the buffer should be flushed into

bDoNotPreserve boolean

Determines whether the content is preserved (false) or not (true)

vInsert boolean int

Determines whether the buffer of the target DOM node is expanded (true) or replaced (false), or the new entry is inserted at a specific position (value of type int)

getConfiguration

Returns the configuration object Shortcut for sap.ui.getCore().getConfiguration()

Since 1.92 Instead, use the {@link sap.ui.core.Core#getConfiguration} API.

getHTML

Renders the given sap.ui.core.Control and finally returns the content of the rendering buffer. Ensures the buffer is restored to the state before calling this method.

Since 0.15.0 Use <code>flush()</code> instead render content outside the rendering phase.
Param Type DefaultValue Description
oControl sap.ui.core.Control

the Control whose HTML should be returned.

sap.ui.core.RenderManager.getPreserveAreaRef

Returns the hidden area reference belonging to the current window instance.

getRenderer

Returns the renderer class for a given control instance

Param Type DefaultValue Description
oControl sap.ui.core.Control

the control that should be rendered

sap.ui.core.RenderManager.getRenderer

Returns the renderer class for a given control instance

Param Type DefaultValue Description
oControl sap.ui.core.Control

the control that should be rendered

icon

Writes either an <img> tag for normal URI or a <span> tag with needed properties for an icon URI.

Additional classes and attributes can be added to the tag with the second and third parameter. All of the given attributes are escaped when necessary for security consideration.

When an <img> tag is rendered, the following two attributes are added by default and can be overwritten with corresponding values in the mAttributes parameter:

Note: This function requires the sap.ui.core.IconPool module. Ensure that the module is loaded before this function is called to avoid syncXHRs.

Param Type DefaultValue Description
sURI sap.ui.core.URI

URI of an image or of an icon registered in sap.ui.core.IconPool

aClasses array string

Additional classes that are added to the rendered tag

mAttributes object

Additional attributes that will be added to the rendered tag. Currently the attributes class and style are not allowed

openEnd

Ends an open tag started with openStart.

This indicates that there are no more attributes to set to the open tag.

openStart

Opens the start tag of an HTML element.

This must be followed by openEnd and concluded with close. To allow a more efficient DOM update, all tag names have to be used in their canonical form. For HTML elements, tag names must all be set in lowercase. For foreign elements, such as SVG, tag names can be set in upper camel case (e.g. linearGradient).

Param Type DefaultValue Description
sTagName string

Tag name of the HTML element

vControlOrId sap.ui.core.Element sap.ui.core.ID

Control instance or ID to identify the element

sap.ui.core.RenderManager.preserveContent

Collects descendants of the given root node that need to be preserved before the root node is wiped out. The "to-be-preserved" nodes are moved to a special, hidden 'preserve' area.

A node is declared "to-be-preserved" when it has the data-sap-ui-preserve attribute set. When the optional parameter bPreserveNodesWithId is set to true, then nodes with an id are preserved as well and their data-sap-ui-preserve attribute is set automatically. This option is used by UIAreas when they render for the first time and simplifies the handling of predefined HTML content in a web page.

The "to-be-preserved" nodes are searched with a depth first search and moved to the 'preserve' area in the order that they are found. So for direct siblings the order should be stable.

Param Type DefaultValue Description
oRootNode Element

to search for "to-be-preserved" nodes

bPreserveRoot boolean false

whether to preserve the root itself

bPreserveNodesWithId boolean false

whether to preserve nodes with an id as well

render

Renders the given control to the provided DOMNode.

If the control is already rendered in the provided DOMNode the DOM of the control is replaced. If the control is already rendered somewhere else the current DOM of the control is removed and the new DOM is appended to the provided DOMNode.

This function must not be called within control renderers.

Param Type DefaultValue Description
oControl sap.ui.core.Control

the Control that should be rendered.

oTargetDomNode Element

The node in the DOM where the result of the rendering should be inserted.

renderControl

Turns the given control into its HTML representation and appends it to the rendering buffer.

If the given control is undefined or null, then nothing is rendered.

Param Type DefaultValue Description
oControl sap.ui.core.Control

the control that should be rendered

style

Adds a style name-value pair to the style collection of the last open HTML element.

This is only valid when called between openStart/voidStart and openEnd/voidEnd. To allow a more efficient DOM update, the CSS property names and values have to be used in their canonical form. In general, CSS properties are lower-cased in their canonical form, except for parts that are not under the control of CSS. For more information, see https://www.w3.org/TR/CSS/#indices .

Param Type DefaultValue Description
sName string

Name of the style property

sValue string

Value of the style property

text

Sets the text content with the given text.

Line breaks are not supported by this method, use CSS white-space: pre-line option to implement line breaks.

HTML entities are not supported by this method, use unicode escaping or the unicode character to implement HTML entities. For further information see https://html.spec.whatwg.org/multipage/named-characters.html#named-character-references .

Param Type DefaultValue Description
sText string

The text to be written

translate

Since 1.1 never has been implemented - DO NOT USE
Param Type DefaultValue Description
sKey string

the key

unsafeHtml

Sets the given HTML markup without any encoding or sanitizing.

This must not be used for plain texts; use the text method instead.

Param Type DefaultValue Description
sHtml string

Well-formed, valid HTML markup

voidEnd

Ends an open self-closing tag started with voidStart.

This indicates that there are no more attributes to set to the open tag. For self-closing tags close must not be called.

voidStart

Starts a self-closing tag, such as img or input.

This must be followed by voidEnd. For self-closing tags, the close method must not be called. To allow a more efficient DOM update, void tag names have to be set in lowercase. This API is specific for void elements and must not be used for foreign elements. For more information, see https://www.w3.org/TR/html5/syntax.html#void-elements .

Param Type DefaultValue Description
sTagName string

Tag name of the HTML element

vControlOrId sap.ui.core.Element sap.ui.core.ID

Control instance or ID to identify the element

write

Write the given texts to the buffer.

Since 1.92 Instead, use the {@link sap.ui.core.RenderManager Semantic Rendering API}. There is no 1:1 replacement for <code>write</code>. Typically, <code>write</code> is used to create a longer sequence of HTML markup (e.g. an element with attributes and children) in a single call. Such a markup sequence has to be split into the individual calls of the Semantic Rendering API. <br><br>Example:<br> oRm.write("&lt;span id=\"" + oCtrl.getId() + "-outer\" class=\"myCtrlOuter\"&gt;" + "&amp;nbsp;" + oResourceBundle.getText("TEXT_KEY") + "&amp;nbsp;&lt;/span&gt;"); <br><br> has to be transformed to <br><br> oRm.openStart("span", oCtrl.getId() + "-outer").class("myCtrlOuter").openEnd().text("\u00a0" + oResourceBundle.getText("TEXT_KEY") + "\u00a0").close("span"); <br><br> Note that "&amp;nbsp;" was replaced with "\u00a0" (no-break-space). In general, HTML entities have to be replaced by the corresponding Unicode character escapes. A mapping table can be found at {@link https://html.spec.whatwg.org/multipage/named-characters.html#named-character-references}.
Param Type DefaultValue Description
sText string number

(can be a number too)

writeAcceleratorKey

Since 1.1 never has been implemented - DO NOT USE

writeAccessibilityState

Collects accessibility related attributes for an Element and renders them as part of the currently rendered DOM element.

See the WAI-ARIA specification for a general description of the accessibility related attributes. Attributes are only rendered when the accessibility feature is activated in the UI5 runtime configuration.

The values for the attributes are collected from the following sources (last one wins):

  1. from the properties and associations of the given oElement, using a heuristic mapping (described below)
  2. from the mProps parameter, as provided by the caller
  3. from the parent of the given oElement, if it has a parent and if the parent implements the method enhanceAccessibilityState
If no oElement is given, only mProps will be taken into account.

Heuristic Mapping

The following mapping from properties/values to ARIA attributes is used (if the element does have such properties):

In case of the required property, all label controls which reference the given element in their labelFor relation are additionally taken into account when determining the value for the aria-required attribute.

Additionally, the associations ariaDescribedBy and ariaLabelledBy are used to determine the lists of IDs for the ARIA attributes aria-describedby and aria-labelledby.

Label controls that reference the given element in their labelFor relation are automatically added to the aria-labelledby attributes.

Note: This function is only a heuristic of a control property to ARIA attribute mapping. Control developers have to check whether it fulfills their requirements. In case of problems (for example the RadioButton has a selected property but must provide an aria-checked attribute) the auto-generated result of this function can be influenced via the parameter mProps as described below.

The parameter mProps can be used to either provide additional attributes which should be rendered and/or to avoid the automatic generation of single ARIA attributes. The 'aria-' prefix will be prepended automatically to the keys (Exception: Attribute role does not get the prefix 'aria-').

Examples:
{hidden : true} results in aria-hidden="true" independent of the presence or absence of the visibility property.
{hidden : null} ensures that no aria-hidden attribute is written independent of the presence or absence of the visibility property.

The function behaves in the same way for the associations ariaDescribedBy and ariaLabelledBy. To append additional values to the auto-generated aria-describedby and aria-labelledby attributes, the following format can be used:

  {describedby : {value: "id1 id2", append: true}} =>  aria-describedby = "ida idb id1 id2"
(assuming that "ida idb" is the auto-generated part based on the association ariaDescribedBy).

Since 1.92 Instead use {@link sap.ui.core.RenderManager#accessibilityState} of the {@link sap.ui.core.RenderManager Semantic Rendering API}.
Param Type DefaultValue Description
oElement sap.ui.core.Element

The Element whose accessibility state should be rendered

mProps object

A map of additional properties that should be added or changed.

writeAttribute

Writes the attribute and its value into the HTML.

For details about the escaping refer to jQuery.sap.encodeHTML

Since 1.92 Instead use {@link sap.ui.core.RenderManager#attr} of the {@link sap.ui.core.RenderManager Semantic Rendering API}.
Param Type DefaultValue Description
sName string

Name of the attribute

vValue string number boolean

Value of the attribute

writeAttributeEscaped

Writes the attribute and a value into the HTML, the value will be encoded.

The value is properly encoded to avoid XSS attacks.

Since 1.92 Instead use {@link sap.ui.core.RenderManager#attr} of the {@link sap.ui.core.RenderManager Semantic Rendering API}.
Param Type DefaultValue Description
sName string

Name of the attribute

vValue any

Value of the attribute

writeClasses

Writes and flushes the class collection (all CSS classes added by "addClass()" since the last flush). Also writes the custom style classes added by the application with "addStyleClass(...)". Custom classes are added by default from the currently rendered control. If an oElement is given, this Element's custom style classes are added instead. If oElement === false, no custom style classes are added.

Since 1.92 Not longer needed, when using the {@link sap.ui.core.RenderManager Semantic Rendering API} the actual writing of classes happens when {@link sap.ui.core.RenderManager#openEnd} or {@link sap.ui.core.RenderManager#voidEnd} are used.
Param Type DefaultValue Description
oElement sap.ui.core.Element boolean

an Element from which to add custom style classes (instead of adding from the control itself)

writeControlData

Writes the controls data into the HTML. Control Data consists at least of the id of a control

Since 1.92 Instead use {@link sap.ui.core.RenderManager#openStart} or {@link sap.ui.core.RenderManager#voidStart} of the {@link sap.ui.core.RenderManager Semantic Rendering API} and pass the desired control data as the second parameter to the new API.
Param Type DefaultValue Description
oControl sap.ui.core.Control

the control whose identifying information should be written to the buffer

writeElementData

Writes the elements data into the HTML. Element Data consists at least of the id of an element

Since 1.92 Instead use {@link sap.ui.core.RenderManager#openStart} or {@link sap.ui.core.RenderManager#voidStart} of the {@link sap.ui.core.RenderManager Semantic Rendering API} and pass the desired element data as the second parameter to the new API.
Param Type DefaultValue Description
oElement sap.ui.core.Element

the element whose identifying information should be written to the buffer

writeEscaped

Escape text for HTML and write it to the buffer.

For details about the escaping refer to jQuery.sap.encodeHTML

Since 1.92 Instead use {@link sap.ui.core.RenderManager#text} of the {@link sap.ui.core.RenderManager Semantic Rendering API}.
Param Type DefaultValue Description
sText any

the text to escape

bLineBreaks boolean false

Whether to convert line breaks into
tags

writeIcon

Writes either an <img> tag for normal URI or a <span> tag with needed properties for an icon URI.

Additional classes and attributes can be added to the tag with the second and third parameter. All of the given attributes are escaped for security consideration.

When an <img> tag is rendered, the following two attributes are added by default and can be overwritten with corresponding values in the mAttributes parameter:

Since 1.92 Instead use {@link sap.ui.core.RenderManager#icon} of the {@link sap.ui.core.RenderManager Semantic Rendering API}.
Param Type DefaultValue Description
sURI sap.ui.core.URI

URI of an image or of an icon registered in sap.ui.core.IconPool

aClasses array string

Additional classes that are added to the rendered tag

mAttributes object

Additional attributes that will be added to the rendered tag

writeStyles

Writes and flushes the style collection

Since 1.92 Not longer needed, when using the {@link sap.ui.core.RenderManager Semantic Rendering API} the actual writing of styles happens when {@link sap.ui.core.RenderManager#openEnd} or {@link sap.ui.core.RenderManager#voidEnd} are used.