ui5-typescript-walkthrough
Step 16: Dialogs and Fragments
In this step, we will take a closer look at another element which can be used to assemble views: the fragment.
Fragments are light-weight UI parts (UI subtrees) which can be reused but do not have any controller. This means, whenever you want to define a certain part of your UI to be reusable across multiple views, or when you want to exchange some parts of a view against one another under certain circumstances (different user roles, edit mode vs read-only mode), a fragment is a good candidate, especially where no additional controller logic is required.
A fragment can consist of 1 to n controls. At runtime, fragments placed in a view behave similar to “normal” view content, which means controls inside the fragment will just be included into the view’s DOM when rendered. There are of course controls that are not designed to become part of a view, for example, dialogs. But even for these controls, fragments can be particularly useful, as you will see in a minute.
We will now add a dialog to our app. Dialogs are special, because they open on top of the regular app content and thus do not belong to a specific view. That means the dialog must be instantiated somewhere in the controller code, but since we want to stick with the declarative approach and create reusable artifacts to be as flexible as possible, we will create an XML fragment containing the dialog. A dialog, after all, can be used in more than one view of your app.
Preview
A dialog opens when the new “Say Hello With Dialog” button is clicked
You can access the live preview by clicking on this link: 🔗 Live Preview of Step 16.
To download the solution for this step as a zip file, just choose the link here: 📥 Download Solution for Step 16.
Coding
webapp/view/HelloDialog.fragment.xml (New)
We add a new XML file to declaratively define our dialog in a fragment. The fragment assets are located in the core namespace, so we add an xml namespace for it inside the FragmentDefinition tag.
<core:FragmentDefinition
xmlns="sap.m"
xmlns:core="sap.ui.core" >
<Dialog
id="helloDialog"
title="Hello {/recipient/name}"/>
</core:FragmentDefinition>
The syntax is similar to a view, but since fragments do not have a controller this attribute is missing. Also, the fragment does not have any footprint in the DOM tree of the app, and there is no control instance of the fragment itself (only the contained controls). It is simply a container for a set of reuse controls.
webapp/controller/HelloPanel.controller.ts
In the HelloPanel controller, we define a new event handler function onOpenDialog which calls the dialog in the HelloDialog fragment when triggered. To do so we need to import the sap.m.Dialog module.
Using async/await, we handle the opening of the dialog asynchronously whenever the event is triggered.
If the dialog fragment does not exist yet, the fragment is instantiated by calling the loadFragment API. We then store the dialog on the controller instance. This allows us to reuse the dialog every time the event is triggered again.
import Controller from "sap/ui/core/mvc/Controller";
import MessageToast from "sap/m/MessageToast";
import JSONModel from "sap/ui/model/json/JSONModel";
import ResourceModel from "sap/ui/model/resource/ResourceModel";
import ResourceBundle from "sap/base/i18n/ResourceBundle";
import Dialog from "sap/m/Dialog";
/**
* @namespace ui5.walkthrough.controller
*/
export default class HelloPanel extends Controller {
private dialog : Dialog;
onShowHello(): void {
...
}
async onOpenDialog(): Promise<void> {
this.dialog ??= await this.loadFragment({
name: "ui5.walkthrough.view.HelloDialog"
}) as Dialog;
this.dialog.open();
}
};
💡 Tip:
To reuse the dialog opening and closing functionality in other controllers, you might create a new fileui5.walkthrough.controller.controller.BaseController, which extendssap.ui.core.mvc.Controller, and put all your dialog-related coding into this controller. Now, all the other controllers can extend fromui5.walkthrough.controller.BaseControllerinstead ofsap.ui.core.mvc.Controller.
webapp/i18n/i18n.properties
We add a new text for the button to open the dialog to the text bundle. We will add this button to the HelloPanel view in the next step.
...
# Hello Panel
showHelloButtonText=Say Hello
helloMsg=Hello {0}
homePageTitle=UI5 TypeScript Walkthrough
helloPanelTitle=Hello World
openDialogButtonText=Say Hello With Dialog
webapp/view/HelloPanel.view.xml
We add a new button to the view to open the dialog and assign an unique idto it. The button calls the event handler function onOpenDialog in the controller of the panel’s content view. We assign the new text to the text property of the button and refer class to sapUiResponsiveMargin to pimp up the design.
<mvc:View
controllerName="ui5.walkthrough.controller.HelloPanel"
xmlns="sap.m"
xmlns:mvc="sap.ui.core.mvc">
<Panel
headerText="{i18n>helloPanelTitle}"
class="sapUiResponsiveMargin"
width="auto" >
<content>
<Button
id="helloDialogButton"
text="{i18n>openDialogButtonText}"
press=".onOpenDialog"
class="sapUiSmallMarginEnd"/>
<Button
text="{i18n>showHelloButtonText}"
press=".onShowHello"
class="myCustomButton"/>
<Input
value="{/recipient/name}"
valueLiveUpdate="true"
width="60%"/>
<FormattedText
htmlText="Hello {/recipient/name}"
class="sapUiSmallMargin sapThemeHighlight-asColor myCustomText"/>
</content>
</Panel>
</mvc:View>
You will need the id of the button control id="helloDialogButton" in Step 28: Integration Test with OPA.
It is a good practice to set a unique ID like helloWorldButton to key controls of your app so that can be identified easily. If the attribute `id` is not specified, the OpenUI5 runtime generates unique but changing ID like `__button23` for the control. Inspect the DOM elements of your app in the browser to see the difference.
Next: Step 17: Fragment Callbacks
Previous: Step15: Nested Views
Related Information
Dialogs and other Popups as Fragments