abstract class sap.ui.core.XMLComposite

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

Base Class for XMLComposite controls.

Documentation links:


Constructor

XMLComposite is the base class for composite controls that use a XML fragment representation for their visual parts. From a user perspective such controls appear as any other control, but internally the rendering part is added as a fragment. The fragment that is used should appear in the same folder as the control's JS implementation with the file extension .control.xml. The fragment's content can access the interface data from the XMLComposite control via bindings. Currently only aggregations and properties can be used with bindings inside a fragment. The exposed model that is used for internal bindings in the fragment has the default name $this. The name will always start with an $. The metadata of the derived control can define the alias with its metadata. A code example can be found below.

As XMLComposites compose other controls, they are only invalidated and re-rendered if explicitly defined. Additional metadata for invalidation can be given for properties and aggregation. The default invalidation is "none". Setting invalidate to true for properties and aggregations sets the complete XMLComposite to invalidate and rerender.

Example:

XMLComposite.extend("sap.mylib.MyXMLComposite", {
  metadata : {
    library: "sap.mylib",
    properties : {
      text: { //changing this property will not re-render the XMLComposite
         type: "string",
         defaultValue: ""
      },
      title: { //changing this property will re-render the XMLComposite as it defines invalidate: true
         type: "string",
         defaultValue: "",
         invalidate: true
      },
      value: { //changing this property will re-render the XMLComposite as it defines invalidate: true
         type: "string",
         defaultValue: "",
         invalidate: true
      }
    },
    defaultProperty : "text",
    aggregations : {
      items : {
         type: "sap.ui.core.Control",
         invalidate: true
      },
      header : {
         type: "sap.mylib.FancyHeader",
         multiple : false
      }
    },
    defaultAggregation : "items"
    events: {
      outerEvent : {
        parameters : {
          opener : "sap.ui.core.Control"
        }
      }
    }
  },
  //alias defaults to "this"
  alias: "mycontrolroot" //inner bindings will use model name $mycontrolroot
  //fragment defaults to {control name}.control.xml in this case sap.mylib.MyXMLComposite.control.xml
  fragment: "sap.mylib.MyXMLCompositeOther.control.xml" //the name of the fragment
});

Internally the XMLComposite instantiates and initializes the given fragment and stores the resulting control in a hidden aggregation named _content. The fragment should only include one root element.

Bindings of inner controls to the interface of the XMLComposite can be done with normal binding syntax. Here properties are used as property bindings and aggregations are used as list bindings. Currently it is not possible to bind associations in a fragment.

Example:

   <core:FragmentDefinition xmlns:m="sap.m" xmlns:core="sap.ui.core">
      <m:Text text="{$this>text}" visible="{= ${$this>text} !== ""}" />
   </core:FragmentDefinition>
   <core:FragmentDefinition xmlns:m="sap.m" xmlns:core="sap.ui.core">
      <m:VBox items="{path:"$this>texts", filters:{path:"text", operator:"Contains", value1:"Text"}, sorter:{path:"text", descending:true}}">
          <m:Text text="{$this>text}" />
      </m:VBox>
   </core:FragmentDefinition>
   <core:FragmentDefinition xmlns:m="sap.m" xmlns:core="sap.ui.core">
      <m:Button text="Press Me" press="handlePress"/>
   </core:FragmentDefinition>

All events handled within the fragment will be dispatched to the XMLComposite control. It is recommended to follow this paradigm to allow reuse of a XMLComposite without any dependency to controller code of the current embedding view.

   MyXMLComposite.prototype.handlePress = function() {
       this.fireOuterEvent(); // passing on the event to the outer view
   }

Accepts an object literal mSettings that defines initial property values, aggregated and associated objects as well as event handlers. See sap.ui.base.ManagedObject#constructor for a general description of the syntax of the settings object.

new sap.ui.core.XMLComposite()

Properties

Name Type Default Value Description
displayBlock boolean true

Whether the CSS display should be set to "block".

Visibility: public
height sap.ui.core.CSSSize

The height

Visibility: public
width sap.ui.core.CSSSize 100%

The width

Visibility: public

Borrowed Properties

Name Type Default Value Description
blocked boolean false

Whether the control is currently in blocked state.

Visibility: public
busy boolean false

Whether the control is currently in busy state.

Visibility: public
busyIndicatorDelay int 1000

The delay in milliseconds, after which the busy indicator will show up for this control.

Visibility: public
busyIndicatorSize sap.ui.core.BusyIndicatorSize Medium

The size of the BusyIndicator. For controls with a width smaller 3rem a sap.ui.core.BusyIndicatorSize.Small should be used. If the size could vary in width and the width could get smaller than 3rem, the sap.ui.core.BusyIndicatorSize.Auto option could be used. The default is set to sap.ui.core.BusyIndicatorSize.Medium For a full screen BusyIndicator use sap.ui.core.BusyIndicatorSize.Large.

Since: 1.54.

Visibility: public
fieldGroupIds string[]

The IDs of a logical field group that this control belongs to.

All fields in a logical field group should share the same fieldGroupId. Once a logical field group is left, the validateFieldGroup event is fired.

For backward compatibility with older releases, field group IDs are syntactically not limited, but it is suggested to use only valid sap.ui.core.IDs.

See #attachValidateFieldGroup or consult the Field Group documentation.

Since: 1.31.

Visibility: public
visible boolean true

Whether the control should be visible on the screen.

If set to false, a placeholder will be rendered to mark the location of the invisible control in the DOM of the current page. The placeholder will be hidden and have zero dimensions (display: none).

