HTML Container

Overview

The library controls can be embedded anywhere in an HTML page by the means of a UIArea. Such a UIArea denotes a place by a DOM node in a page where a control, or a tree of controls, will be rendered to. Whenever the JavaScript object that represents the control is modified, the control will be re-rendered.

The HTML control which is part of the sap.ui.core library package can be used in any other control such as Tab, Panel, MatrixLayout, or others. In comparison to other library controls, the rendering for the HTML control is different: Instead of creating control-specific HTML, the HTML control displays the HTML that you have defined in the content property.

Examples

Static HTML Provided as a String

This is the simple use case for the HTML control: Some - usually decorative - HTML fragment is specified as a string and set to the content property. Without further configuration, the HTML control will convert this string to DOM nodes whenever it has to render.

The Panel in this example contains several controls out of the library and an HTML control on the right-hand side. The content of the HTML control is defined by a longer string literal. Open the source box to check this; whenever the control is rendered, the string content is rendered as inner HTML and thereby converted to DOM nodes.

After rendering, the DOM nodes can be modified by an action such as add node, remove node, modify attribute, or attach event handler, for example. You can click into the HTML control below to simulate such dynamic changes. But whenever the control is rendered again, the original HTML fragment is also rendered and new DOM nodes replace the existing modified ones. Check it with the Redraw button which invalidates and re-renders the HTML control.

Last Redraw: , DOM Node UID:

Static (decorative) HTML Provided as a String With Preserved DOM After Rendering

The second use case is similar to the first one: The HTML fragment is specified as a string. The difference is that after the first rendering, the HTML control tries to preserve the created DOM nodes as long as possible. Before each re-rendering step, the existing DOM is preserved in some hidden page area, and then the control and its relatives (parents, siblings) are rendered - this creates a new DOM node hierarchy. After the rendering, the preserved DOM content of the controls is integrated in the newly created DOM tree.

This example is useful when the dynamic changes to the DOM cannot be re-done easily, for example if they represent valuable user interaction. The HTML control initially renders an empty black box. By clicking it, a dynamic modification is simulated (colored boxes are added). When the control is re-rendered, the string content is rendered again, and all dynamic changes are lost. If you enable the preferDOM option which is a control property, the existing DOM node is preserved together with the dynamic changes.

Last Redraw: , DOM Node UID:

Predefined Content

A different approach for defining the HTML content of the control is to associate some existing DOM content with the control. There are two ways possible to implement this:

  • Automatic Content Association

    Embed the content into the HTML page as content of the enclosing UIArea. Give the content the same ID the HTML control has. The framework runtime analyzes the content of the UIArea before rendering it and preserves any content with an ID. After rendering the HTML control, the control will find the preserved content by its ID and display it.

  • Manual Content Association

    Create the DOM content anywhere on the page and associate it with an HTML control by calling the setDOMContent method. The control will reproduce the content whenever it re-renders.

  • Sample 3a:Automatic Content Association

    Last Redraw: , DOM Node UID:

    Sample 3b:Manual Content Association

    In this example, some content is created using jQuery and set as the content of the HTML control.

    Last Redraw: , DOM Node UID:

    Use Case 4 (experimental): HTML With Multiple Root Nodes

    The library controls must have a single root element. If you have the requirement that the HTML can consist of more than one root node, for example if you need a chain of spans with different styles, you can use the HTML control with the experimental support for multiple root nodes. Since this feature is experimental, problems are to be expected, especially in the case that single controls are re-rendered or invalidated. The scenario that should work without any problems is

    Sample 4:Multi-Root Content Within a MatrixLayoutCell

    Last Redraw: , DOM Node UID:

    Note: This use case is not fully supported by the framework. Especially re-rendering might fail or give unexpected results in the case of multiple roots. Use it only after carefully testing of your scenario.

    API Documentation

    See API documentation