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.
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
.
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"); };
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:
onBeforeRendering
and exit
hooks.sap.ui.core.CSSSize
). But this might not be sufficient in all cases, e.g. validated URL values can contain harmful content; in this case encodeCSS can be used.rm.openStart("div", oControl.getId() + "-suffix");
instead of rm.openStart("div").attr("id", oControl.getId() + "-suffix");
focusin
event must double check their focus handling. Since DOM nodes are not removed and only reused, the focusin
event might not be fired during re-rendering.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()
Method | Description |
---|---|
accessibilityState |
Collects accessibility related attributes for an 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):
oElement is given, only mProps will be taken into account.Heuristic MappingThe following mapping from properties/values to ARIA attributes is used (if the element does have such properties):
In case of the Additionally, the associations Label controls that reference the given element in their 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 The parameter Examples: The function behaves in the same way for the associations {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 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 |
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. The following example shows how 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 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 |
close |
Closes an open tag started with 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
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
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 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 |
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 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 |
text |
Sets the text content with the given text. Line breaks are not supported by this method, use CSS white-space: pre-line
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 |
voidEnd |
Ends an open self-closing tag started with This indicates that there are no more attributes to set to the open tag. For self-closing tags |
voidStart |
Starts a self-closing tag, such as This must be followed by |
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("<span id=\"" + oCtrl.getId() + "-outer\" class=\"myCtrlOuter\">" + "&nbsp;" + oResourceBundle.getText("TEXT_KEY") + "&nbsp;</span>"); <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 "&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 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):
oElement is given, only mProps will be taken into account.Heuristic MappingThe following mapping from properties/values to ARIA attributes is used (if the element does have such properties):
In case of the Additionally, the associations Label controls that reference the given element in their 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 The parameter Examples: The function behaves in the same way for the associations {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
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.
|
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):
oElement
, using a heuristic mapping (described below)mProps
parameter, as provided by the calleroElement
, if it has a parent and if the parent implements the method enhanceAccessibilityStateoElement
is given, only mProps
will be taken into account.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
).
Param | Type | DefaultValue | Description |
---|---|---|---|
oElement | sap.ui.core.Element |
The |
|
mProps | object |
A map of additional properties that should be added or changed. |
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
Param | Type | DefaultValue | Description |
---|---|---|---|
sName | string |
name of the class to be added; null values are ignored |
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
Param | Type | DefaultValue | Description |
---|---|---|---|
sName | string |
Name of the CSS property to write |
|
vValue | string float int |
Value to write |
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 |
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 |
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 |
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 } }); ... };
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 |
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 |
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 |
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.
Detaches a sap.ui.core.RenderManager.preserveContent listener
Param | Type | DefaultValue | Description |
---|---|---|---|
fnListener | function |
listener function |
Searches "to-be-preserved" nodes for the given control id.
Param | Type | DefaultValue | Description |
---|---|---|---|
sId | string |
control id to search content for. |
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 ( |
|
vInsert | boolean int |
Determines whether the buffer of the target DOM node is expanded ( |
Returns the configuration object Shortcut for sap.ui.getCore().getConfiguration()
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.
Param | Type | DefaultValue | Description |
---|---|---|---|
oControl | sap.ui.core.Control |
the Control whose HTML should be returned. |
Returns the hidden area reference belonging to the current window instance.
Returns the renderer class for a given control instance
Param | Type | DefaultValue | Description |
---|---|---|---|
oControl | sap.ui.core.Control |
the control that should be rendered |
Returns the renderer class for a given control instance
Param | Type | DefaultValue | Description |
---|---|---|---|
oControl | sap.ui.core.Control |
the control that should be rendered |
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.
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 |
Ends an open tag started with openStart
.
This indicates that there are no more attributes to set to the open tag.
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 |
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 |
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. |
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 |
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 |
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 |
Param | Type | DefaultValue | Description |
---|---|---|---|
sKey | string |
the key |
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 |
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.
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 the given texts to the buffer.
Param | Type | DefaultValue | Description |
---|---|---|---|
sText | string number |
(can be a number too) |
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):
oElement
, using a heuristic mapping (described below)mProps
parameter, as provided by the calleroElement
, if it has a parent and if the parent implements the method enhanceAccessibilityStateoElement
is given, only mProps
will be taken into account.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
).
Param | Type | DefaultValue | Description |
---|---|---|---|
oElement | sap.ui.core.Element |
The |
|
mProps | object |
A map of additional properties that should be added or changed. |
Writes the attribute and its value into the HTML.
For details about the escaping refer to jQuery.sap.encodeHTML
Param | Type | DefaultValue | Description |
---|---|---|---|
sName | string |
Name of the attribute |
|
vValue | string number boolean |
Value of the attribute |
Writes the attribute and a value into the HTML, the value will be encoded.
The value is properly encoded to avoid XSS attacks.
Param | Type | DefaultValue | Description |
---|---|---|---|
sName | string |
Name of the attribute |
|
vValue | any |
Value of the attribute |
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.
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) |
Writes the controls data into the HTML. Control Data consists at least of the id of a control
Param | Type | DefaultValue | Description |
---|---|---|---|
oControl | sap.ui.core.Control |
the control whose identifying information should be written to the buffer |
Writes the elements data into the HTML. Element Data consists at least of the id of an element
Param | Type | DefaultValue | Description |
---|---|---|---|
oElement | sap.ui.core.Element |
the element whose identifying information should be written to the buffer |
Escape text for HTML and write it to the buffer.
For details about the escaping refer to jQuery.sap.encodeHTML
Param | Type | DefaultValue | Description |
---|---|---|---|
sText | any |
the text to escape |
|
bLineBreaks | boolean | false |
Whether to convert line breaks into |
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: ""
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 |