Class sap.ui.core.RenderManagerModule: sap/ui/core/RenderManager

extends Object

RenderManager that will take care for rendering Controls.

The RenderManager will be available from the sap.ui.core.Core instance (available via sap.ui.getCore()).
It can be used to render Controls and Control-Trees.

The convention for renderers belonging to some controls is the following:

  • for a Control e.g. sap.ui.controls.InputField there shall be
  • a renderer named sap.ui.controls.InputFieldRenderer
Constructor Summary
new sap.ui.core.RenderManager()Creates an instance of the RenderManager.
Method Summary
sap.ui.core.RenderManager.createInvisiblePlaceholderId(oElement)Creates the ID to be used for the invisible Placeholder DOM element.
sap.ui.core.RenderManager.extend(sClassName, oClassInfo?, FNMetaImpl?)Creates a new subclass of class sap.ui.core.RenderManager with name sClassName and enriches it with the information contained in oClassInfo.
sap.ui.core.RenderManager.findPreservedContent(sId)Searches "to-be-preserved" nodes for the given control id.
sap.ui.core.RenderManager.getMetadata()Returns a metadata object for class sap.ui.core.RenderManager.
sap.ui.core.RenderManager.getPreserveAreaRef()Returns the hidden area reference belonging to this window instance.
sap.ui.core.RenderManager.getRenderer(oControl)Returns the renderer class for a given control instance
sap.ui.core.RenderManager.preserveContent(oRootNode, bPreserveRoot?, bPreserveNodesWithId?)Collects descendants of the given root node that need to be preserved before the root node is wiped out.
addClass(sName)Adds a class to the class collection if the name is not empty or null.
addStyle(sName, value)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
cleanupControlWithoutRendering(oControl)Cleans up the rendering state of the given control with rendering it.
destroy()Cleans up the resources associated with this instance.
flush(oTargetDomNode, bDoNotPreserve, vInsert)Renders the content of the rendering buffer into the provided DOMNode.
getConfiguration()Returns the configuration object Shortcut for sap.ui.getCore().getConfiguration()
getRenderer(oControl)Returns the renderer class for a given control instance
render(oControl, oTargetDomNode)Renders the given control to the provided DOMNode.
renderControl(oControl)Turns the given control into its HTML representation and appends it to the rendering buffer.
write(sText)Write the given texts to the buffer
writeAccessibilityState(oElement?, mProps?)Writes the accessibility state (see WAI-ARIA specification) of the provided element into the HTML based on the element's properties and associations.
writeAttribute(sName, value)Writes the attribute and its value into the HTML
writeAttributeEscaped(sName, vValue)Writes the attribute and its value into the HTML

The value is properly escaped to avoid XSS attacks.

writeClasses(oElement?)Writes and flushes the class collection (all CSS classes added by "addClass()" since the last flush).
writeControlData(oControl)Writes the controls data into the HTML.
writeElementData(oElement)Writes the elements data into the HTML.
writeEscaped(sText, bLineBreaks)Escape text for HTML and write it to the buffer
writeInvisiblePlaceholderData(oElement)Writes necessary invisible control/element placeholder data into the HTML.
writeStyles()Writes and flushes the style collection
getHTML(oControl)Renders the given sap.ui.core.Control and finally returns the content of the rendering buffer.
translate(sKey)
Methods borrowed from class sap.ui.base.Object
Constructor Detail
new sap.ui.core.RenderManager()
Creates an instance of the RenderManager.
See:
sap.ui.core.Core
sap.ui.getCore()
Method Detail
sap.ui.core.RenderManager.createInvisiblePlaceholderId(oElement): string
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()
Parameters:
{sap.ui.core.Element}oElement The Element instance for which to create the placeholder ID
Returns:
{string} The ID used for the invisible Placeholder of this element
sap.ui.core.RenderManager.extend(sClassName, oClassInfo?, FNMetaImpl?): function
Creates a new subclass of class sap.ui.core.RenderManager with name sClassName and enriches it with the information contained in oClassInfo.

oClassInfo might contain the same kind of information as described in sap.ui.base.Object.extend.

