Preview

An e-mail link is added to the address panel

Coding

You can view and download all files in the Demo Kit at Data Binding - Step 9.

1. Create a new folder named controller within your webapp folder as a general location for all controller files for this app. Next, create a new file named App.controller.js with the following content:

   webapp/controller/App.controller.js (New)

   Hidden

   sap.ui.define([
   	"sap/m/library",
   	"sap/ui/core/mvc/Controller"
   ], (mobileLibrary, Controller) => {
   	"use strict";
   
   	return Controller.extend("ui5.databinding.controller.App", {
   		formatMail(sFirstName, sLastName) {
   			const oBundle = this.getView().getModel("i18n").getResourceBundle();
   
   			return mobileLibrary.URLHelper.normalizeEmail(
   				`${sFirstName}.${sLastName}@example.com`,
   				oBundle.getText("mailSubject", [sFirstName]),
   				oBundle.getText("mailBody"));
   		}
   	});
   });

   In our custom formatter, we set the first and last name currently in the model as function parameters. When a user changes the data in the model by entering a different name in the input fields, our formatter will be invoked automatically by the framework. This ensures that the UI stays in sync with the data model.

   In the formatMail function, we use the sap.m.URLHelper.normalizeEmail function that expects an e-mail address, a mail subject, and a text body. When a user follows the link, their default email client will open with these parameters. For more information, see API Reference: sap.m.URLHelper.normalizeEmail. The mailSubject resource bundle text contains a placeholder for the recipient's first name (see below). Therefore, we provide the name with [sFirstName].

   Note

   For a detailed description of the e-mail link format, see https://developer.mozilla.org/de/docs/Web/Guide/HTML/Email_links.

2. Enhance the App.view.xml file as shown below:

   webapp/view/App.view.xml

   Hidden

   <mvc:View
   	controllerName="ui5.databinding.controller.App"
   	xmlns="sap.m"
   	xmlns:form="sap.ui.layout.form"
   	xmlns:l="sap.ui.layout"
   	xmlns:mvc="sap.ui.core.mvc">
   	...
   	<Panel headerText="{i18n>panel2HeaderText}" class="sapUiResponsiveMargin" width="auto">
   		<content>
   			<l:VerticalLayout>
   				<Label labelFor="address" text="{i18n>address}:"/>
   				<FormattedText class="sapUiSmallMarginBottom"
   					htmlText="{/address/street}&lt;br>{/address/zip} {/address/city}&lt;br>{/address/country}"
   					id="address" width="200px"/>
   				<Link href="{
   						parts: [
   							'/firstName',
   							'/lastName'
   						],
   						formatter: '.formatMail'
   					}"
   					text="{i18n>sendEmail}"/>
   			</l:VerticalLayout>
   		</content>
   	</Panel>
   </mvc:View>

   For more complex bindings, we can't use the simple binding syntax with the curly braces anymore. The href property of the Link element now contains an entire object inside the string value. In this case, the object has two properties:

   • parts

     This is a JavaScript array in which each element is a string representing a path property. The number and order of the elements in this array correspond directly to the number and order of parameters expected by the formatMail function.

   • formatter

     This is a reference to the function that receives the parameters listed in the parts array. Whatever value the formatter function returns becomes the value set for the href property. The dot ( formatMail) at the beginning of the formatter tells SAPUI5 to look for a formatMail function on the controller instance of the view. If you don't use the dot, the function will be resolved by looking into the global namespace.

   Note

   When using formatter functions, the binding automatically switches to "one-way". Therefore, you can't use a formatter function for "two-way" scenarios. However, you can use data types (which we explain in the following steps).

3. Add the # E-mail section to the i18n.properties and i18n_de.properties files as shown below.

   webapp/i18n/i18n.properties

   Hidden

   …
   # Screen titles
   panel1HeaderText=Data Binding Basics 
   panel2HeaderText=Address Details
   
   # E-mail
   sendEmail=Send Mail
   mailSubject=Hi {0}!
   mailBody=How are you?

   webapp/i18n/i18n_de.properties

   Hidden

   …
   # Screen titles
   panel1HeaderText=Data Binding Grundlagen
   panel2HeaderText=Adressdetails
   
   # E-mail
   sendEmail=E-mail versenden
   mailSubject=Hallo {0}!
   mailBody=Wie geht es dir?