Skip to content

Fragment Class

The UI5 Antares library includes a built-in class (FragmentCL) providing a set of public methods to load the contents of a fragment file (*.fragment.xml) and to open a dialog or a popover.

Info

The Custom Control From Fragment and Custom Content From Fragment methods of the Entry classes also use the FragmentCL class.

Constructor

In order to utilise the functionality of FragmentCL, it is necessary to initialise the object.

Parameter Type Mandatory Default Value Description
controller sap.ui.core.mvc.Controller Yes The controller object (usually this object)
fragmentPath string Yes The path of the fragment whose content will be loaded or opened
openByControl? sap.ui.core.Control No If the loaded fragment contains a popover, this parameter determines which control the popover opens next to. For example: sap.m.Button

Example

Let us assume that we have created a file with the extension .fragment.xml and the following content. Our objective is to open the dialog in the controller.

Dialog.fragment.xml
<core:FragmentDefinition
    xmlns:form="sap.ui.layout.form"
    xmlns="sap.m"
    xmlns:core="sap.ui.core"
>
    <Dialog title="Create New Product">
        <form:SimpleForm>
            <form:content>
                <Label text="Product ID" />
                <MaskInput
                    mask="CCCCCCCC-CCCC-CCCC-CCCC-CCCCCCCCCCCC"
                    value="{ID}"
                    placeholderSymbol="_"
                >
                    <rules>
                        <MaskInputRule
                            maskFormatSymbol="C"
                            regex="[a-f0-9]"
                        />
                    </rules>
                </MaskInput>
                <Label text="Name" />
                <Input value="{name}" />
                <Label text="Description" />
                <TextArea
                    value="{description}"
                    rows="5"
                />
                <Label text="Price" />
                <Slider
                    width="100%"
                    min="1000"
                    max="100000"
                    showAdvancedTooltip="true"
                    showHandleTooltip="true"
                    inputsAsTooltips="true"
                    enableTickmarks="true"
                    step="1000"
                    class="sapUiMediumMarginBottom"
                    value="{price}"
                />
                <Label text="Currency" />
                <ComboBox selectedKey="{currency}">
                    <items>
                        <core:Item
                            key="EUR"
                            text="Euro"
                        />
                        <core:Item
                            key="USD"
                            text="US Dollar"
                        />
                        <core:Item
                            key="TRY"
                            text="Turkish Lira"
                        />
                    </items>
                </ComboBox>
            </form:content>
        </form:SimpleForm>
        <beginButton>
            <Button
                text="Complete"
                press="onCompleteProduct"
            />
        </beginButton>
        <endButton>
            <Button
                text="Close"
                press="onCloseProductDialog"
            />
        </endButton>
    </Dialog>
</core:FragmentDefinition>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
import Controller from "sap/ui/core/mvc/Controller";
import FragmentCL from "ui5/antares/ui/FragmentCL"; // Import the class

/**
 * @namespace your.apps.namespace
 */
export default class YourController extends Controller {
  public onInit() {

  }