Also see InvisibleRenderer.

Visibility: public

Aggregations

Default Aggregation:

Name Cardinality Type Description
_content 0..1 sap.ui.core.Control

Aggregation used to store the default content

Borrowed Aggregations

Name Cardinality Type Description
customData 0..n sap.ui.core.CustomData

Custom Data, a data structure like a map containing arbitrary key value pairs.

dependents 0..n sap.ui.core.Element

Dependents are not rendered, but their databinding context and lifecycle are bound to the aggregating Element.

Since: 1.19.

dragDropConfig 0..n sap.ui.core.dnd.DragDropBase

Defines the drag-and-drop configuration. Note: This configuration might be ignored due to control metadata restrictions.

Since: 1.56.

layoutData 0..1 sap.ui.core.LayoutData

Defines the layout constraints for this control when it is used inside a Layout. LayoutData classes are typed classes and must match the embedding Layout. See VariantLayoutData for aggregating multiple alternative LayoutData instances to a single Element.

tooltip 0..1 sap.ui.core.TooltipBase

The tooltip that should be shown for this Element.

In the most simple case, a tooltip is a string that will be rendered by the control and displayed by the browser when the mouse pointer hovers over the control's DOM. In this variant, tooltip behaves like a simple control property.

Controls need to explicitly support this kind of tooltip as they have to render it, but most controls do. Exceptions will be documented for the corresponding controls (e.g. sap.ui.core.HTML does not support tooltips).

Alternatively, tooltip can act like a 0..1 aggregation and can be set to a tooltip control (an instance of a subclass of sap.ui.core.TooltipBase). In that case, the framework will take care of rendering the tooltip control in a popup-like manner. Such a tooltip control can display arbitrary content, not only a string.

UI5 currently does not provide a recommended implementation of TooltipBase as the use of content-rich tooltips is discouraged by the Fiori Design Guidelines. Existing subclasses of TooltipBase therefore have been deprecated. However, apps can still subclass from TooltipBase and create their own implementation when needed (potentially taking the deprecated implementations as a starting point).

See the section Using Tooltips in the Fiori Design Guideline.


Methods Overview

Method Description
byId

Returns an element by its ID in the context of the XMLComposite.

May only be used by the implementation of a specific XMLComposite, not by an application using a XMLComposite.

enhanceAccessibilityState

This method is a hook for the RenderManager that gets called during the rendering of child Controls. It allows to add, remove and update existing accessibility attributes (ARIA) of those controls.

sap.ui.core.XMLComposite.extend

Creates a new subclass of class sap.ui.core.XMLComposite 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.core.Control.extend.

getDisplayBlock

Gets current value of property displayBlock.

Whether the CSS display should be set to "block".

Default value is true.

getHeight

Gets current value of property height.

The height

sap.ui.core.XMLComposite.getMetadata

Returns a metadata object for class sap.ui.core.XMLComposite.

getResourceBundle

Returns the resource bundle of the resource model

Sample: this.getResourceBundle().then(function(oBundle) {oBundle.getText()})

getWidth

Gets current value of property width.

The width

Default value is '100%'.

setDisplayBlock

Sets a new value for property displayBlock.

Whether the CSS display should be set to "block".

When called with a value of null or undefined, the default value of the property will be restored.

Default value is true.

setHeight

Sets a new value for property height.

The height

When called with a value of null or undefined, the default value of the property will be restored.

setWidth

Sets a new value for property width.

The width

When called with a value of null or undefined, the default value of the property will be restored.

Default value is '100%'.

byId

Returns an element by its ID in the context of the XMLComposite.

May only be used by the implementation of a specific XMLComposite, not by an application using a XMLComposite.

Param Type DefaultValue Description
sId string

XMLComposite-local ID of the inner element

enhanceAccessibilityState

This method is a hook for the RenderManager that gets called during the rendering of child Controls. It allows to add, remove and update existing accessibility attributes (ARIA) of those controls.

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

The Control that gets rendered by the RenderManager

mAriaProps object

The mapping of "aria-" prefixed attributes

sap.ui.core.XMLComposite.extend

Creates a new subclass of class sap.ui.core.XMLComposite 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.core.Control.extend.

Param Type DefaultValue Description
sClassName string

Name of the class being created

oClassInfo object

Object literal with information about the class

FNMetaImpl function

Constructor function for the metadata object; if not given, it defaults to the metadata implementation used by this class

getDisplayBlock

Gets current value of property displayBlock.

Whether the CSS display should be set to "block".

Default value is true.

getHeight

Gets current value of property height.

The height

sap.ui.core.XMLComposite.getMetadata

Returns a metadata object for class sap.ui.core.XMLComposite.

getResourceBundle

Returns the resource bundle of the resource model

Sample: this.getResourceBundle().then(function(oBundle) {oBundle.getText()})

getWidth

Gets current value of property width.

The width

Default value is '100%'.

setDisplayBlock

Sets a new value for property displayBlock.

Whether the CSS display should be set to "block".

When called with a value of null or undefined, the default value of the property will be restored.

Default value is true.

Param Type DefaultValue Description
bDisplayBlock boolean true

New value for property displayBlock

setHeight

Sets a new value for property height.

The height

When called with a value of null or undefined, the default value of the property will be restored.

Param Type DefaultValue Description
sHeight sap.ui.core.CSSSize

New value for property height

setWidth

Sets a new value for property width.

The width

When called with a value of null or undefined, the default value of the property will be restored.

Default value is '100%'.

Param Type DefaultValue Description
sWidth sap.ui.core.CSSSize '100%'

New value for property width