class sap.ui.core.Fragment

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

Fragments support the definition of light-weight stand-alone UI control trees. This class acts as factory which returns the UI control tree defined inside the Fragments. When used within declarative Views, the Fragment content is imported and seamlessly integrated into the View.

Fragments are used similar as sap.ui.core.mvc.Views, but Fragments do not have a Controller on their own (they may know one, though), they are not a Control, they are not part of the UI tree and they have no representation in HTML. By default, in contrast to declarative Views, they do not do anything to guarantee ID uniqueness.

But like Views they can be defined in several Formats (XML, declarative HTML, JavaScript; support for other types can be plugged in), the declaration syntax is the same as in declarative Views and the name and location of the Fragment files is similar to Views. Controller methods can also be referenced in the declarations, but as Fragments do not have their own controllers, this requires the Fragments to be used within a View which does have a controller. That controller is used, then.

Do not call the Fragment constructor directly!

Use-cases for Fragments are e.g.: - Modularization of UIs without fragmenting the controller structure - Re-use of UI parts - 100%-declarative definition of Views


Constructor

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.Fragment()

Properties

Name Type Default Value Description
type string Visibility: public

Methods Overview

Method Description
sap.ui.core.Fragment.byId

Returns an Element/Control by its ID in the context of the Fragment with the given ID

sap.ui.core.Fragment.createId

Returns the ID which a Control with the given ID in the context of the Fragment with the given ID would have.

sap.ui.core.Fragment.extend

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

sap.ui.core.Fragment.getMetadata

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

getType

Gets current value of property type.

sap.ui.core.Fragment.getType

Get the implementation of the init and the load function for the requested fragment type.

sap.ui.core.Fragment.load

Loads and instantiates a Fragment. A Promise is returned, which resolves with the Fragments content.

The Fragment object itself is not an entity with significance beyond this factory.

The Fragment types "XML", "JS" and "HTML" are available by default; additional Fragment types can be added using the sap.ui.core.Fragment.registerType() function.

Further properties may be supported by future or custom Fragment types. Any given properties will be forwarded to the Fragment implementation.

If no fixed ID is given, the Fragment ID is generated. In any case, the Fragment ID will be used as prefix for the IDs of all contained controls.

sap.ui.core.Fragment.registerType

Registers a new Fragment type

setType

Sets a new value for property type.

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

sap.ui.core.Fragment.byId

Returns an Element/Control by its ID in the context of the Fragment with the given ID

Param Type DefaultValue Description
sFragmentId string

ID of the Fragment from which to retrieve the Control

sId string

ID of the Element/Control to retrieve

sap.ui.core.Fragment.createId

Returns the ID which a Control with the given ID in the context of the Fragment with the given ID would have.

Param Type DefaultValue Description
sFragmentId string

ID of the Fragment for which to calculate the Control ID

sId string

Fragment-local ID of the Control to calculate the ID for

sap.ui.core.Fragment.extend

Creates a new subclass of class sap.ui.core.Fragment 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.ManagedObject.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

sap.ui.core.Fragment.getMetadata

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

getType

Gets current value of property type.

sap.ui.core.Fragment.getType

Get the implementation of the init and the load function for the requested fragment type.

Param Type DefaultValue Description
sType string

Name of the fragment type

sap.ui.core.Fragment.load

Loads and instantiates a Fragment. A Promise is returned, which resolves with the Fragments content.

The Fragment object itself is not an entity with significance beyond this factory.

The Fragment types "XML", "JS" and "HTML" are available by default; additional Fragment types can be added using the sap.ui.core.Fragment.registerType() function.

Further properties may be supported by future or custom Fragment types. Any given properties will be forwarded to the Fragment implementation.

If no fixed ID is given, the Fragment ID is generated. In any case, the Fragment ID will be used as prefix for the IDs of all contained controls.

Param Type DefaultValue Description
mOptions object

options map

name string

must be supplied if no "definition" parameter is given. The Fragment name must correspond to an XML Fragment which can be loaded via the module system (fragmentName + suffix ".fragment.[typeextension]") and which contains the Fragment definition. If "mOptions.controller" is supplied, the (event handler-) methods referenced in the Fragment will be called on this Controller. Note that Fragments may require a Controller to be given and certain methods to be implemented by it.

type string XML

the Fragment type, e.g. "XML", "JS", or "HTML" (see above). Default is "XML"

definition string

definition of the Fragment content. When this property is supplied, the "name" parameter must not be used. If both are supplied, the definition has priority. Please see the above example on how to use the 'definition' parameter.

id string

the ID of the Fragment

controller sap.ui.core.mvc.Controller Object

the Controller or Object which should be used by the controls in the Fragment. Note that some Fragments may not need a Controller while others may need one and certain methods to be implemented by it.

containingView sap.ui.core.mvc.View

The view containing the Fragment content. If the Fragment content contains ExtensionPoints this parameter must be given.

sap.ui.core.Fragment.registerType

Registers a new Fragment type

Param Type DefaultValue Description
sType string

the Fragment type. Types "XML", "HTML" and JS" are built-in and always available.

oFragmentImpl object

an object having the properties "init" and "load".

init function

Called on Fragment instantiation with the settings map as argument. Function needs to return a promise which resolves with sap.ui.core.Control|sap.ui.core.Control[]

load function

Called to load the fragment content. Must return a Promise which resolves with the loaded resource. This resource is passed as 'fragmentContent' to the init() function via a parameter object.

setType

Sets a new value for property type.

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

Param Type DefaultValue Description
sType string

New value for property type