  public async onOpenDialog() {
    // Initialize with the controller and fragment path
    const fragment = new FragmentCL(this, "your.apps.namespace.fragments.FragmentFileName");
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
sap.ui.define([
    "sap/ui/core/mvc/Controller",
    "ui5/antares/ui/FragmentCL" // Import the class
], 
    /**
     * @param {typeof sap.ui.core.mvc.Controller} Controller
     */
    function (Controller, FragmentCL) {
      "use strict";

      return Controller.extend("your.apps.namespace.YourController", {
        onInit: function () {

        },

        onOpenDialog: async function () {
          // Initialize with the controller and fragment path
          const fragment = new FragmentCL(this, "your.apps.namespace.fragments.FragmentFileName");
        }
      });

    });

Load Content

To load the content from a fragment file, the load(): Promise<Control | Control[]> method can be utilized.

Info

In the event that the fragment contains more than one UI control, the load() method will return an array containing the UI controls. Conversely, for single content, the load() method will return the UI control itself.

Attention

Please be aware that the load() method is asynchronous and must be awaited.

Example

Let us assume that we have created a file with the extension .fragment.xml with the following content. We would now like to use the sap.m.Text in the controller.

Text.fragment.xml
<core:FragmentDefinition
    xmlns:form="sap.ui.layout.form"
    xmlns="sap.m"
    xmlns:core="sap.ui.core"
>
    <Text text="My Text" />
</core:FragmentDefinition>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
import Controller from "sap/ui/core/mvc/Controller";
import FragmentCL from "ui5/antares/ui/FragmentCL"; // Import the class
import Text from "sap/m/Text";

/**
 * @namespace your.apps.namespace
 */
export default class YourController extends Controller {
  public onInit() {

  }

  public async onLoadFragment() {
    // Initialize with the controller and fragment path
    const fragment = new FragmentCL(this, "your.apps.namespace.fragments.FragmentFileName");

    // load the content of the fragment
    const content = await fragment.load() as unknown as Text;

    // use the content
    console.log(content.getText());
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
sap.ui.define([
    "sap/ui/core/mvc/Controller",
    "ui5/antares/ui/FragmentCL" // Import the class
], 
    /**
     * @param {typeof sap.ui.core.mvc.Controller} Controller
     */
    function (Controller, FragmentCL) {
      "use strict";

      return Controller.extend("your.apps.namespace.YourController", {
        onInit: function () {

        },

        onLoadFragment: async function () {
          // Initialize with the controller and fragment path
          const fragment = new FragmentCL(this, "your.apps.namespace.fragments.FragmentFileName");

          // load the content of the fragment
          const content = await fragment.load();

          // use the content
          console.log(content.getText());
        }
      });

    });

Open Dialog or Popover

There are two distinct methods for opening a dialog or popover from a fragment file.

Attention

Please be advised that both methods support only the following dialog and popover classes:

Tip

Both methods include an optional parameter named viewDependent: boolean. Should you wish to add the dialog or popover as a dependent to your view, please set this parameter to true.

Open Sync

In order to utilise the open() method, it is essential to first execute the load() method.

To utilize the open() method, it is essential to first execute the load() method.

Info

The open() method returns the dialog or popover loaded from a fragment using the load() method.

Attention

When opening a popover, it is necessary to set the control that the popover opens next to. Please refer to the constructor documentation for further information.

Dialog Example

Let us assume that we have created a file with the extension .fragment.xml with the following content. We would now like to open the dialog in the controller.

Dialog.fragment.xml
<core:FragmentDefinition
    xmlns:form="sap.ui.layout.form"
    xmlns="sap.m"
    xmlns:core="sap.ui.core"
>
    <Dialog title="Create New Product">
        <form:SimpleForm>
            <form:content>
                <Label text="Product ID" />
                <MaskInput
                    mask="CCCCCCCC-CCCC-CCCC-CCCC-CCCCCCCCCCCC"
                    value="{ID}"
                    placeholderSymbol="_"
                >
                    <rules>
                        <MaskInputRule
                            maskFormatSymbol="C"
                            regex="[a-f0-9]"
                        />
                    </rules>
                </MaskInput>
                <Label text="Name" />
                <Input value="{name}" />
                <Label text="Description" />
                <TextArea
                    value="{description}"
                    rows="5"
                />
            </form:content>
        </form:SimpleForm>
        <beginButton>
            <Button
                text="Complete"
                press="onCompleteProduct"
            />
        </beginButton>
        <endButton>
            <Button
                text="Close"
                press="onCloseProductDialog"
            />
        </endButton>
    </Dialog>
</core:FragmentDefinition>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
import Controller from "sap/ui/core/mvc/Controller";
import FragmentCL from "ui5/antares/ui/FragmentCL"; // Import the class

/**
 * @namespace your.apps.namespace
 */
export default class YourController extends Controller {
  public onInit() {

  }

  public async openDialog() {
    // Initialize with the controller and fragment path
    const fragment = new FragmentCL(this, "your.apps.namespace.fragments.FragmentFileName");

    // load the content of the fragment
    await fragment.load();

    // open the dialog
    fragment.open();
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
sap.ui.define([
    "sap/ui/core/mvc/Controller",
    "ui5/antares/ui/FragmentCL" // Import the class
], 
    /**
     * @param {typeof sap.ui.core.mvc.Controller} Controller
     */
    function (Controller, FragmentCL) {
      "use strict";

      return Controller.extend("your.apps.namespace.YourController", {
        onInit: function () {

        },

        openDialog: async function () {
          // Initialize with the controller and fragment path
          const fragment = new FragmentCL(this, "your.apps.namespace.fragments.FragmentFileName");

          // load the content of the fragment
          await fragment.load();

          // open the dialog
          fragment.open();
        }
      });

    });

Popover Example

Let us assume that we have created a file with the extension .fragment.xml and the following content. We would now like to open the popover in the controller.

Popover.fragment.xml
<core:FragmentDefinition
    xmlns:form="sap.ui.layout.form"
    xmlns="sap.m"
    xmlns:core="sap.ui.core"
>
    <Popover>
        <content>
            <Text text="Test" />
            <Button
                text="Finish"
                press="onFinish"
            />
        </content>
    </Popover>
</core:FragmentDefinition>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
import Controller from "sap/ui/core/mvc/Controller";
import FragmentCL from "ui5/antares/ui/FragmentCL"; // Import the class
import Button from "sap/m/Button";

/**
 * @namespace your.apps.namespace
 */
export default class YourController extends Controller {
  public onInit() {

  }

  public async openPopover() {
    // Initialize with the controller and fragment path and the open by control
    const fragment = new FragmentCL(this, "your.apps.namespace.fragments.FragmentFileName", this.getView()?.byId("myButton") as Button);

    // load the content of the fragment
    await fragment.load();

    // open the dialog
    fragment.open();
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
sap.ui.define([
    "sap/ui/core/mvc/Controller",
    "ui5/antares/ui/FragmentCL" // Import the class
], 
    /**
     * @param {typeof sap.ui.core.mvc.Controller} Controller
     */
    function (Controller, FragmentCL) {
      "use strict";

      return Controller.extend("your.apps.namespace.YourController", {
        onInit: function () {

        },

        openPopover: async function () {
          // Initialize with the controller and fragment path and the open by control
          const fragment = new FragmentCL(this, "your.apps.namespace.fragments.FragmentFileName", this.getView().byId("myButton"));

          // load the content of the fragment
          await fragment.load();

          // open the dialog
          fragment.open();
        }
      });

    });

Open Async

The openAsync() method first executes the load() method internally, and then opens the dialog or popover.

Info

The openAsync() method returns the dialog or popover loaded from a fragment.

Attention

When opening a popover, it is necessary to set the control that the popover opens next to. Please refer to the constructor documentation for further information.

Tip

Please be aware that the openAsync() method is asynchronous. To retrieve the dialog or popover, please await the openAsync() method.

Dialog Example

Let us assume that we have created a file with the extension .fragment.xml and the following content. We would now like to open the dialog in the controller.

Dialog.fragment.xml
<core:FragmentDefinition
    xmlns:form="sap.ui.layout.form"
    xmlns="sap.m"
    xmlns:core="sap.ui.core"
>
    <Dialog title="Create New Product">
        <form:SimpleForm>
            <form:content>
                <Label text="Product ID" />
                <MaskInput
                    mask="CCCCCCCC-CCCC-CCCC-CCCC-CCCCCCCCCCCC"
                    value="{ID}"
                    placeholderSymbol="_"
                >
                    <rules>
                        <MaskInputRule
                            maskFormatSymbol="C"
                            regex="[a-f0-9]"
                        />
                    </rules>
                </MaskInput>
                <Label text="Name" />
                <Input value="{name}" />
                <Label text="Description" />
                <TextArea
                    value="{description}"
                    rows="5"
                />
            </form:content>
        </form:SimpleForm>
        <beginButton>
            <Button
                text="Complete"
                press="onCompleteProduct"
            />
        </beginButton>
        <endButton>
            <Button
                text="Close"
                press="onCloseProductDialog"
            />
        </endButton>
    </Dialog>
</core:FragmentDefinition>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
import Controller from "sap/ui/core/mvc/Controller";
import FragmentCL from "ui5/antares/ui/FragmentCL"; // Import the class

/**
 * @namespace your.apps.namespace
 */
export default class YourController extends Controller {
  public onInit() {

  }

  public async openDialog() {
    // Initialize with the controller and fragment path
    const fragment = new FragmentCL(this, "your.apps.namespace.fragments.FragmentFileName");

    // open the dialog
    fragment.openAsync();
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
sap.ui.define([
    "sap/ui/core/mvc/Controller",
    "ui5/antares/ui/FragmentCL" // Import the class
], 
    /**
     * @param {typeof sap.ui.core.mvc.Controller} Controller
     */
    function (Controller, FragmentCL) {
      "use strict";

      return Controller.extend("your.apps.namespace.YourController", {
        onInit: function () {

        },

        openDialog: async function () {
          // Initialize with the controller and fragment path
          const fragment = new FragmentCL(this, "your.apps.namespace.fragments.FragmentFileName");

          // open the dialog
          fragment.openAsync();
        }
      });

    });

Popover Example

Let us assume that we have created a file with the extension .fragment.xml and the following content. We would now like to open the popover in the controller.

Popover.fragment.xml
<core:FragmentDefinition
    xmlns:form="sap.ui.layout.form"
    xmlns="sap.m"
    xmlns:core="sap.ui.core"
>
    <Popover>
        <content>
            <Text text="Test" />
            <Button
                text="Finish"
                press="onFinish"
            />
        </content>
    </Popover>
</core:FragmentDefinition>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
import Controller from "sap/ui/core/mvc/Controller";
import FragmentCL from "ui5/antares/ui/FragmentCL"; // Import the class
import Button from "sap/m/Button";

/**
 * @namespace your.apps.namespace
 */
export default class YourController extends Controller {
  public onInit() {

  }

  public async openPopover() {
    // Initialize with the controller and fragment path and the open by control
    const fragment = new FragmentCL(this, "your.apps.namespace.fragments.FragmentFileName", this.getView()?.byId("myButton") as Button);

    // open the dialog
    fragment.openAsync();
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
sap.ui.define([
    "sap/ui/core/mvc/Controller",
    "ui5/antares/ui/FragmentCL" // Import the class
], 
    /**
     * @param {typeof sap.ui.core.mvc.Controller} Controller
     */
    function (Controller, FragmentCL) {
      "use strict";

      return Controller.extend("your.apps.namespace.YourController", {
        onInit: function () {

        },

        openPopover: async function () {
          // Initialize with the controller and fragment path and the open by control
          const fragment = new FragmentCL(this, "your.apps.namespace.fragments.FragmentFileName", this.getView().byId("myButton"));

          // open the dialog
          fragment.openAsync();
        }
      });

    });

Close Dialog or Popover

To close the dialog or popover that was opened by any of the approaches listed below, you will need to use the close() or closeAndDestroy() method.

1) load() and open()

2) openAsync()

Attention

Please be advised that it is your responsibility to destroy the content after using the close() method. This can be achieved by using the destroyFragmentContent() method. Alternatively, if you use the closeAndDestroy() method, the content will be destroyed automatically.

Example

Let us assume that we have created a file with the extension .fragment.xml with the following content. We would now like to open the dialog in the controller. When the user presses the Close button, we will close the dialog and destroy it.

Dialog.fragment.xml
<core:FragmentDefinition
    xmlns:form="sap.ui.layout.form"
    xmlns="sap.m"
    xmlns:core="sap.ui.core"
>
    <Dialog title="Create New Product">
        <form:SimpleForm>
            <form:content>
                <Label text="Product ID" />
                <MaskInput
                    mask="CCCCCCCC-CCCC-CCCC-CCCC-CCCCCCCCCCCC"
                    value="{ID}"
                    placeholderSymbol="_"
                >
                    <rules>
                        <MaskInputRule
                            maskFormatSymbol="C"
                            regex="[a-f0-9]"
                        />
                    </rules>
                </MaskInput>
                <Label text="Name" />
                <Input value="{name}" />
                <Label text="Description" />
                <TextArea
                    value="{description}"
                    rows="5"
                />
            </form:content>
        </form:SimpleForm>
        <beginButton>
            <Button
                text="Complete"
                press="onCompleteProduct"
            />
        </beginButton>
        <endButton>
            <Button
                text="Close"
                press="onCloseDialog"
            />
        </endButton>
    </Dialog>
</core:FragmentDefinition>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
import Controller from "sap/ui/core/mvc/Controller";
import FragmentCL from "ui5/antares/ui/FragmentCL"; // Import the class

/**
 * @namespace your.apps.namespace
 */
export default class YourController extends Controller {
  private fragment: FragmentCL; // The class property

  public onInit() {

  }

  public async openDialog() {
    // Initialize with the controller and fragment path and set to the class property
    this.fragment = new FragmentCL(this, "your.apps.namespace.fragments.FragmentFileName");

    // open the dialog
    this.fragment.openAsync();
  }

  public async onCloseDialog () {
    this.fragment.close(); // close the dialog
    this.fragment.destroyFragmentContent(); // do not forget to destroy after closing
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
sap.ui.define([
    "sap/ui/core/mvc/Controller",
    "ui5/antares/ui/FragmentCL" // Import the class
], 
    /**
     * @param {typeof sap.ui.core.mvc.Controller} Controller
     */
    function (Controller, FragmentCL) {
      "use strict";

      return Controller.extend("your.apps.namespace.YourController", {
        onInit: function () {

        },

        openDialog: async function () {
          // Initialize with the controller and fragment path and set to the class property
          this.fragment = new FragmentCL(this, "your.apps.namespace.fragments.FragmentFileName");

          // open the dialog
          this.fragment.openAsync();
        },

        onCloseDialog: async function () {
          this.fragment.close(); // close the dialog
          this.fragment.destroyFragmentContent(); // do not forget to destroy after closing
        }
      });

    });

Get Fragment Content

To retrieve the content loaded from a fragment file using the load() or openAsync() method, the getFragmentContent() method can be utilized.

Returns Description
Control | Control[] Returns the control or controls loaded from a fragment file using the load() or openAsync() method

Destroy Fragment Content

To destroy the content loaded from a fragment using the load() or openAsync() methods, the destroyFragmentContent() method can be utilized.

Attention

Should you wish to destroy the content of the dialog when the user presses the ESC button on the keyboard, we advise you to use the setAutoDestroyOnESC(destroy: boolean) method and set the parameter of the method to true. Otherwise, you will be responsible for destroying the content when the user presses the ESC button. Please note that if the content is not destroyed in each ESC event, the dialog cannot be loaded again.

Example

Let us assume that we have created a file with the extension .fragment.xml and the following content. We would now like to open the dialog in the controller. When the user presses the Close button, we will close the dialog and destroy it.

Dialog.fragment.xml
<core:FragmentDefinition
    xmlns:form="sap.ui.layout.form"
    xmlns="sap.m"
    xmlns:core="sap.ui.core"
>
    <Dialog title="Create New Product">
        <form:SimpleForm>
            <form:content>
                <Label text="Product ID" />
                <MaskInput
                    mask="CCCCCCCC-CCCC-CCCC-CCCC-CCCCCCCCCCCC"
                    value="{ID}"
                    placeholderSymbol="_"
                >
                    <rules>
                        <MaskInputRule
                            maskFormatSymbol="C"
                            regex="[a-f0-9]"
                        />
                    </rules>
                </MaskInput>
                <Label text="Name" />
                <Input value="{name}" />
                <Label text="Description" />
                <TextArea
                    value="{description}"
                    rows="5"
                />
            </form:content>
        </form:SimpleForm>
        <beginButton>
            <Button
                text="Complete"
                press="onCompleteProduct"
            />
        </beginButton>
        <endButton>
            <Button
                text="Close"
                press="onCloseDialog"
            />
        </endButton>
    </Dialog>
</core:FragmentDefinition>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
import Controller from "sap/ui/core/mvc/Controller";
import FragmentCL from "ui5/antares/ui/FragmentCL"; // Import the class

/**
 * @namespace your.apps.namespace
 */
export default class YourController extends Controller {
  private fragment: FragmentCL; // The class property

  public onInit() {

  }

  public async openDialog() {
    // Initialize with the controller and fragment path and set to the class property
    this.fragment = new FragmentCL(this, "your.apps.namespace.fragments.FragmentFileName");

    // open the dialog
    this.fragment.openAsync();
  }

  public async onCloseDialog () {
    this.fragment.close(); // close the dialog
    this.fragment.destroyFragmentContent(); // do not forget to destroy after closing
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
sap.ui.define([
    "sap/ui/core/mvc/Controller",
    "ui5/antares/ui/FragmentCL" // Import the class
], 
    /**
     * @param {typeof sap.ui.core.mvc.Controller} Controller
     */
    function (Controller, FragmentCL) {
      "use strict";

      return Controller.extend("your.apps.namespace.YourController", {
        onInit: function () {

        },

        openDialog: async function () {
          // Initialize with the controller and fragment path and set to the class property
          this.fragment = new FragmentCL(this, "your.apps.namespace.fragments.FragmentFileName");

          // open the dialog
          this.fragment.openAsync();
        },

        onCloseDialog: async function () {
          this.fragment.close(); // close the dialog
          this.fragment.destroyFragmentContent(); // do not forget to destroy after closing
        }
      });

    });