Parameters:
{string}sClassName Name of the class being created
{object}oClassInfo? Object literal with information about the class
{function}FNMetaImpl? Constructor function for the metadata object; if not given, it defaults to sap.ui.core.ElementMetadata
Returns:
{function} Created class / constructor function
sap.ui.core.RenderManager.findPreservedContent(sId): jQuery
Searches "to-be-preserved" nodes for the given control id.
Parameters:
{string}sId control id to search content for.
Returns:
{jQuery} a jQuery collection representing the found content
sap.ui.core.RenderManager.getMetadata(): sap.ui.base.Metadata
Returns a metadata object for class sap.ui.core.RenderManager.
Returns:
{sap.ui.base.Metadata} Metadata object describing this class
sap.ui.core.RenderManager.getPreserveAreaRef(): Element
Returns the hidden area reference belonging to this window instance.
Returns:
{Element} the hidden area reference belonging to this core instance.
sap.ui.core.RenderManager.getRenderer(oControl)
Returns the renderer class for a given control instance
Parameters:
{sap.ui.core.Control}oControl the control that should be rendered
sap.ui.core.RenderManager.preserveContent(oRootNode, bPreserveRoot?, bPreserveNodesWithId?)
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.

Parameters:
{Element}oRootNode to search for "to-be-preserved" nodes
{boolean}bPreserveRoot? whether to preserve the root itself
{boolean}bPreserveNodesWithId? whether to preserve nodes with an id as well
addClass(sName): sap.ui.core.RenderManager
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
Parameters:
{string}sName name of the class to be added; null values are ignored
Returns:
{sap.ui.core.RenderManager} this render manager instance to allow chaining
addStyle(sName, value): sap.ui.core.RenderManager
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
Parameters:
{string}sName name of the CSS property to write
{string|float|int}value value to write
Returns:
{sap.ui.core.RenderManager} this render manager instance to allow chaining
cleanupControlWithoutRendering(oControl)
Cleans up the rendering state of the given control with rendering it.

A control is responsible for the rendering of all its child controls. But in some cases it makes sense that a control does not render all its children based on a filter condition. For example a Carousel control only renders the current visible parts (and maybe some parts before and after the visible area) for performance reasons. If a child was rendered but should not be rendered anymore because the filter condition does not apply anymore this child must be cleaned up correctly (e.g deregistering eventhandlers, ...).

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

