Instantiation_of_Fragments_04129b2.md

loio
04129b2798c447368f4c8922c3c33cd7

view on: demo kit nightly build | demo kit latest release

Instantiation of Fragments

OpenUI5 provides two options to instantiate a fragment: If it is instantiated inside a controller extending sap.ui.core.mvc.Controller, theloadFragment() function is the way to go. However, if it is instantiated in a non-controller artefact, the generic function sap.ui.core.Fragment.load() can be used.

Comparing fragments to views, there is one important difference: Fragments are no controls. While views are control instances which have their own HTML and their own set of properties and may contain other controls, fragments just consist of their content. Views contain their content controls, while fragments consist of their content controls.

For example, when a fragment containing a button is instantiated, the result is just this button.

---

Instantiation of Fragments in a Controller

Since 1.93, the loadFragment() function is available on every controller instance extending sap.ui.core.mvc.Controller. This API has several advantages over the generic sap.ui.core.Fragment.load() function:

• The loadFragment API relays the handling of asynchronous destroy operations to the framework's lifecycle.

  In some cases it might happen that a controller instance is destroyed before the asynchronously loaded fragment content becomes available. This typically leads to left-over controls, which are not properly cleaned up. As a result you might experience duplicate ID errors when the same view is recreated. To circumvent such issues, the loadFragment() function automatically wires the fragment loading into the view's exit lifecycle. This way the fragment content also gets destroyed once the view is destroyed. Additionally, all methods which are available on the controller instance, such as an event handler, are also available for the fragment content.

• View Prefixing: By default, the fragment content is prefixed by the view ID. With that, all fragment content is available by using the byId function on the controller or view instance. This option can be disabled by passing false to the autoPrefixId parameter. In this case, the application developer has to ensure that no duplicate ID issues occur for this fragment content.

• Addition to the dependents aggregation: By default, the fragment content is added to the dependents aggregation of the view. This offers two major advantages: First, all models and element bindings which are available on the view instance are also available automatically on the fragment content. Second, if the view is destroyed, the fragment content is destroyed also. This option can be disabled by passing false to the addToDependents parameter. In this case, the application developer has to ensure that the fragment content is destroyed when the view is destroyed. If not, duplicate ID issues might occur.

this.loadFragment({
    name: "myapp.fragments.MyFragment"
});

---

Generic Instantiation of Fragments

The generic function sap.ui.core.Fragment.load() can be called with either the name, the type, and optionally a controller, or with a configuration object and an optional controller; for more information, see the API Reference.

It either returns the root control contained in the fragment or an array of root controls, depending on the type of the fragment. OpenUI5 offers three types: XML, HTML, and JS.

The different methods used for the instantiation of a fragment have the following commonalities:

• A fragment name must be given. This name must be resolvable to the fragment file URL by the OpenUI5 module loading mechanism. In case of JS fragments the name may also be defined inline.

• A controller can be optionally given. Some fragments may require a controller and certain methods to be present in this controller.

• An ID can be optionally given.

  If no ID is given, any control IDs specified in the fragment are used as is. The repeated use of a fragment can lead to duplicate IDs. One way to avoid that problem is to specify a unique fragment ID. For more information see Unique IDs. This ID will then be used as prefix for all controls in this fragment instance.

Note:

When using the generic function sap.ui.core.Fragment.load() the application developer has to take care to add fragment content only to non-destroyed content:

Fragment.load({
    name: "myapp.fragments.MyFragment"
 }).then(function(oContent){
    if(!this.isDestroyStarted()){
       // do stuff
   }
});

• Programmatically Instantiating JS Fragments
  For each fragment type, OpenUI5 provides a method that can be used to programmatically instantiate a fragment.
• Programmatically Instantiating XML Fragments
  For each fragment type, OpenUI5 provides a method that can be used to programmatically instantiate a fragment.
• Instantiating Fragments in Declarative Views
  Example how both types of fragments can be instantiated in an XML view.
• Using Other Objects Instead of Controllers
  For the instantiation of fragments, the oController object must not necessarily be a controller. It can also be another object.
• Inline Definition and Instantiation of Fragments
  Instead of defining fragments externally in a separate file, they can also be defined inline and can be instantiated immediately.

Related Information

API Reference: sap.ui.core.mvc.Controller.prototype.loadFragment

API Reference: sap.ui.core.Fragment.load