render = function(rm, ctrl){ //... var aAggregatedControls = //... for(var i=0; i

Note: The method does not remove DOM of the given control. The callee of this method has to take over the responsibility to cleanup the DOM of the control afterwards. For parents which are rendered with the normal mechanism as shown in the example above this requirement is fulfilled, because the control is not added to the rendering buffer (renderControl is not called) and the DOM is replaced when the rendering cycle is finalized.

Parameters:
{sap.ui.core.Control}oControl the control that should be cleaned up
Since:
1.22.9
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.
flush(oTargetDomNode, bDoNotPreserve, vInsert)
Renders the content of the rendering buffer into the provided DOMNode.

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();
Parameters:
{Element}oTargetDomNode The node in the dom where the buffer should be flushed into.
{boolean}bDoNotPreserve flag, whether to not preserve (true) the content or to preserve it (false).
{boolean|int}vInsert flag, whether to append (true) or replace (false) the buffer of the target dom node or to insert at a certain position (int)
getConfiguration(): sap.ui.core.Configuration
Returns the configuration object Shortcut for sap.ui.getCore().getConfiguration()
Returns:
{sap.ui.core.Configuration} the configuration object
getRenderer(oControl)
Returns the renderer class for a given control instance
Parameters:
{sap.ui.core.Control}oControl the control that should be rendered
render(oControl, oTargetDomNode)
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.

Parameters:
{sap.ui.core.Control}oControl the Control that should be rendered.
{Element}oTargetDomNode The node in the DOM where the result of the rendering should be inserted.
renderControl(oControl)
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.

Parameters:
{sap.ui.core.Control}oControl the control that should be rendered
Write the given texts to the buffer
Parameters:
{string|number}sText (can be a number too)
Returns:
{sap.ui.core.RenderManager} this render manager instance to allow chaining
writeAccessibilityState(oElement?, mProps?): sap.ui.core.RenderManager
Writes the accessibility state (see WAI-ARIA specification) of the provided element into the HTML based on the element's properties and associations.

The ARIA properties are only written when the accessibility feature is activated in the UI5 configuration.

The following properties/values to ARIA attribute mappings are done (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 attribute also the Label controls which referencing the given element in their 'for' relation are taken into account to compute the aria-required attribute.

Additionally the association ariaDescribedBy and ariaLabelledBy are used to write the id lists of the ARIA attributes aria-describedby and aria-labelledby.

Label controls which referencing the given element in their 'for' 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 fullfills 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 added 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 precense or absence of the visibility property. {hidden : null} ensures that no aria-hidden attribute is written independent of the precense 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).

Parameters:
{sap.ui.core.Element}oElement? the element whose accessibility state should be rendered
{Object}mProps? a map of properties that should be added additionally or changed.
Returns:
{sap.ui.core.RenderManager} this render manager instance to allow chaining
writeAttribute(sName, value): sap.ui.core.RenderManager
Writes the attribute and its value into the HTML
Parameters:
{string}sName the name of the attribute
{string|number|boolean}value the value of the attribute
Returns:
{sap.ui.core.RenderManager} this render manager instance to allow chaining
writeAttributeEscaped(sName, vValue): sap.ui.core.RenderManager
Writes the attribute and its value into the HTML

The value is properly escaped to avoid XSS attacks.

Parameters:
{string}sName the name of the attribute
{any}vValue the value of the attribute
Returns:
{sap.ui.core.RenderManager} this render manager instance to allow chaining
writeClasses(oElement?): sap.ui.core.RenderManager
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.
Parameters:
{sap.ui.core.Element|boolean}oElement? an Element from which to add custom style classes (instead of adding from the control itself)
Returns:
{sap.ui.core.RenderManager} this render manager instance to allow chaining
writeControlData(oControl): sap.ui.core.RenderManager
Writes the controls data into the HTML. Control Data consists at least of the id of a control
Parameters:
{sap.ui.core.Control}oControl the control whose identifying information should be written to the buffer
Returns:
{sap.ui.core.RenderManager} this render manager instance to allow chaining
writeElementData(oElement): sap.ui.core.RenderManager
Writes the elements data into the HTML. Element Data consists at least of the id of a element
Parameters:
{sap.ui.core.Element}oElement the element whose identifying information should be written to the buffer
Returns:
{sap.ui.core.RenderManager} this render manager instance to allow chaining
writeEscaped(sText, bLineBreaks): sap.ui.core.RenderManager
Escape text for HTML and write it to the buffer
Parameters:
{string}sText
{boolean}bLineBreaks Whether to convert linebreaks into
tags
Returns:
{sap.ui.core.RenderManager} this render manager instance to allow chaining
writeInvisiblePlaceholderData(oElement): sap.ui.core.RenderManager
Writes necessary invisible control/element placeholder data into the HTML.

Controls should only use this method if they can't live with the standard 'visible=false' implementation of the RenderManager which renders dummy HTMLSpanElement for better re-rendering performance. Even though HTML5 error tolerance accepts this for most of the cases and these dummy elements are not in the render tree of the Browser, controls may need to generate a valid and semantic HTML output when the rendered HTMLSpanElement is not an allowed element(e.g. <span> element within the <tr> or <li> group).

The caller needs to start an opening HTML tag, then call this method, then complete the opening and closing tag.

oRenderManager.write("");
Parameters:
{sap.ui.core.Element}oElement an instance of sap.ui.core.Element
Returns:
{sap.ui.core.RenderManager} this render manager instance to allow chaining
Writes and flushes the style collection
Returns:
{sap.ui.core.RenderManager} this render manager instance to allow chaining
getHTML(oControl): string
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.
Parameters:
{sap.ui.core.Control}oControl the Control whose HTML should be returned.
Deprecated:
Since version 0.15.0. Use flush() instead render content outside the rendering phase.
Returns:
{string} the resulting HTML of the provided control
translate(sKey)
Parameters:
{string}sKey
Deprecated:
Not implemented - DO NOT USE
writeAcceleratorKey(): sap.ui.core.RenderManager
Deprecated:
Not implemented - DO NOT USE
Returns:
{sap.ui.core.RenderManager} this render manager instance to allow chaining