sap ui5 reference for sap hana en

PUBLIC

SAP HANA Platform SPS 07Document Version: 1.1 - 13-03-2014

SAPUI5 Reference for SAP HANA

Table of Contents1 Building User Interfaces with SAPUI5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.1 Installing SAPUI5 Application Tools. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51.2 Getting Started with SAPUI5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5

1.2.1 Choose Your Browser. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61.2.2 Create your First Mobile App using SAPUI5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141.2.3 Create Your First SAPUI5 Application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .211.2.4 Develop Your First Application using SAPUI5 Tools. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .241.2.5 Support Translation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .451.2.6 Testing SAPUI5 Applications Locally. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471.2.7 Running SAPUI5 Applications on SAP HANA. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

1.3 Concepts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491.3.1 Model-View-Controller (MVC). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .501.3.2 Resource Handling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 591.3.3 Libraries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 601.3.4 SAPUI5 Components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 621.3.5 Extensibility Concept: Adapting SAPUI5 Applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

1.4 Developing User Interfaces with SAPUI5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 641.4.1 Bootstrapping and Configuration of SAPUI5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .651.4.2 UI Control Constructors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 831.4.3 UI Control API: Event Handling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 831.4.4 Models and Data Binding. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 841.4.5 Implementing Views. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1251.4.6 Custom Data - Attaching Data Objects to Controls. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1301.4.7 Declarative Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1331.4.8 SAPUI5 Components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1391.4.9 Defining a Component for SAPUI5 from Scratch. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1411.4.10 Component Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1451.4.11 Extensibility Concept: Adapting SAPUI5 Applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1471.4.12 Navigation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1541.4.13 HTML Templating in SAPUI5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1591.4.14 Expressions and Helpers for HTML Templating. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1601.4.15 Example: Use of HTML Templating in SAPUI5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1611.4.16 Modularization and Resource Handling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1631.4.17 Control Devlopment Topics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1791.4.18 Building Mobile Applications with SAPUI5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2051.4.19 Testing SAPUI5 Applications in Eclipse. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2661.4.20 UI development toolkit for HTML5 Test Suite. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2711.4.21 Localized Texts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273

1.5 References. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277

2P U B L I C© 2014 SAP AG or an SAP affiliate company. All rights reserved.

SAPUI5 Reference for SAP HANATable of Contents

1.5.1 Compatibility Rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2771.5.2 Naming Conventions for Control and Application Development. . . . . . . . . . . . . . . . . . . . . . 2801.5.3 Typed Views and Controllers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2831.5.4 File Names and Locations (View and Controller). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2861.5.5 Troubleshooting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2861.5.6 Security Concepts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299

2 Important Disclaimers on Legal Aspects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302

SAPUI5 Reference for SAP HANATable of Contents

P U B L I C© 2014 SAP AG or an SAP affiliate company. All rights reserved. 3

1 Building User Interfaces with SAPUI5UI development toolkit for HTML5 (SAPUI5) is a user interface technology that is used to build and adapt client applications based on SAP HANA. You can install SAPUI5 in the SAP HANA studio to build user interfaces delivered by SAP HANA's Web server.

SAPUI5 runtime is a client-side HTML5 rendering library with a rich set of standard and extension controls and a lightweight programming model. To support you in developing applications, SAPUI5 application development tools comes with a set of eclipse-based wizards and editors. SAPUI5 application development tools provides wizards to create application projects and views according to the model-view-controller concept and other features like JavaScript code completion, templates and snippets, and in-place application preview.

SAPUI5 provides many features to enable you to easily create and extend state-of-the-art user interfaces. SAPUI5 supports the following features:

● RIA-like client-side features based on JavaScript● CSS3, which allows you to adapt themes to your company's branding in an effective manner● Extensibility concept regarding custom controls, meaning that you can extend existing SAPUI5 controls as

well as develop your own controls● Open source jQuery library used as foundation● Full support of the SAP product standard● Compliance to Open Ajax; can be used together with standard JavaScript libraries● Produced in a release independent code line to enable short shipment cycles

SAPUI5 SDK

The SAPUI5 SDK (Demo Kit) provides the following sections:

● Developer Guide with additional information about SAPUI5, the used programming languages, open source technologies, development tools, and APIs

● Controls containing running demo examples with descriptions and source codes● API reference with JavaScript documentation of Framework and Control API● Test Suite, which shows all controls running with different property settings where you can interactively adapt

the controls you use for test purposes

The Demo Kit is installed as a delivery unit. To directly access the Demo Kit, use the following link and replace the placeholders accordingly: <xsengine protocol>://<xsengine server>:<xsengine port>/sap/ui5/1/sdk/index.html.

Related Information

Installing SAPUI5 Application Tools [page 5]This section provides a short description how to install SAPUI5 tools for SAP HANA.

Getting Started with SAPUI5 [page 5]Here you find information on how to adjust your enviroment and to get started with some easy examples including an introduction to the SAPUI5 tools.


SAPUI5 Reference for SAP HANABuilding User Interfaces with SAPUI5

Concepts [page 49]Overview on the architecture and concepts of SAPUI5

Developing User Interfaces with SAPUI5 [page 64]

1.1 Installing SAPUI5 Application Tools

This section provides a short description how to install SAPUI5 tools for SAP HANA.

Before you start the installation of SAPUI5 application development tools, make sure that you comply with the following requirements:

● SAP HANA studio is installed.● SAPUI5 application development tools are downloaded from the SAP Software Download Center on SAP

Service Marketplace (http://service.sap.com/swdc ) and search for SAPUI5 TOOLS IDE PLUGIN 1.00.

For more information about the installation of SAPUI5 application development tools, see the SAPUI 5 Installation

Guide for SAP HANA on SAP Service Marketplace or SAP Note 1747308 .

1.2 Getting Started with SAPUI5

Here you find information on how to adjust your enviroment and to get started with some easy examples including an introduction to the SAPUI5 tools.

Choose your browser

Before you really get started, check the list of supported browsers to choose one that fits your needs.

Browser Support: SAPUI5 for Desktop [page 6]

Browser Support: SAPUI5 for Mobile [page 12]

Create applications using SAPUI5 tools

Using the SAPUI5 application tools in Eclipse allows you to create sophisticated SAPUI5 application projects based on the Model View Controller concept. The tools provide additional features such as SAPUI5 Snippets or JavaScript Templates.

Develop Your First Application using SAPUI5 Tools [page 24]



http://help.sap.com/disclaimer?site=http://service.sap.com/swdc

http://help.sap.com/disclaimer?site=https://service.sap.com/sap/support/notes/1747308

Supporting Translation

Support Translation [page 45]

Testing SAPUI5 applications

Testing SAPUI5 Applications Locally [page 47]

1.2.1 Choose Your Browser

You need to check which browser suits best to your use case.

Supported Browsers

For displaying Mobile apps for testing purposes locally on your Desktop computer, you need a WebKit based browser such as Google Chrome.

Related Information

Browser Support: SAPUI5 for Desktop [page 6]The UI development toolkit for HTML5 (SAPUI5) is a control library based on CSS3, HTML5 and the new JavaScript API. That's why only browsers with HTML5 capabilities are supported.

Browser Support: SAPUI5 for Mobile [page 12]

1.2.1.1 Browser Support: SAPUI5 for Desktop

The UI development toolkit for HTML5 (SAPUI5) is a control library based on CSS3, HTML5 and the new JavaScript API. That's why only browsers with HTML5 capabilities are supported.

Browser Support for Core and Standard Libraries

Note

Also refer to SAP note 1716423



http://help.sap.com/disclaimer?site=https://service.sap.com/sap/support/notes/ 1716423

Supported Browsers

The following browsers are supported for Microsoft Windows platforms only:

● Microsoft Internet Explorer 9 and upwards, so including Microsoft Internet Explorer 10● Mozilla Firefox 17 (aka Firefox Extended Support Release - ESR) and latest version● Google Chrome latest version

The following browser is only supported for MAC OS X:

● Safari 5.1 and upwards

Browsers with Restricted Support

Internet Explorer 8 (IE8): There are degradations in visual design and over time also restricted functionality.

For more information, see

● Degradations by Feature.● Degradations by Control [page 10]

Not supported Browsers

Internet Explorer 6 and 7 are not supported. All browsers not mentioned above are also not supported.

Browser Support for VIZ Charting

The VIZ charting library (sap.viz) relies on the open source component D3 which in turn relies on the availability of Scalable Vector Graphics (SVG). As SVG is not supported by IE8 and not fully supported by FF ESR, the VIZ charting library is also not supported on those browsers.

1.2.1.1.1 Degradations by Feature

The following sections describe the degradations for older Browser versions, such as FireFox 3.6 or Internet Explorer 8 (IE8).



Rounded Corners

IE8 and lower versions of IE do not support the CSS property border-radius. As a result, controls in themes that use this property have square corners instead of rounded corners.

In the UX theme this affects the following controls:

● Button● ComboBox● DatePicker and its popup● DropdownBox● ListBox● MessageBar● Panel● ProgressIndicator● TextArea● TextField

Button in FireFox 3.6 Button in Internet Explorer 8

Box Shadow

IE 8 and lower versions of IE do not support the CSS property box-shadow. As a result, controls in themes that use this property do not have a shadow. This property is usually used to enhance a 3D effect, for example, along vertical edges or to drop a shadow for a box "floating" above other content, which is used for all kinds of popup windows.

In the UX theme, this affects the following controls:

● Button(3D)● ComboBox(Popup)● DatePicker(Popup)● DropdownBox(Popup)● Menu(Popup)● MenuButton(Popup)● MessageBar(+Popup)● ProgressIndicator(3D)● RichTooltip● TextArea(3D)● TextField(3D)● Toolbar(OverflowMenu)



ComboBox in FireFox 3.6 ComboBox in Internet Explorer 8

Background Size

IE 8 and lower versions of IE do not support the property background-size which allows to stretch a background image or gradient.

This affects the Button control.

Button in FireFox 3.6 Button in Internet Explorer 8

Gradient Backgrounds

IE8 only supports gradients in a limited way, so some gradients may be missing.

This affects tables. In the example, compare the table header and row selectors.

Gradient Background in FireFox 3.6 Gradient Background in Internet Explorer 8

Native Scrollbars

For native scrollbars, see the ComboBox example in the Box Shadow section.



1.2.1.1.2 Degradations by Control

The following table gives an overview of degradations.

Control Corners Shadow BG Size Gradients Scrollbars Degradation in IE8

Accordion

Button X X X No rounded corners, vertical edges without 3D effect and background has no scale when button size differs from default height

CheckBox

ComboBox X X X No rounded corners, no 3D effect for vertical edges and popup has no shadow

DatePicker X X X No rounded corners, no 3D effect for vertical edges and popup has no shadow

Dialog X Native scrollbars

DropdownBox X X X No rounded corners, no 3D effect for vertical edges and popup has no shadow

FileUploader X X Inherited from the components used (InputField and Button)

HorizontalDivider

Image

Label

Link




ListBox X X X No rounded corners, no 3D effect for vertical edges

Menu X Popup without shadow

MenuButton X X X No rounded corners, vertical edges without 3D effect, background does not scale when button size differs from default height, popup without shadow

MenuBar X Menu items without rounded corners

MessageBar X X No rounded corners, no shadow, message list popup without shadow

MessageBox

Panel X Native scrollbars

ProgressIndicator

X X No rounded corners, vertical edges without 3D effect

RadioButton

RichTooltip X X No shadow; if it had a shadow, the shadow would not have rounded corners

Slider

Splitter

Table X X Native scrollbars,




headers/line markers only show 2-colors instead of gradient

TextArea X X X No rounded corners, vertical edges without 3D effect

TextField X X No rounded corners, vertical edges without 3D effect

TextView

Toolbar X Overflow menu without shadow

1.2.1.2 Browser Support: SAPUI5 for Mobile

The following tables give an overview of the platforms supported by the sap.m library of SAPUI5 for Mobile. Depending on the theme you use - SAP Mobile Visual Identity or SAP Blue Crystal - different platforms and browsers are supported.

iOS

iOs is supported as of platform version 5.

Browser Safari Web View

Supported with SAP Blue Crystal Yes Yes

Supported with SAP Mobile Visual Identity

Yes (iOS5 and iOS6) Yes (iOS5 and iOS6)

Chrome and Opera are not supported. When using SAP Mobile Visual Identity, iOS7 is not supported

Android

Android is supported as of platform version 2.3



Browser Android Browser Chrome Web View

Supported with theme:

SAP Blue Crystal Yes Yes Yes

SAP Mobile Visual Identity Yes Yes Yes

Opera, Opera mini and Firefox are not supported on Android devices.

BlackBerry

Blackberry is supported as of platform version 10.

NoteThe sap.makit library supports the same platforms as Mobile Visual Identity theme excluding BlackBerry 10.

Browser BlackBerry Browser Web View

Supported for both themes Yes Yes

Theme style when using SAP Mobile visual Identity

Android Android

Opera Mini is not supported on BlackBerry devices.

Windows Mobile

Windows Mobile is not supported.

Windows Desktop

When using Windows running on a desktop device, there is no touch support.

Browser Internet Explorer FireFox Chrome

Supported versions 9 or higher latest and Extended Support Release

latest version

Safari and Opera are not supported.

SAPUI5 for Mobile is not supported on the desktop for SAP Mobile Visual Identity. Only for development scenarios you can use it with Safari and Google Chrome, with either Android or iOS style, depending on your configuration.



Mac OS

On Mac OS, Safari browser is supported in version 5.1 or higher when using SAP Blue Crystal theme.

SAP Mobile Visual Identity is not supported, you can use it only for development scenarios, also with Safari browser.

Exceptions

Note● SAP Mobile Visual Identity is only supported for the following controls: ActionSheet, ActionListItem, App,

BusyDialog, BusyIndication, Button, CheckBox, Carousel, CustomListItem, DateTimeInput, Dialog, DisplayListItem, FlexBox, GrowingList, Input, Image, InputListItem, Label, List, NavContainer, MessageToast, Page, Bar, Popover, PullToRefresh, RadioButton, SegmentedButton, StandardListItem, ScrollContainer, SearchField, Select, Slider, Switch, SplitApp, Text, TextArea

● The control FlexBox is not supported in Internet Explorer 9.● The control Carousel is not supported in Internet Explorer.

1.2.2 Create your First Mobile App using SAPUI5

Whether you develop a SAPUI5 application for desktop or for mobile, the concepts are very similar. SAPUI5 provides an additional control library called sap.m, which is optimized for mobile devices.

The sap.m library provides a mobile-style theme, which makes users feel comfortable on both, Android and Apple devices. It has a focus on touch interactions.

NoteThe sap.m mobile library is optimized for mobile browsers based on WebKit. Currently, the library does not run properly on other browsers, such as Microsoft Internet Explorer and Mozilla Firefox. Therefore we recommend to use Google Chrome or Apple Safari for tests on desktop PCs.

Also, the mobile library only uses touch events and deduces its appearance from the platform it is running on. For tests with Chrome or Safari on desktop PCs, you therefore need the to set one of the following URL parameters:

● sap-ui-xx-fakeOS=android● sap-ui-xx-fakeOS=ios● sap-ui-xx-fakeOS=blackberry ● sap-ui-xx-fakeOS=winphone

The URL parameter suggests to emulate touch events from mouse events and to apply the styles for either Android, iOS, BlackBerry of Windows Phone. You can also add this parameter as data-sap-ui-xx-fakeOS attribute to the bootstrap script tag.



Related Information

Create a HTML Page for Your Mobile App [page 15]You first create a HTML page and define the meta tags, a script tag to load the SAPUI5 libraries and a placeholder for your mobile app.

Initialize the Mobile App [page 16]The sap.m library provides a control called App which is meant to be the root control of a mobile application. It provides the initialization of the HTML page, sets some meta tags to ensure an as-native-as-possible look&feel, and can manage different pages and the animations between them.

Add Content Pages [page 17]Typical mobile applications are often composed of a number of pages/views/screens between which the user can navigate. You now add two of them to your app.

Run Your First Mobile App [page 18]To test a mobile app on your desktop, you have to ensure some prerequisites.

1.2.2.1 Create a HTML Page for Your Mobile App

You first create a HTML page and define the meta tags, a script tag to load the SAPUI5 libraries and a placeholder for your mobile app.

Procedure

1. Create a HTML page called mobile.html2. Add the HTML5 doctype definition: <!DOCTYPE html>" in the first line and the Internet Explorer-specific

meta tag :<meta http-equiv="X-UA-Compatible" content="IE=edge" />" are the beginning of <head> element.

This ensures that all browsers use the latest version of their rendering engine. Although Microsoft Internet Explorer is not really used widely on mobile devices and not yet supported by the SAPUI5 mobile library, this meta tag makes the page more future-proof.

3. Add a second meta tag: <meta http-equiv="Content-Type" content="text/html;charset=UTF-8"/>.

This lets all browsers treat the file as UTF-8 encoded (assuming that you use this encoding when editing/saving the file)

4. Add a <div> element to <body>.

5. The "sapUiBody" class should always be added to the <body> tag to initialize font and colors for the whole page:

<body class="sapUiBody">  <div id="content"></div></body>

6. To load the SAPUI5 JavaScript file, that contains the library, add the following script tag in the <head>:

<script src= "http://<http://<server>:<port>/sapui5/resources/sap-ui-core.js" id= "sap-ui-bootstrap" data-sap-ui-libs= "sap.m" data-sap-ui-theme= "sap_mvi"> </script>

Note that you are only loading the "sap.m" control library and the "sap_mvi" theme. mvi stands for Mobile Visual Identity and is the name of the SAP Mobile design.

7. Replace <server> and <port> with your local SAPUI5 installation or point to the SAPUI5 libraries on SAP HANA Cloud Platform: https://sapui5.hana.ondemand.com/resources/sap-ui-core.js

Results

At this point, SAPUI5 including the mobile controls is loaded and ready to use.

Next Steps

Initialize the Mobile App [page 16]

1.2.2.2 Initialize the Mobile App

The sap.m library provides a control called App which is meant to be the root control of a mobile application. It provides the initialization of the HTML page, sets some meta tags to ensure an as-native-as-possible look&feel, and can manage different pages and the animations between them.

Procedure

Create the control and define the page that you want to display first:

// create a mobile App // it initializes the HTML page for mobile use and provides animated page handling var app = new sap.m.App("myApp", {initialPage:"page1"}); // page1 should be displayed first

○ Instead of using the App control, you can also use jQuery.sap.initMobile() to set up the HTML and use other full screen controls, such as sap.m.Page or sap.m.Carousel as root element of your app.



1.2.2.3 Add Content Pages

Typical mobile applications are often composed of a number of pages/views/screens between which the user can navigate. You now add two of them to your app.

Procedure

1. One sap.m.Page control is created, its title is set and the content is just one button:

// create the first page of your applicationvar page1 = new sap.m.Page("page1", { title: "Initial Page", content : new sap.m.Button({ // content is just one Button text : "Go to Page 2", tap : function() { app.to("page2"); // when tapped, it triggers drilldown to page 2 } })});

When the Button is pressed, it triggers a drilldown navigation by calling app.to("page2"), where page2 is the ID of the second page. You could also give the animation type. The default is a slide animation from right to left.

sap.m.Page controls can be used as pages, and the aggregation is called pages, but other controls could be used as well.

2. Add the following to the <script> seciton of the HTML page below the part, where you've initialized the app:

// create the second page of your applicationvar page2 = new sap.m.Page("page2", { title: "Page 2", showNavButton: true, // page 2 should display a back button navButtonTap: function(){ app.back(); // when tapped, the back button should navigate back up to page 1 }, icon: "http://www.sap.com/global/ui/images/global/sap-logo.png", content : new sap.m.Text({text:"Hello Mobile World!"})});

showNavButton is set to true to get a Back button displayed. When this button is triggered, the handler calls app.back(). This causes an inverse animation, which leads back to the main page.

A header icon, which is only visible on Android, and "Hello Mobile World" content is also given.3. Finally, add the two pages to the App:

// add both pages to the Appapp.addPage(page1).addPage(page2);

The app is placed into the HTML like a SAPUI5 desktop control. The App takes care to cover the whole screen.



Next Steps

Run Your First Mobile App [page 18]

1.2.2.4 Run Your First Mobile App

To test a mobile app on your desktop, you have to ensure some prerequisites.

Prerequisites

Your operating system is Microsoft Windows and you use a current WebKit-based browser (Google Chrome or Apple Safari). Other operating systems work as well, but the procedure may differ. Also, the mobile library is currently not optimized for Mozilla Firefox and Microsoft Internet Explorer.

NoteThe URL in the script tag is pre-filled as https://sapui5.hana.ondemand.com/resources/sap-ui-core.js. This is the URL where the resources are located in the SAP HANA Cloud delivery. Test this URL first and if it does not work, replace this URL with the location of SAPUI5 on your local server.

Also note that the version of SAPUI5 deployed on https://sapui5.hana.ondemand.com/ may be updated with a delay of some days or weeks after a new release of SAPUI5, even though we try to keep them in sync. This example will work nevertheless.

Procedure

1. Right-click on your desktop and choose New Text Document .2. Enter a name for the new file, for example "mobile.html", and confirm the extension change warning.3. Right-click on the new file and choose Edit. Make sure it opens in Notepad and not in MS Word.4. Copy and paste the HTML code below and save the file. Keep in mind that the SAPUI5 URL may need to be

adapted.5. Drag and drop the file into the browser window.6. To load the example on a mobile device, you put the file on a server.7. To play around with the app in your desktop browser, add the following URL parameter to the file URL: sap-

ui-xx-fakeOS=ios, so that the URL reads : "mobile.html?sap-ui-xx-fakeOS=ios". This enables the simulation of touch events on desktop PCs. This also enables the iPhone/iPad styling; if you want to see the Android styling, use sap-ui-xx-fakeOS=android instead.

<!DOCTYPE HTML><html> <head>



And the following mobile App on Android:



If you have set the sap-ui-xx-fakeOS URL parameter, you can navigate to the second page by clicking the button.

To open the application on a real mobile device, you can also put the HTML document on a Web server and load the resulting URL in your mobile browser.

1.2.3 Create Your First SAPUI5 Application

You can include a bootstrap to the SAPUI5 JavaScript libraries to use SAPUI5 in an HTML page without having set up the SAPUI5 application development tools in Eclipse.

This page explains how to create and run a simple SAPUI5 application from scratch within twenty seconds (with some practice… the current record is 16 seconds).

If you are interested in exactly doing this without reading too much, you can skip the background information and read the And how to do it in 20 Seconds section below.

Background Information

As SAPUI5 is a client-side web UI library meaning that it runs in a browser, a SAPUI5 application typically is composed of an HTML page and, if required, many more files.

SAPUI5 is implemented in JavaScript. For loading SAPUI5, its bootstrap needs to be included with a <script> tag. The last two attributes select the visual design to apply initially (other choices would be sap_hcb or sap_platinum) and the SAPUI5 control library/libraries to use (sap.ui.dev would be another one). In your scenario you need to make sure the URL points to a SAPUI5 installation.

#!text/html<script id="sap-ui-bootstrap" src="resources/sap-ui-core.js" data-sap-ui-theme="sap_bluecrystal" data-sap-ui-libs="sap.ui.commons"></script>

SAPUI5 UI elements are created and modified programmatically:

#!js// create the button instancevar myButton = new sap.ui.commons.Button("btn");

// set properties, e.g. the text (there is also a shorter way of setting several properties)myButton.setText("Hello World!");

// attach an action to the button's "press" event (use jQuery to fade out the button)myButton.attachPress(function(){$("#btn").fadeOut()});

There is also a shorthand notation based on JSON for setting multiple properties; you could also write:

#!js



NoteThe URL in the script tag is pre-filled as https://sapui5.hana.ondemand.com/resources/sap-ui-core.js. This is the URL where the resources are located in the SAP HANA Cloud Platform delivery. Test this URL first and if it does not work, replace this URL with the location of SAPUI5 on your local server.

Also note that the version of SAPUI5 deployed on https://sapui5.hana.ondemand.com/ may be updated with a delay of some days or weeks after a new release of SAPUI5. This example will work nevertheless.

Proceed as follows:

1. Right click your desktop and select New Text Document .2. Name the new file, for example "ui5.html", and accept the extension change warning.3. Right click the new file and select Edit. Make sure that the file opens in Notepad and not in MS Word.4. Copy and paste the below HTML code. Keep in mind to adapt the SAPUI5 URL5. Drag the file to the browser window.6. That was it.

#!text/html<!DOCTYPE html><html><head> <meta http-equiv="X-UA-Compatible" content="IE=edge" /> <meta http-equiv="Content-Type" content="text/html;charset=UTF-8"/> <title>SAPUI5 in 20 Seconds</title>  <script id="sap-ui-bootstrap" src="https://sapui5.hana.ondemand.com/resources/sap-ui-core.js" data-sap-ui-theme="sap_bluecrystal" data-sap-ui-libs="sap.ui.commons"></script>

 <script> // create the button instance var myButton = new sap.ui.commons.Button("btn");

// set properties, e.g. the text (there is also a shorter way of setting several properties) myButton.setText("Hello World!");

// attach an action to the button's "press" event (use jQuery to fade out the button) myButton.attachPress(function(){$("#btn").fadeOut()});

// place the button into the HTML element defined below myButton.placeAt("uiArea");

// an alternative, more jQuery-like notation for the same is: /* $(function(){ $("#uiArea").sapui("Button", "btn", { text:"Hello World!", press:function(){$("#btn").fadeOut();} }); }); */ </script>

</head><body class="sapUiBody">

<div id="uiArea"></div></body></html>

Result

If you followed the steps above you should now see a button like this which fades out when clicked:

Next Steps

You can now do the following:

● Add more buttons.● Let them do trickier things.● Use a different visual theme as mentioned above, for example sap_ux● Find out about further properties and events of button controls and use those.● Find out about further controls and add those. For more information, see the Controls Gallery in the Demo Kit.

1.2.4 Develop Your First Application using SAPUI5 Tools

The SAPUI5 application development tools in Eclipse support you in developing web applications according to the Model View Controller concept (MVC).

The SAPUI5 application development tools for Eclipse provide wizards to support you in creating SAPUI5 applications in an easy way. With the SAPUI5 application project wizard, the necessary application skeleton containing view(s) and controller will automatically be created.

Creating SAPUI5 applications

The SAPUI5 tools support you in creating applications according to MVC. In this section we guide you through a simple example. You will create a SAPUI5 application project, which includes a control, a method in the controller and an additional view.

More Information

Create an SAPUI5 Application Project [page 25]

Add a Control to Your View [page 29]

Implement a Method in the Controller [page 30]

Utilities

With Eclipse you can make use of utilities for JavaScript development. Additionally SAPUI5 provides templates and snippets.

● JavaScript Code CompletionThe Eclipse JavaScript Development Tools (JSDT) provide an editor which parses scripts and offers code completion functionality. The core libraries for the code completion are made available automatically.

NoteIf your Eclipse installation contains the org.eclipse.wst.jsdt.feature feature in Version 1.3.1, we recommend to update it. Invoking the JavaScript code completion in version 1.3.1 may cause Eclipse to crash.

More Information

JavaScript Code Completion [page 34]

Use JavaScript Templates [page 36]

SAPUI5 Snippets [page 38]

1.2.4.1 Create an SAPUI5 Application Project

Context

To create a SAPUI5 Application Project, you must have installed the SAPUI5 Application Development feature in your Eclipse installation.



Procedure

1. Start the New SAPUI5 Application Project wizard in the Eclipse by choosing New Other ... SAPUI5 Application Development Application Project .



2. Enter the following project-related data:

○ Project name○ Location (optional, prefilled from the current workspace)○ Target device: 'Desktop' or 'Mobile'○ Select Create an Inital View

Views can also be added later using the SAPUI5 Application View wizard



3. Enter the following view-related data:

○ Choose the folder in which the view shall be created○ Enter a unique name for your view○ Choose the Development Paradigm.

Results

After finishing the wizard, the system performs the following steps:

● A new dynamic web project is created. All relevant files are created in the WebContent folder.● A prefilled index.html is created which contains sap.ui.commons lib and sap_goldreflection theme in

the boostrap in case of a desktop target device and the sap.m lib and sap_mvi theme in case of mobile target device.

● In WEB-INF folder a web.xml file is created which contains settings for resource handling and the use of SimpleProxyServlet.

● The installed SAPUI5 UI lib plugins are automatically added to the Java build path and added to the deployment assembly.



● The SAPUI5 class path container (if available) is automatically added to the JavaScript include path.● The index.html page is opened in the standard editor.● Inside the JavaScript block of index.html, code completion is available, see JavaScript Code Completion.● An automatic switch to the J2EE perspective is performed.● If you have selected the Create an Initial View option on the first page of the SAPUI5 Application Project

wizard, a view and a view controller are created and the coding to call the view is added to the index.html file.

Next Steps

Add a Control to Your View [page 29]


Create an Additional View [page 31]

Integrate a New View [page 33]

Related Information

JavaScript Code Completion [page 34]When using the SAPUI5 tools, code completion is enabled automatically, without the tools, you need to enable it.

Use JavaScript Templates [page 36]You can add SAPUI5 control-specific templates for JavaScript code. Such templates are available, for example, in JavaScript views of SAPUI5 application tools development.

SAPUI5 Snippets [page 38]

Linking your Eclipse Editor to the Demo Kit [page 36]You can use Quick Fixes to display the API documentation of a SAPUI5 control in the Demo Kit.

1.2.4.2 Add a Control to Your View

In your SAPUI5 application project, the first step to build your application is to add a control to your view and implement a method to react on user interaction. In this case you create a button and implement a function to react when the user presses it.



Procedure

To add a control to your view, add the following coding depending on the type of your view:

○ In a JS view add the following to the createContent function

var aControls = []; var oButton = new sap.ui.commons.Button({ id : this.createId("MyButton"), text : "Hello JS View" }); aControls.push(oButton.attachPress(oController.doIt)); return aControls;

○ In an HTML view add the following to the template tag:

<div data-sap-ui-type="sap.ui.commons.Button" id="MyButton" data-text="Hello HTML View" data-press="doIt"></div>

○ In an XML view add the following coding to the core tag

<Button id="MyButton" text="Hello XML View" press="doIt"/>

○ In a JSON view add the following to the content function

"Type":"sap.ui.commons.Button", "id":"MyButton", "text":"Hello JSON View", "press":"doIt"

A button is added to your view with an event that is triggered when the user presses it.

Next Steps

The doIt method, which is called in each of these view types, is implemented in the controller:


1.2.4.3 Implement a Method in the Controller

All functions that are not directly related to the user interface should be handled in the controller to ensure clear separation between UI and data. In this case you add a method to handle the event, which is attached to a button.

Prerequisites

You've created a button as described in: Add a Control to Your View [page 29]



Procedure

To handle this event, add the following function to the controller:

doIt : function(oEvent) { alert(oEvent.getSource().getId() + " does it!"); }

1.2.4.4 Create an Additional View

Context

● A SAPUI5 application view can only be created for a SAPUI5 application project that has been created with the SAPUI5 Application Wizard and not for other kinds of projects.

● A SAPUI5 application view name needs to be unique inside the project folder.● The specified folder for a SAPUI5 application view needs to be WebContent/<application name> or a sub

folder.

Procedure

1. Choose New Other... SAPUI5 Application Development View to open the New SAPUI5 Application

View wizard.



2. Fill in the required data:

○ Select the SAPUI5 application project, in which you want to create the view.○ Select a folder, in which you want to store the view (default is WebContent/<application name>).○ Enter a name for the view.○ Select the development paradigm, see View Types.

Results

When you finish the wizard, the system creates the view in the specified folder. The file name suffix indicates the development paradigm:

● <viewname>.view.js for JavaScript views● <viewname>.view.xml for XML views● <viewname>.view.json for JSON views● <viewname>.view.html for HTML views



If the corresponding index.html file contains sap.m lib in the bootstrap, that is, if the SAPUI5 application project has been created for a mobile target device, the view contains coding for instantiating a mobile page control sap.m.Page.

The system also creates a controller file <viewname>.controller.js with draft coding.

For JavaScript views, code completion is available, see JavaScript Code Completion.

NoteIf you rename the view or controller file, or move them to a different folder, the coding in the view and controller and in the places where the view is used needs to be adapted manually.

1.2.4.5 Integrate a New View

To integrate a new view, you can either add it to index.html or nest it into another view.

Prerequisites

If you create a new view for an existing SAPUI5 application project, the view needs to be manually called.

Procedure

To call a view, choose from the following options:

○ Directly embed the new view in the index.html page○ All Views can be nested independent of the view type. Each view type behaves like any SAPUI5 control.

The viewName property defines, which views are embedded. To nest a view, proceed according to the given examples:

For XML view type:

<core:View controllerName="sap.hcm.Address" xmlns="sap.ui.commons" xmlns:core="sap.ui.core" xmlns:html="http://www.w3.org/1999/xhtml"> <Panel> <core:JSView id="myJSView" viewName="sap.hcm.Bankaccount" /> </Panel><core:View>

For HTML views, the nested view looks as follows:

<template data-controller-name= "example.mvc.test" >

<div data-sap-ui-type= "sap.ui.core.mvc.HTMLView" id= "MyHTMLView" data-view-name= "example.mvc.test2" ></div> <div data-sap-ui-type= "sap.ui.core.mvc.JSView" id= "MyJSView" data-view-name= "example.mvc.test2" ></div>



<div data-sap-ui-type= "sap.ui.core.mvc.JSONView" id= "MyJSONView" data-view-name= "example.mvc.test2" ></div> <div data-sap-ui-type= "sap.ui.core.mvc.XMLView" id= "MyXMLView" data-view-name= "example.mvc.test2" ></div>

</template>

1.2.4.6 JavaScript Code Completion

When using the SAPUI5 tools, code completion is enabled automatically, without the tools, you need to enable it.

NoteIf your Eclipse installation contains the org.eclipse.wst.jsdt.feature feature in Version 1.3.1, we recommend to update it. Invoking the JavaScript code completion in version 1.3.1 may cause Eclipse to crash.

Automatic Code Completion for SAPUI5 Application Projects

The Eclipse JavaScript Development Tools (JSDT) provide an editor which parses scripts and offers a code completion functionality.

Code Completion for SAPUI5 Views

For JavaScript views, code completion is available.



Enabling Code Completion for Other Projects

If you are not working with a SAPUI5 application project, you can perform the following preparing steps to add the required SAPUI5 core libraries to the JavaScript include path.

Ensure that the JavaScript Facet is set and proceed as follows:

1. Open Project Properties .2. Select Project Facets.3. If you do not see the list of all possible facets, click the link: Convert to facet form and wait a second to see all

available facets.4. Mark JavaScript Facet on the same view.5. Leave the project properties.

Your project now has the JavaScript facet. Now you can add the SAPUI5 core libraries. Proceed as follows:

● Open Project Properties .

● Choose JavaScript Include Path .● Select Add JavaScript Library….● Select SAPUI5.

You should now be able to see the following JavaScript resources in your project:



1.2.4.7 Linking your Eclipse Editor to the Demo Kit

You can use Quick Fixes to display the API documentation of a SAPUI5 control in the Demo Kit.

Procedure

1. Place the cursor on the actual SAPUI5 control name in your JavaScript code or in your XMLView. The name of the control in JavaScript code usually starts with sap.

2. To see all available Quick Fixes, press CTRL+1.

3. To open the API documentation of the control in the Demo Kit, choose Display in Demo Kit.

1.2.4.8 Use JavaScript Templates

You can add SAPUI5 control-specific templates for JavaScript code. Such templates are available, for example, in JavaScript views of SAPUI5 application tools development.

Context

The templates are an overview over all available



● control properties● aggregations● associations and● events

To use the JavaScript templates, the SAPUI5 application development tools feature has to be installed in your Eclipse.

NoteIf your Eclipse installation contains the feature org.eclipse.wst.jsdt.feature in Version 1.3.1, we recommend to update it. In this version, invoking the JavaScript code completion may cause Eclipse to crash.

Procedure

1. To insert a template, open the JavaScript editor.2. Start typing the name of the respective control or the name of the alias, for example button.3. Choose CRTL + SPACE and choose the control from the code completion list.

All properties and events are inserted.



1.2.4.9 SAPUI5 Snippets

You can add SAPUI5-specific code parts, so called SAPUI5 Snippets. Code snippets are templates and examples on how to use the SAPUI5 runtime and controls and what can be done with them. SAPUI5 snippets are available as prepared HTML pages with no separation between model, view and, controller (MVC) and they are generated during startup of the Eclipse runtime.

Before you can use the SAPUI5 snippets, the SAPUI5 application development tools must be installed in your Eclipse.

To open the Snippets view, proceed as follows:



1. Choose Window Show View Other... .



2. In the Show View dialog, choose General Snippets and confirm you selection with OK.

3. The Snippet view opens.

To insert a snippet, proceed as follows:

1. Create a SAPUI5 application project, see Creating a SAPUI5 Application Project.2. Open the index.html in the HTML editor.3. Delete all content.



4. To insert the snippet code, double click on the snippet or use drag&drop.



5. Save the code and run it in the integrated browser.



6. NoteIf you have problems with incorrect rendered pages, open the default external browser.



The page should then be displayed correctly:



1.2.5 Support Translation

This section provides a description of what needs to be done to support the translation of resource bundles.



Prerequisites

You've created an SAPUI5 application project as described in:

1. Create an SAPUI5 Application Project [page 25]2. Add a Control to Your View [page 29]3. Implement a Method in the Controller [page 30]

Context

To enable the translation of the user interface, you define a specific suffix for the resource bundles and use a specific first line in the resource bundle file.

Procedure

1. If not already done so, change the bootstrap tag (located in the index.html file) to enable the application to access the SAPUI5 libraries on the xsengine as follows: src="resources/sap-ui-core.js" to src="/sap/ui5/1/resources/sap-ui-core.js".

2. Create a new folder i18n in the WebContent folder. Add a new file messagebundle.hdbtextbundle to the i18n folder with the following content:

# TRANSLATE# XBUT,30MY_BUTTON_TEXT=Hello {0} button

NoteA specific suffix .hdbtextbundle is needed for the resource bundles on SAP HANA (so called .properties file on other platforms).

3. To load this bundle, add the following coding to the createContent function of your view:

// require the jQuery.sap.resources module jQuery.sap.require("jquery.sap.resources"); // load the resource bundlevar oBundle = jQuery.sap.resources({ // specify url of the .hdbtextbundle url : "i18n/messagebundle.hdbtextbundle"});

4. To add a control to your view for example to the helloworld.view.js), insert the following coding:

createContent : function(oController) {var aControls = []; var oButton = new sap.ui.commons.Button({ id : this.createId("MyButton"), // access the text using the welcome key and pass the value // for the placeholder ( {0} ) via an array text : oBundle.getText("MY_BUTTON_TEXT", [ "World" ]) });



aControls.push(oButton.attachPress(oController.doIt)); return aControls;}

The text property of the button now is connected to the resource bundle and can be displayed in other languages.

Related Information

Localized Texts [page 273]

1.2.6 Testing SAPUI5 Applications Locally

This section provides a description how local testing can be performed as an optional step.

Context

If you want to test the SAPUI5 application before you activate your project, you can test it within Eclipse on your local PC. This local testing is optional. If you perform a local test, note the following:

● The src attribute in the bootstrap tag of the index.html file needs to have a different URL than the src attribute for execution on SAP HANA's Web server. This can be achieved by manually changing the URL before submitting to SAP HANA's Web server, or by using a code snippet, that detects if the application runs locally or not, and sets the URL accordingly.

● If you call a data service in form of a server-side JavaScript or an OData service that resides in the SAP HANA box, it is necessary to use a URL that points to SAP HANA's Web server. It is usually also necessary to use the so-called proxy servlet to avoid cross-domain issues. In case of the bootstrap URL, for example, the URL for local execution differs from the URL for execution on SAP HANA's Web server.

Procedure

1. Change the URL set as "src" in the bootstrap tag of the index.html file (see explanation above). To avoid a manual change before submitting the application, use the following code snippet that detects the context automatically, in which the application runs, and sets the URL accordingly.

<script src="/sap/ui5/1/resources/sap-ui-core.js" id="sap-ui-bootstrap" data-sap-ui-libs="sap.ui.commons" data-sap-ui-theme="sap_goldreflection" ></script><script>// use alternative bootstrap for testing locally in

// Eclipse during development time// this is only a helper mechanism during development timeif (!window.sap) {var oriTag = document.getElementById("sap-ui-bootstrap");oriTag.id = "wrong";oriTag.src = "wrong.js";var script = "<script id='sap-ui-bootstrap' " +"src='resources/sap-ui-core.js' " +"data-sap-ui-theme='sap_goldreflection' " +"data-sap-ui-libs='sap.ui.commons'> " +"<\/script>";document.write(script);}</script>

2. If you use requests to backend services, you need to use a suitable URL that points to the backend server and, to avoid cross-domain issues, you need to use the so-called proxy servlet. Similar to the bootstrap tag, you can change the respective code manually before submitting, or you can use a code snippet that determines the URL automatically depending on the context, in which the application runs.

NoteAs the server-side logic of an SAPUI5 application cannot be executed locally on the developer's PC, it can only run on the server. Hence, this needs to be committed and activated before it can be tested.

3. To test your application, choose one of the following options:

○ Open the context menu for the index.html file located in your project's WebContent folder and choose Run As Web App Preview .

○ To run your application on a server, for example Tomcat, open the context menu of your project, choose Run As Run on Server and select the respective server.

Related Information

Testing SAPUI5 Applications in Eclipse [page 266]You have different options to test your applications locally in Eclipse.

1.2.7 Running SAPUI5 Applications on SAP HANA

To run an SAPUI5 application on SAP HANA, you either expose the respective package via HTTP or you create the SAPUI5 application inside a SAP HANA XS application.l

Procedure

1. Ensure that you have changed the bootstrap tag in index.html to enable the application to access the SAPUI5 libraries on the xsengine as follows: src="resources/sap-ui-core.js" to src="/sap/ui5/1/resources/sap-ui-core.js".



2. To expose the SAPUI5 application project:

○ If the package that contains your SAPUI5 application project has not been exposed via HTTP already, you need to create .xsapp and .xsaccess files, see Creating the Application Descriptors.

○ This is not necessary, if the project was created as a sub-package of an SAP HANA XS application.3. Activate the project on SAP HANA's Web server.4. To start the UI application on SAP HANA's Web server, use the following URL: <xsengine protocol>://

<xsengine server>:<xsengine port>/<SAPUI5 application name>/WebContent/index.html . Replace the placeholders accordingly.

1.3 Concepts

Overview on the architecture and concepts of SAPUI5

SAPUI5 is a client UI technology based on JavaScript, CSS and HTML5. SAPUI5 applications run in a browser. Depending on the device, the application is supposed to run on (mobile, tablet or desktop PC), you use different UI libraries.

Servers come into play for deploying your applications, storing the SAPUI5 libraries and to connecting to a data base. Depending on the environment in which SAPUI5 is used, the libraries or your applications are stored on an



SAP NetWeaver Application Server or an SAP HANA Cloud platform, for example. To access business data for your application the preferred way is using the OData model through a SAP NetWeaver Gateway.

When a user accesses an SAPUI5 application from his device, a request is sent to the respective server to load the application into the browser. The view accesses the relevant libraries. Usually the model is also instantiated and business data is fetched from the data base.

Model-View-Controller

SAPUI5 uses the model-view-controller (MVC) concept to achieve the following objectives:

● Support development in distributed teams with different source locations● Suggest file structure, naming, and usage patterns● Add capability of UI declaration (in comparison to a programmatic construction)

Related Information

Model-View-Controller (MVC) [page 50]Models [page 52]

A model holds the data and provides methods to retrieve the data from the data base and to set and update data.

Views [page 53]

Controllers [page 56]A controller in SAPUI5 is used to separate view logic from model logic. All methods for controlling the data flow should be implemented in a controller.

Data Binding [page 57]Data binding is used to bind two data or information sources together to keep them in sync. If data binding is implemented and defined properly, all changes in one data source are automatically reflected in the other data source.

Resource Handling [page 59]There are two layers in SAPUI5 which are responsible for resource handling and which work completely independent from each other: The client side and the server side.

Libraries [page 60]The basis of SAPUI5 is a set of JavaScript and CSS libraries.

1.3.1 Model-View-Controller (MVC)

In the model-view-controller concept, the representation of information is separated from the user's interaction:

● The view is responsible for defining and rendering the UI.



● The model manages the application data.● The controller reacts to view events and user interaction by modifying view and model.

The purpose of data binding in the UI is to separate the definition of the user interface (view), the data that visualized by the application (model), and the code for the business logic for processing the data (controller). The separation has the following advantages: It provides a better readability, maintainability, and extensibility and it allows you to change the view without touching the underlying business logic and to define several views of the same data.

With this pattern, a separation of concerns is achieved that facilitates development and change of parts independently.

Views and controllers often form a 1:1 relationship, but it is also possible to have controllers without UI, these controllers are called application controllers. It is also possible to create views without controllers. From a technical position, a view is a SAPUI5 control and can have or inherit a SAPUI5 model.

View and controller represent reusable units and distributed development is highly supported.

Related Information

Views [page 53]

Models [page 52]A model holds the data and provides methods to retrieve the data from the data base and to set and update data.

Controllers [page 56]A controller in SAPUI5 is used to separate view logic from model logic. All methods for controlling the data flow should be implemented in a controller.



1.3.1.1 Models

A model holds the data and provides methods to retrieve the data from the data base and to set and update data.

SAPUI5 provides the following predefined models:

● The JSON model can be used to bind controls to JavaScript object data, which is usually serialized in the JSON format. The JSON model is a client-side model and, therefore, intended for small datasets, which are completely available on the client. The JSON model supports two-way binding.

● The XML model is a client-side model intended for small datasets, which are completely available on the client. The XMLModel does not contain mechanims for server-based paging or loading of deltas

● The Resource model is designed to handle data in resource bundles, mainly to provide texts in different languages.

● The OData model enables binding of controls to data from OData services. The OData model is a server-side model: the dataset is only available on the server and the client only knows the currently visible rows and fields.

The JSON model, XML model, and the resource model are client-side models, meaning that the model data is loaded completely and is available on the client. Operations such as sorting and filtering are executed on the client without further server requests. The OData model is a server-side model and only loads the data requested by the user interface from the server. Any changes in data binding or list operations require a new request to the server.

You can not only define one model for your applications, but define different areas in your application with different models and assign single controls to a model. You can also define nested models, for example, a JSON model defined for the application and an OData model for a table control contained in the application.

A web application should support several data sources, such as JSON, XML, Atom, or OData. However, the way in which data binding is defined and implemented within the UI controls should be independent of the respective data source. It is also possible to create a custom model implementation for data sources that are not yet covered by the framework or are domain-specific.

API References

● sap.ui.model

● sap.ui.model.json.JSONModel

● sap.ui.model.odata.ODataModel

● sap.ui.model.resource.ResourceModel

● sap.ui.model.xml.XMLModel

Related Information

Binding Modes [page 58]Models and Data Binding [page 84]



http://help.sap.com/disclaimer?site=https://sapui5.hana.ondemand.com/sdk/#docs/api/symbols/sap.ui.model.html

http://help.sap.com/disclaimer?site=https://sapui5.hana.ondemand.com/sdk/#docs/api/symbols/sap.ui.model.json.JSONModel.html

http://help.sap.com/disclaimer?site=https://sapui5.hana.ondemand.com/sdk/#docs/api/symbols/sap.ui.model.odata.ODataModel.html

http://help.sap.com/disclaimer?site=https://sapui5.hana.ondemand.com/sdk/#docs/api/symbols/sap.ui.model.resource.ResourceModel.html

http://help.sap.com/disclaimer?site=https://sapui5.hana.ondemand.com/sdk/#docs/api/symbols/sap.ui.model.xml.XMLModel.html

1.3.1.2 Views

Although XML and JSON notation has been introduced for SAPUI5 UI controls, the model-view-controller concept is also supported to facilitate traditional programmatic UI constructions.

SAPUI5 provides the following predefined view types

● XML view. The user interface is defined in an XML file or string.

NoteThe XMLView type supports a mix of XML and plain HTML.

● JSON view. The user interface is defined in a file or string in JSON format.● JS view. The user interface is constructed in a traditional manner.● HTML view. The user interface is defined in an HTML file or string.

The above mentioned view types are predefined and offered for selection as view options in the application creation wizard. If you use SAPUI5 application development tools, you can also plug in other view types. For defining other or custom view types, you extend the base class sap.ui.core.mvc.View.

API Reference

sap.ui.core.mvc.View

Related Information

JS Views [page 53]XML Views [page 54]JSON Views [page 54]HTML Views [page 55]

An HTML View is defined by declarative HTML. Like the declarative support, the HTML view supports embedded HTML.

1.3.1.2.1 JS Views

You create a JS (JavaScript) view in the same way as a controller and use the suffix .view.js. for the file. SAPUI5 provides the following two default methods for implementation:

● getControllerName(): Specifies the controller belonging to this viewIf this method is not implemented or returns NULL, the view has no controller.

● createContent(): Called initially once after the controller has been instantiated



http://help.sap.com/disclaimer?site=https://sapui5.hana.ondemand.com/sdk/#docs/api/symbols/sap.ui.core.mvc.View.html

This method is used to create the UI. As the method knows the controller, it can directly attach the event handlers.

sap.ui.jsview("sap.hcm.Address", { // this View file is called Address.view.js getControllerName: function() { return "sap.hcm.Address"; // the Controller lives in Address.controller.js },

createContent: function(oController) { var oButton = new sap.ui.commons.Button({text:"Hello JS View"}); oButton.attachPress(oController.handleButtonClicked); return oButton; }

});

The string in quotes denotes the view name that equals the SAPUI5 module name within the require/declare concept.

1.3.1.2.2 XML Views

The XML view type is defined in an XML file. The file name either ends with .view.xml or as an XML string. The file name and the folder structure together specify the name of the view that equals the SAPUI5 module name within the require/declare concept.

For resources/sap/hcm/Address.view.xml, the view name is sap.hcm.Address. The application uses this view name for displaying an instance of this view. If you define the XML view by means of an XML string, no file or require/declare is needed.

The file looks as follows:

<core:View controllerName="sap.hcm.Address" xmlns="sap.ui.commons" xmlns:core="sap.ui.core"> <Panel> <Image src="http://www.sap.com/global/ui/images/global/sap-logo.png"/> <Button text="Press Me!"/> </Panel><core:View>

Nest the XML tags analogous to the nesting sequence of SAPUI5 controls and add the property values as attributes. For information on more complex views see the following sections.

1.3.1.2.3 JSON Views

The JSON view type is defined in a file. The file name has to either end with .view.json or as a JSON string. The file name and the folder structure together specify the name of the view that equals the SAPUI5 module name within the modularization concept.

For the file resources/sap/hcm/Address.view.json, the view name is sap.hcm.Address. The application uses this view name for displaying an instance of this view.



The file looks as follows:

{ "Type":"sap.ui.core.mvc.JSONView", "controllerName":"sap.hcm.Address", "content": [{ "Type":"sap.ui.commons.Image", "id":"MyImage", "src":"http://www.sap.com/global/ui/images/global/sap-logo.png" }, { "Type":"sap.ui.commons.Button", "id":"MyButton", "text":"Press Me"

}]

}

You nest the JSON objects analogous to the nesting of SAPUI5 controls and add the property values as attributes. The syntax is the same as the syntax of a JSON constructor for any control.

NoteYou can use strings, boolean and null in your JSON view.

Aggregation Handling in JSON Views

You add child controls as arrays. This is shown in the example above where an image and a button have been added to the view content aggregation.

1.3.1.2.4 HTML Views

An HTML View is defined by declarative HTML. Like the declarative support, the HTML view supports embedded HTML.

The view file ends with view.html, for example myview.view.html.

Example:

<template data-controller-name="example.mvc.test"> Hello <h1>Title</h1> <div>Embedded HTML</div> <div class="test test2 test3" data-sap-ui-type="sap.ui.commons.Panel" id="myPanel"> <div class="test test2 test3" data-sap-ui-type="sap.ui.commons.Button" id="Button1" data-text="Hello World" data-press="doIt"></div> <div data-sap-ui-type="sap.ui.commons.Button" id="Button2" data-text="Hello"></div> <div data-sap-ui-type="sap.ui.core.mvc.HTMLView" id="MyHTMLView" data-view-name="example.mvc.test2"></div> <div data-sap-ui-type="sap.ui.core.mvc.JSView" id="MyJSView" data-view-name="example.mvc.test2"></div>



<div data-sap-ui-type="sap.ui.core.mvc.JSONView" id="MyJSONView" data-view-name="example.mvc.test2"></div> <div data-sap-ui-type="sap.ui.core.mvc.XMLView" id="MyXMLView" data-view-name="example.mvc.test2"></div> </div></template>

All view specific properties can be added to the <template> tag as data-* attributes.

Related Information

Declarative Support [page 133]

1.3.1.3 Controllers

A controller in SAPUI5 is used to separate view logic from model logic. All methods for controlling the data flow should be implemented in a controller.

Controller Definition

You define a simple controller without functions as follows:

sap.ui.controller("sap.hcm.Address", { // controller logic goes here});

The string in quotes specifies the controller name. The controller file is then named Address.controller.js.

NoteThe suffix .controller.js is mandatory for controllers.

Lifecycle Hooks

SAPUI5 provides predefined lifecycle hooks for implementation. You can add event handlers or other functions to the controller and the controller can fire events, for which other controllers or entities can register.

SAPUI5 provides the following lifecycle hooks:

● onInit(): Called when a view is instantiated and its controls (if available) have already been created; used to modify the view before it is displayed to bind event handlers and do other one-time initialization

● onExit(): Called when the view is destroyed; used to free resources and finalize activities



● onAfterRendering(): Called when the view has been rendered and, therefore, its HTML is part of the document; used to do post-rendering manipulations of the HTML. SAPUI5 controls get this hook after being rendered.

● onBeforeRendering(): Invoked before the controller view is re-rendered and not before the first rendering; use onInit() for invoking the hook before the first rendering

NoteFor controllers without a view, no lifecycle hooks are called.

sap.ui.controller("sap.hcm.Address", { onInit: function() { this.counter = 0; }});

Event Handlers and Other Functions

In addition to lifecycle hooks, a controller can define additional methods that serve as event handlers or additional functionality offered by the controller.

sap.ui.controller("sap.hcm.Address", { increaseCounter: function() { this.counter++; }});

API Reference

sap.ui.core.mvc.Controller

1.3.1.4 Data Binding

Data binding is used to bind two data or information sources together to keep them in sync. If data binding is implemented and defined properly, all changes in one data source are automatically reflected in the other data source.

To achieve this, there is a model and a data binding. The model instance holds the data and provides methods to set the data or to retrieve data from a server. It also provides a method for creating bindings to the data. When this method is called, a data binding instance is created, which contains the binding information and provides an event, which is fired whenever the bound data is changed. An element can listen to this event and update its visualization according to the new data.

Usually, the UI uses data binding to bind UI controls to the model, which holds the application data, so that the controls are updated automatically whenever application data is changed. The data binding is also used when



http://help.sap.com/disclaimer?site=https://sapui5.hana.ondemand.com/sdk/#docs/api/symbols/sap.ui.core.mvc.Controller.html

changes in the control cause updates in the underlying application data, such as data being entered by a user. This is called two-way binding.

The default binding mode for model implementations (if not implemented otherwise) is two-way binding and the supported binding modes by the model are one-way binding, two-way binding and one-time binding. The default binding mode can be changed by the application for each model instance. A model implementation should specify its supported binding modes and set the default binding mode accordingly (e.g. if the model supports only one way binding the default binding mode should also be set to one way).

Related Information

Binding Modes [page 58]Models and Data Binding [page 84]

1.3.1.4.1 Binding Modes

A model implementation supports different binding modes. The following binding modes are available:

● One Way: One-way binding means a binding from the model to the view; value changes in the model update all corresponding bindings and the view

● Two Way: Two-way binding means a binding from the model to the view and from the view to the model; value changes in the model and in the view update all corresponding bindings and the view and model, respectively

● One Time: One-time binding means from model to view once.

The models support different binding modes, The JSON model and the XML model support one-way, two-way data binding, and one-time binding modes, whereas the OData model currently supports one-way binding and one-time binding. The resource model only supports the one-time binding mode because it deals with static texts only.

The following table shows, which binding modes the respective binding models support:

Model One-way Two-way One-time

Resource model -- -- X

JSON model X X X

XML model X X X

OData model X -- X

Default Binding Mode of Models

When a model instance is created, the instance has a default binding mode. All bindings of this model instance have this binding mode as their default.

The following table shows the supported binding modes and their default binding mode for each model implementation.



Model Default binding mode

Resource model One-time

JSON model Two-way

XML model Two-way

OData model One-way

API Reference

sap.ui.model.BindingMode

1.3.2 Resource Handling

There are two layers in SAPUI5 which are responsible for resource handling and which work completely independent from each other: The client side and the server side.

The resource handling of SAPUI5 is separated in two parts - a client-side and a server-side resource handling.

Server-side Resource Handling

SAPUI5 provides resource handlers for different servers. The main purpose of the server-side resource handlers is to provide access to the SAPUI5 libraries. It improves the interaction between client and server, for example in providing a server-side locale fallback for the language, which helps to avoid multiple requests to get the correct language. It is also used to support modularized development of SAPUI5 applications and libraries.The Java resource handler is aligned with the concept of the JavaServer Faces.

Client-side Resource Handling

On the client-side SAPUI5 provides the following mechanisms to manage resources:

● It supports localization of application texts with resource bundles.● It allows to modularize the JavaScript files.

Both concepts are loading additional resources from a server where this server might be any kind of web server. It does not depend on any server side technology.



http://help.sap.com/disclaimer?site=https://sapui5.hana.ondemand.com/sdk/#docs/api/symbols/sap.ui.model.BindingMode.html

Related Information

Modularization and Resource Handling [page 163]

1.3.3 Libraries

The basis of SAPUI5 is a set of JavaScript and CSS libraries.

To use these libraries, different ways to embed them into your application are provided and this is handled automatically by the respective resource handler. You can use different libraries in one application.

The mobile library, called sap.m, ist designed especially for mobile devices and tablets, but can be used for desktop applications as well. The other libraries are designed for desktop applications and can be used to run on tablets as well, but not focussed on mobile devices.

Table 1: Main UI LibrariesLibrary

Description Supported Devices API References

Mobile Tablet Desktop

sap.ui.commons

Common library for standard controls

-- Yes Yes sap.ui.commons

sap.m

Library with controls specialized for mobile devices.

Yes Yes Yes sap.m

sap.me

SAPUI5 library with controls specialized for mobile devices (extension).

Yes Yes Yes sap.me

sap.makit

SAPUI5 library contains the makit charts.

Yes Yes -- sap.makit

sap.ui.ux3

SAPUI5 library with controls that implement the SAP User Experience (UX) Guidelines 3.0

-- Yes Yes sap.ui.ux3

sap.viz

SAPUI5 library containing chart

Yes Yes Yes sap.viz



http://help.sap.com/disclaimer?site=https://sapui5.hana.ondemand.com/sdk/#docs/api/symbols/sap.ui.commons.html

http://help.sap.com/disclaimer?site=https://sapui5.hana.ondemand.com/sdk/#docs/api/symbols/sap.m.html

http://help.sap.com/disclaimer?site=https://sapui5.hana.ondemand.com/sdk/#docs/api/symbols/sap.me.html

http://help.sap.com/disclaimer?site=https://sapui5.hana.ondemand.com/sdk/#docs/api/symbols/sap.makit.html

http://help.sap.com/disclaimer?site=https://sapui5.hana.ondemand.com/sdk/#docs/api/symbols/sap.ui.ux3.html

http://help.sap.com/disclaimer?site=https://sapui5.hana.ondemand.com/sdk/#docs/api/symbols/sap.viz.html

Library

Description Supported Devices API References

controls based on the VIZ charting library

More Information

The Controls section of the SAPUI5 Demo Kit provides detailed information including coding samples and details

on the properties, aggregations and events: SAPUI5 Demo Kit: Controls

The API reference for all libraries can be found here: SAPUI5 Demo Kit: API Reference

1.3.3.1 Artifacts

The table gives an overview of the artifacts used in UI development toolkit for HTML5 (SAPUI5).

Artifact Description

Library Top-level structural unit in SAPUI5

Libraries are the master artifacts in the SAPUI5 extensibility concept. They bundle a set of controls and related types and make them consumable by Web applications. There are predefined and standard libraries, such as sap.ui.commons with many commonly used controls. At the same time, it treats custom UI librares as first-class citizens, making it easy for you to write and use your own controls alongside the predefined controls.

Element Basic building block for SAPUI5 interfaces

Elements are reusable entities with properties, events, methods, and relations. The most important relations are aggregations to other UI elements, and in this way a tree structure of elements can be created.

control Subclass of an element, which can be used as root of a tree structure

Controls serve as an entry point, especially for rendering purposes. They are responsible for appearance and user interaction of a rectangular screen area. Examples for controls are Button, Label, TextField, or Table.



http://help.sap.com/disclaimer?site=https://sapui5.hana.ondemand.com/sdk/#content/Controls/index.html

http://help.sap.com/disclaimer?site=https://sapui5.hana.ondemand.com/sdk/#docs/api/symbols/sap.ui.html

Artifact Description

In addition to controls, the platform also provides elements that are not controls and are not used as root of the tree structure, but as dependent parts within it, for example TableRow and TableCell.

property Properties have a name and an associated data type and a well-defined default value expressed as a literal of the respective data type. Properties can be accessed from the application code by means of the element's API as getters and setters, but are also used read-only by a control renderer.

data type First class entities in the meta model; allow reuse of types across libraries and the extensibility of the type system

The SAPUI5 core library (sap.ui.core) provides a predefined set of types that can be used in other libraries.

aggregation Type of relation between UI elements defining aparent-child relation within the tree structures

Aggregations are relation types where the related entities are UI element types. The parent end of an aggregation has cardinality 0..1 and the child end can either have cardinality 0..1 or 0..*. The element's API as generated by SAPUI5 tools offers consistent methods for aggregations, for example, to get, set, or remove target elements.

Examples for aggregations are table rows and table cells or the content of a table cell.

association Type of relation between two UI elements, independent of the parent-child relation within the tree structure

SAPUI5 supports directed outgoing associations to a target of cardinality 0..1. Associations represent a loose coupling and are, thus, implemented by storing the ID of the target element instance. A typical example is the association between a label and its field.

event Events have a name and any number of parameters. The element's API offers support to manage event subscriptions.

1.3.4 SAPUI5 Components

Components are independent and resuable parts used in SAPUI5 applications. An application can use components from different locations from where the application is running. Thus, components can be developed by different development teams and be used in different projects.



NoteConstraints due to cross-origin issues also apply to components.

Components also support the encapsulation of closely related parts of an application into a particular component. This makes the structure of an application and its code easier to understand and to maintain.

SAPUI5 provides the following two types of components:

● UI components (class: sap.ui.core.UIComponent)UI components represent a screen area or element on the user interface, for example, a button or a shell, along with the respective settings and metadata.

● Faceless components (class: sap.ui.core.Component)Faceless components do not have a user interface and are used, for example, for a service that delivers data from a back end system.

The sap.ui.core.Component class is the base class for UI and faceless components. To extend the functionality, components can inherit from their base class or from another component.

Structure of a Component

A component is a folder. The folder name defines the component name and contains all optional and required resources that are used in the component except for the required SAPUI5 libraries and child components. Optional resources are, for example, the CSS and internationalization files, views, and images. The following files are mandatory for components:

● component.jsThis is the component controller and provides the runtime metadata (properties, aggregation, events) and the component methods. The name parameter that is passed to the component constructor represents the package name under which you can find the component.

● component.jsonThis is the component descriptor and contains the design-time metadata; you need this file for design-time environments such as the AppDesigner. The file is not loaded during runtime.

NoteAll paths within a component are relative paths to the component.js file and not to the index.html file.

The following figure gives an example of a component folder structure.



The ComponentContainer control wraps a UI component. You use the control in the SAPUI5 control tree in the same way as any other control.

Related Information

Defining a Component for SAPUI5 from Scratch [page 141]Describes how to define a component for SAPUI5 from scratch

1.3.5 Extensibility Concept: Adapting SAPUI5 Applications

SAPUI5 supports the adaptation of standard applications to specific requirements. The information about the adapted objects is stored in the component configuration. The standard application itself is not changed. The customized application becomes the start-up project and launches the standard application with the additional customizing configuration.

SAPUI5 supports the following adaptations of the standard::

● View extensions by using extension points to insert custom content (views or fragments)● Replacing standard views with customized views● Modifying views by changing specific properties● Controller extensions by adding code or overriding existing code● Customizing i18N resource texts

1.4 Developing User Interfaces with SAPUI5



1.4.1 Bootstrapping and Configuration of SAPUI5

This section provides information about bootstrapping and configuration options for SAPUI5.

To use SAPUI5 for your application, you must load and initialize SAPUI5 in your HTML page. You can use the SAPUI5 bootstrap script in your page to initialize SAPUI5 runtime automatically as soon as the script is loaded and executed by the browser. For simple use cases as well as the default SAPUI5 installation, this is sufficient to build and run UIs.

Additionally, you can specify the set of SAPUI5 libraries and the theme used for your application in the configuration settings.

The following code snippet shows a typical bootstrap script tag:

#!text/html <script id="sap-ui-bootstrap" type="text/javascript" src="resources/sap-ui-core.js" data-sap-ui-theme="sap_goldreflection" data-sap-ui-libs="sap.ui.commons" > </script>

The attributes data-sap-ui-theme="sap_goldreflection" and data-sap-ui-libs="sap.ui.commons" already provide examples of how SAPUI5 runtime can be configured to the needs of an application.

Related Information

Bootstrapping: Loading and Initializing SAPUI5 in HTML Pages [page 65]Initialization Process [page 70]Configuration of the SAPUI5 Runtime [page 71]

1.4.1.1 Bootstrapping: Loading and Initializing SAPUI5 in HTML Pages

To use SAPUI5 for your application, you must load and initialize SAPUI5 in your HTML pages. For this, SAPUI5 provides several bootstrap files to support different use cases of bootstrapping. All supported use cases have in common that you need to load and execute at least one SAPUI5-specific JavaScript resource.

The following table gives an overview of the most important resources and the respective use cases. The resource names refer to the resources/ folder in the SAPUI5 installation. The actual base URL depends on your platform and administrative setup.



Resource Description

sap-ui-core.js This is the standard bootstrap file. It already contains jQuery, jquery-ui-position and only the minimum required parts of the SAPUI5 core library (sap.ui.core). Required files are loaded dynamically using XMLHttpRequest (XHR).

For more information, see Standard Variant for Bootstrapping.

sap-ui-core-nojQuery.js You use this bootstrap file for applications with their own jQuery version. It also contains the minimum required parts of the SAPUI5 core library, but not jQuery and jquery-ui-position.

For more information, see noJQuery Variant for Bootstrapping.

sap-ui-core-all.js This bootstrap file contains almost all resources of the sap.ui.core library. Only a few duplicates, such as multiple jQuery versions, testing resources, and so on, are omitted. If you use this file for bootstrapping, the *-all.js file is also loaded for all other libraries. This reduces the number of JavaScript requests to the number of libraries (typically 1..4).

NoteTo ensure proper encapsulation, the *-all.js files will be renamed in future versions of SAPUI5. The sap-ui-core-all.js file remains as is, but for the files for other libraries a name relative to the libary will be used, for example sap/ui/commons/library-all.js. Applications must not address these files directly as SAPUI5 runtime loads them. Only sap-ui-core-all.js can be directly referenced in the bootstrap tag.

For more information, see All-in-one per Library Variant for Bootstrapping.

sap/ui/core/library-preload.js This bootstrap file is similar to the sap-ui-core-all.js file, but the modules are parsed and executed only on demand, and not immmediately.

CautionAn application must not reference this file. If the configuration option is set to preload, SAPUI5 automatically loads the file.

For more information, see Preload Variant for Bootstrapping.



Resource Description

sap-ui-core-lean.js This bootstrap file is similar to the sap-ui-core.js file, but in this use case only the jQuery and one SAPUI5 file are loaded immediately and the other files are loaded dynamically.

NoteThis use case is usually not used and may be removed in future.

sap-ui5.js This bootstrap file contains all JavaScript modules from the sap.ui.core, sap.ui.commons, sap.ui.table and sap.ui.ux3 libraries. If you use this file for bootstrapping, you only need one single request, but the loading time may be longer as the loading time for other use cases. Another drawback of this use case is the fixed set of libraries.

This file is only available on platorms based on the sapui5.war or sapui5-static.zip artifacts. The OSGi/Eclipse versions (com.sap.ui5.core.jar), for example, do not contain this file.

For more information, see sap-ui5 Variant for Bootstrapping.

sap-ui-custom*.js This bootstrap file is reserved for custom merged files created by the application.

NoteThe proposed naming scheme for these files needs to be adapted in future versions for the same encapsulation reasons as mentioned above.

Related Information

Initialization Process [page 70]

1.4.1.1.1 Standard Variant for Bootstrapping

The standard variant is the most common use case for bootstrapping. In this variant, you include the sap-ui-core.js file in your HTML page. This variant is self-contained, meaning that it already contains jQuery as well as



some jQuery plugins. An applications only specifies the sap-ui-core.js file on its page and SAPUI5 runtime does the rest automatically.

<script id="sap-ui-bootstrap" src="resources/sap-ui-core.js" data-sap-ui-libs="sap.ui.commons" data-sap-ui-theme="sap_goldreflection" > </script>

SAPUI5 synchronously loads the libraries specified in the data-sap-ui-libs configuration option. If a libary requires a library that is not specified in the configuration, SAPUI5 loads this library automatically. You use the data-sap-ui-theme configuration option to specifiy the style sheet you want to load for all libraries.

Subsequent to the bootstrap script tag, an application can call most of the SAPUI5 APIs. The application can access the core APIs, or instantiate, configure, and place controls. The document object model (DOM), however, can only be accessed after the controls have been rendered, that is, only after the document is ready. The application can use the attachInitEvent method to be notified about that event.

NoteIn the default configuration, SAPUI5 automatically activates the preload=sync mode when running from optimized sources. For more information, see Preload Variant for Bootstrapping.

Related Information

Configuration of the SAPUI5 Runtime [page 71]

1.4.1.1.2 noJQuery Variant for Bootstrapping

You can use the noJQuery variant for bootstrapping if your application already integrates jQuery and/or if you want to use a jQuery version that is different to the version integrated in SAPUI5. In this variant, you include the resources/sap-ui-core-noJQuery.js file in your HTML page. Make sure that jQuery and jquery-ui-position have been loaded beforehand. See the following code snippet for an example.

 <script src="my-jQuery-min.js" ></script>

 <script src="resources/jquery-ui-position.js" ></script>

 <script id="sap-ui-bootstrap" src="resources/sap-ui-core-nojQuery.js" data-sap-ui-libs="sap.ui.commons" data-sap-ui-theme="sap_goldreflection" > </script>

1.4.1.1.3 Preload Variant for Bootstrapping

In the preload variant, SAPUI5 loads all JavaScript modules of a library in advance with one single request. The runtime executes the code only if the application requires the module. Thus, the preload variant significantly reduces the number of roundtrips. To activate the preload variant, set the preload configuration parameter with one of the following values:

● syncIf you set the preload configuration parameter to synch, the runtime loads the modules for all declared libraries synchronously. After processing the bootstrap tag, all preload files of all libraries are loaded and the libraries are initialized as usual. The preload=sync mode should be transparent for most applications.

● asyncIf you set the preload configuration option to asynch, the runtime loads the modules for all declared libraries asynchronously. Thus, any code that follows the SAPUI5 bootstrap tag can not be sure that the SAPUI5 classes are available already. Therefore, the application must delay the access to the SAPUI5 APIs by using the Core.attachInitEvent method. SAPUI5 supports the asynch mode only for libraries that are loaded by the SAPUI5 core. Libraries that are loaded dynamically by using the sap.ui.getCore().loadLibrary() API will be preloaded with preload=sync.

● autoThe preload=auto configuration parameter is the default value. This mode checks whether SAPUI5 runtime uses optimized sources. If optimized sources are used, it enables the preload=sync option to further optimize the runtime. For normal or debug sources, the preload is deactivated.

NotePreload sources always have to be optimized. Therefore, using the preload variant with the debug configuration parameter is counterproductive and debug always overrides the preload configuration parameter.

You can easily check the preload variant with an existing application by specifying the sap-ui-preload=/mode/ parameter in the start URL by adding the data-sap-ui-preload attribute to the bootstrap tag:

<script id="sap-ui-bootstrap" src="resources/sap-ui-core.js" data-sap-ui-libs="sap.ui.commons" data-sap-ui-theme="sap_goldreflection" data-sap-ui-preload="sync" > </script>

NoteThe preload=async option requires active cooperation of the application. It is therefore not activated automatically, but only by configuration.

NoteYou can combine the preload configuration option with other bootstrap variants such as sap-ui-core-noJQuery.



Related Information

noJQuery Variant for Bootstrapping [page 68]Configuration of the SAPUI5 Runtime [page 71]

1.4.1.1.4 All-in-one per Library Variant for Bootstrapping

The request behavior of the all-in-one per library variant is similar to the request behavior of the preload=sync variant, but it immediately executes all code for a library. This variant is a predecessor of the preload variant and should no longer be used.

1.4.1.1.5 sap-ui5 Variant for Bootstrapping

The sap-ui5 variant is a predecessor of the preload variant. It loads all classes and controls of the four standard SAPUI5 libraries sap.ui.core, sap.ui.commons, sap.ui.table, sap.ui.ux3 with one single request. The sap-ui5 variant has the following constraints:

● You can not extend the set of libraries. For custom libraries you must use the all-in-one variant instead.● All the contained code is executed. This may increase the initial startup time of the application depending on

the browser, the client computer or device, and so on.● The file size is huge.

We recommend to use the preload variant instead. Keep in mind that the preload variant is used automatically for optimized sources.

1.4.1.2 Initialization Process

During the initialization of SAPUI5 runtime, the following steps are executed:

1. The jQuery plugins, which are mainly located in the jQuery.sap namespace, provide fundamental functionality of SAPUI5, such as the modularization concept, a small logging framework, performance measurement, and so on.

2. If not already available, the global object sap is created.3. The sap.ui.core.Core class is executed with all its dependencies.4. The runtime configuration is determined from different sources.5. All libraries and modules declared in the configuration as well as their dependencies are loaded.6. For each loaded library, the style sheet of the configured theme is added to the page.7. When all libraries are loaded and the document is ready, the initEvent of the core is fired and all registered

handlers are executed.



1.4.1.2.1 Loading of Additional Resources During Bootstrap

Context

During bootstrap, SAPUI5 runtime loads and interprets the following additional resources for each control library that is loaded:

Procedure

1. Library bootstrap file /''context-path''/resources/''library-name''/library.jsA JavaScript file that contains the JavaScript code for all enumeration types provided by the library as well as library-specific initialization code that is independent from the controls in the library. The file calls the sap.ui.getCore().initLibrary method with an object that describes the content of the library (list of contained controls, elements etc.). For libraries that have been developed with SAPUI5 application development tools or the SAPUI5 offline build tools, this file is generated automatically during the build.

2. Library style sheet file /''context-path''/resources/''library-name''/themes/''theme-name''/library.cssA standard CSS file that contains all styles relevant for this library. For libraries that have been developed with the SAPUI5 application development tools, this file is generated automatically during the build.

1.4.1.2.2 Dynamic Loading of Libraries

In addition to declaring libraries in the runtime configuration, you can also use sap.ui.getCore().loadLibary() to load an additional library at runtime.

You can use all controls from these libraries after loading. The restriction that document object model (DOM) access is only possible after document.ready and rendering applies for these libraries in the same way as for the declared libaries.

1.4.1.3 Configuration of the SAPUI5 Runtime

SAPUI5 provides the following options for providing configuration settings for SAPUI5 runtime:

● Runtime default values● Individual script tag attributes● Single and complex configuration attributes● Global configuration object● URL parameters



● Runtime configuration object

The following order of significance applies:

Attributes of the DOM reference override the system defaults. URL parameters override the DOM attributes; empty URL parameters set the parameter back to its system default. If you call setters at runtime, any previous settings calculated during object creation are overwritten.

Configuration Using Runtime Default Values

SAPUI5 runtime provides a default value for each configuration option. For an overview of the default values, see Configuration Options.

Individual Script Tag Attributes

You can specify the configuration settings by means of one or more attribute in the bootstrap script tag. For each configuration option, SAPUI5 accepts an attribute with a corresponding name in the bootstrap script tag with the following information:

● Attribute nameThe attribute name is composed of the configuration option name and the data-sap-ui- prefix. The first part of the prefix (data-) is necessary to comply with the W3C recommendations for custom attributes in HTML. The second part (-sap-ui-) separates SAPUI5 attributes from custom attributes defined by any other framework.Attribute names in HTML are case-insensitive and the same applies to the configuration attribute names. However, SAPUI5 has defined some configuration options names in camel case, for example originInfo. SAPUI5 converts these names automatically to lower case when accessing the configuration.

● ValueElement attributes in HTML have a string value by definition. For configuration options of type string, the attribute value is equivalent to the value of the option.

NoteIf the value contains specific HTML characters, such as '<' or '>', or if the value contains the same quote character that is used to wrap the attribute value, the usual HTML escape mechanisms must be used: Use entities for the specific HTML characters, for example < instead of <, and switch the type of quotes from single to double or vice versa.

For configuration options that are not of type string, the format of the allowed values has to be defined as follows:

Type Notation/Values

string Just a string, but escaped according to the HTML conventions



Type Notation/Values

boolean 'true' and 'x' are both accepted as true values (case-insensitive), all others are false. We recommend to use 'false' for false values

int Any integer value

string array Comma separated list of values; comma is not supported in the values (no escaping)

map from string to string JavaScript object literal (preferably JSON syntax)

Single and Complex Configuration Attributes

Instead of attaching individual options with individual configuration attributes to the script tag, you can use a single attribute with a more complex structure. The attribute name for the complex configuration is data-sap-ui-config. Its content is similar to the global configuration object, but without the enclosing parenthesis: It is a comma separated list of key/value pairs.

NoteThe usual HTML escape mechanisms must be used if the value contains specific HTML characters (<, >, &) or the quote character that is used to enclose the attribute value.

#!text/html <script id="sap-ui-bootstrap" type="text/javascript" src="resources/sap-ui-core.js" data-sap-ui-config="theme:'sap_platinum',libs:'sap.ui.commons'" > </script>

Global Configuration Object

Another way of specifying the configuration is to create a property in the global window object with property name sap-ui-config. The property must be a simple object, where each property represents the configuration option of the corresponding name.

NoteThe name of the window property intentionally is not a valid JavaScript identifier. This helps to avoid conflicts with typical JavaScript coding and the structured nature of the name is intended to avoid conflicts with SAP objects. To define the object, quotes must be used.

NoteIf a configuration option has a name that is not a valid JavaScript identifier or that is a reserved token in JavaScript, the property name in the configuration object must be quoted. Currently, such a configuration option does not exist.



NoteAs the configuration is evaluated during bootstrap, the configuration object must be created before SAPUI5 is booted. Otherwise, the contained configuration cannot be evaluated. As a consequenece, using the global configuration object requires another script tag in front of the bootstrap script tag. It is up to the application whether it uses an inline script tag or a separate JavaScript file, which is loaded via a script tag, for this purpose. If you use a dedicated file, it may require more work initially, but offers the following advantages:

● Several pages can share the file and, thus, use the same configuration.● The Content Security Policy (CSP) mechanism as introduced, for example, by FireFox 4.0 and others

requires the use of a file.

The following code snippet shows an example for an inline script tag:

#!text/html <script type="text/javascript"> window["sap-ui-config"] = { theme : "sap_platinum", libs : "sap.ui.commons", }; </script> <script id="sap-ui-bootstrap" type="text/javascript" src="resources/sap-ui-core.js" > </script>

Although this option requires an additional script/script tag, it offers the possibility to share configuration between pages, it can be used in environments where the scrip tag cannot be influenced (for example, because it is created out of some configuration, like in some mashup frameworks), and it allows to provide configuration before the core boots.

URL Parameters

You can specify confiuration parameters by adding them as parameters to the start URL of an application. The name of the URL parameters is composed of the name of the configuration option and the sap-ui- prefix.

NoteThe W3C proposed data- prefix is not needed and even not allowed here as all URL parameters are kind of custom parameters.

The value of a URL parameter is of type string and the same type mapping as for HTML attributes applies. However, URLs require a different encoding than HTML; they use, for example % encoding instead of entity encoding.

For security reasons, only some configuration options can be set via URL parameters. An application can set the ignoreUrlParameters option to true to disable URL configuration parameters completely.



Runtime Configuration Object

The above described options for configuration are all evaluated during SAPUI5 runtime boots. After that, all changes to these parameters are ignored. The final configuration result can be read by means of the sap.ui.getCore().getConfiguration() method.

The same object also provides set methods for a very limited set of configuration options. Such options can be modified at runtime and the runtime and/or the controls can react on the configuration changes. The most prominent (and so far only) example for such a configuration option is the theme.

Related Information

Configuration Options [page 75]

1.4.1.3.1 Configuration Options

The following list is an abstract of the available configuration options. For a complete list of all current configuration options, see the documentation of sap.ui.core.Configuration in the API reference at

sap.ui.core.Configuration .

Option Type Default Value URL Modifiable at Runtime

Description

theme string base x x This configuration parameter defines the theme that shall be used for the current page; you can change the theme at runtime by calling sap.ui.getCore().applyTheme().

language string user language x This configuration parameter defines the language that shall be used for localized texts, formattings, and so on.



http://help.sap.com/disclaimer?site=https://sapui5.hana.ondemand.com/sdk/#docs/api/symbols/sap.ui.core.Configuration.html


Description

The default value is not static, but determined from the browser or user language in the following order:

1. navigator.language

2. navigator.browserLanguage

3. navigator.userLanguage

formatLocale string undefined x This configuration parameter defines the locale used for formatting purposes; the default values for the locale are derived from the language.

accessibility boolean true x If set to true, the SAPUI5 controls are rendered for or running in accessibility mode.

animation boolean true x If set to true, animations are generally allowed in SAPUI5 controls.

rtl boolean false x If set to true, all controls are rendered in right-to-left (RTL) mode; not yet determined automatically.

debug boolean false x If set to true, the debug sources are




Description

loaded; if the bootstrap code is loaded from an optimized source, the bootstrap will be aborted and start anew from a debug source.

inspect boolean false x If set to true, the sap-ui-debug.js module is included and provides some supportability features

originInfo boolean false x If set to true, additional information for text resources is provided that allows to determine the origin of a translated text on the UI

noConflict boolean false ! If set to true, SAPUI5 forces jQuery into noConflict mode.

noDuplicateIds

boolean true x If set to true, this configuration parameter enforces that the same IDs are not used for multiple controls; we highly recommend this check as duplicate IDs may cause unforseeable




Description

issues and side effects.

trace boolean false ! If set to true, this configuration parameter activates an overlay div that contains a trace.

logLevel 0|1|2|3|4|5|6|NONE|FATAL|ERROR|WARNING|INFO|DEBUG|ALL

ERROR x x This configuration parameter sets the log level to the given value; for minified (productive) sources, the default level is ERROR, for debug sources it is DEBUG. At runtime, you can modify the log level by using the jQuery.sap.log.setLevel method.

modules string[] [ ] ! This configuration parameter defines a list of JavaScript modules that shall be loaded after the code has been initialized.

areas string[] null ! x This configuration parameter defines UI areas that shall be created in advance; use sap.ui.getCore().createUIArea to create new UI areas and sap.ui.getCore().getUIArea(id).destroy() to delete existing UI areas at runtime.

libs string[] [ ] ! x This configuration parameter defines




Description

a list of libraries that shall be loaded initially; use the loadLibrary() method to load further libraries.

themeRoots object undefined X sap.ui.getCore().setThemeRoot()

This configuration parameter defines the location of themes.

onInit code undefined ! This configuration setting defines if code has to be executed after the initialization

uidPrefix string '--' ! Prefix to be used for automatically generated control IDs; must be choosen carefully to avoid conflicts with IDs defined by the application or DOM IDs.

ignoreUrlParams

boolean false ! Security-relevant parameter that allows applications to disable configuration modifications via URL parameters.

weinreServer string URL to a WEINRE server to be used for debugging purposes; if set, SAPUI5 automatically includes the WEINRE target modules.

weinreId string x

xx-loadAllMode

boolean false !Note

This is an experimental feature and may be




Description

modified or removed in future versions.

This configuration parameter is used internally by SAPUI5 runtime. To activate it, load sap-ui-core-all.js instead of sap.ui.core.js.

preload not specified, auto, sync, or asynch

auto ! Between loading SAPUI5 core runtime and further libraries, the so-called preload files are loaded. They contain all modules of a library. The modules are only loaded, but not executed, thus reducing initialization time.

The values are used as follows:

● When set to auto, SAPUI5 runtime automatically uses sync when running from optimized sources.

● When set to sync, the preload files for the declared libraries are




Description

loaded synchronously.

● When set to async, the preload files are loaded asynchronously.

● For any other value (for example blank), the preload feature is deactivated and modules are loaded on demand.

xx-test-mobile

boolean false xNote

This is an experimental feature, and may be modified or removed in future versions.

This configuration parameter activates support for mobile device-specific events, such as touch events. This enables you to test standard SAPUI5 controls on mobile devices.

xx-fakeOS string undefined xNote

This is an experimental feature and may be modified or




Description

removed in future versions.

You use this configuration parameter to simulate iOS, Android and BlackBerry on desktop PCs for easier development of mobile apps and controls. The following values are supported:

● ios● android● blackberry

The parameter modifies the user-agent and runtime and theming act as the selected mobile platform. This includes Browser detection mechanisms such as jQuery.browser.

NoteThis configuration parameter only works on desktop WebKit browsers, such as Chrome and Safari. On other browsers and on mobile devices the configuration




Description

parameter has no effect.

1.4.2 UI Control Constructors

The constructor is a special type of subroutine called to create an object. The constructor uses values to set control properties, thus preparing the new object for use. The following paragraphs explain the use of UI control constructors in SAPUI5.

In SAPUI5, control constructors accept the following arguments in the specified order:

1. An optional unique identifier of type string which must either be the first argument, or omitted altogether. If you omit the ID, the SAPUI5 framework automatically computes an ID. Specifying your own identifier allows your application to easily find the control and, for example, retrieve the current user input from it. Alternatively, you can keep a reference to the control in a variable.

2. One JSON-like object (object literal) as mSettings parameter that defines values for any property, aggregation, association, or event. If a specific name for a control is ambiguous, meaning that a property has the same name as an event, the framework assumes in the following order: Property, aggregation, association. To resolve ambiguities, add the respective prefix to the key in the JSON object: "aggregation:", "association:", or "event:".

The following code snippet shows an example of a constructor that is called to create a new text field "Hello World" with the specified tooltip and width:

var oTextField = new sap.ui.commons.TextField("testTextField", {value : "Hello SAPUI5", tooltip: "This is an example tooltip", width: "100px"});

The above example is an abbreviated version of the following code snippet with a detailed list of statements, which is alternatively supported:

var oTextField = new sap.ui.commons.TextField("testTextField"); oTextField.setValue("Hello SAPUI5"); oTextField.setTooltip("This is an example tooltip"); oTextField.setWidth("100px");

The supported parameters are documented in the JsDoc of the respective control.

1.4.3 UI Control API: Event Handling

You can register JS event handlers for any controls that raise events. The control API provides attach<EventName> methods as shown in the following example:

#!js



data source. It should also be possible to create a custom model implementation for data sources that are not yet covered by the framework or are domain-specific.

Related Information

Data Binding: Getting Started [page 85]Models and Data Binding in Applications [page 89]

This page describes how data binding can be used in SAPUI5 applications. It describes how to create a model instance, how to assign it to the UI, and how the controls on the UI can be bound to the model.

Binding Types [page 107]

1.4.4.1 Data Binding: Getting Started

This chapter gives an overview of how to use data binding in conjunction with SAPUI5 controls in a simple application. It provides information about binding data to a property of a control (property binding) as well as binding a collection of values (aggregation/list binding).

The following steps show how you use data binding in your application:

1. Decide on the model you want to use. Depending on the service or backend type, you can choose a different model that supports your backend. Currently, model implementations for JSON, XML format, and OData services are available. If no suitable model for your backend is available, you can use your own implementation.

2. Create a model instance.3. Create a control instance.4. Bind properties or lists of the control to your model.5. Unbind properties if you wish.

The following example uses the JSON model. This model is not specific to a particular backend type or implementation. The only requirement is that the data for the model is provided in JSON format.

The JSON model supports two-way/bidirectional data binding by default, which means that the model will automatically reflect changes to the view and vice versa.

Defining the Data

To define the data, proceed as follows:

1. Create a simple HTML page and load the SAPUI5 runtime.2. Create the data that you want to bind to a control property. As we are using the JSON model, you need to

provide this data in JSON format.3. Place the code into your sample page:

// JSON sample datavar data = {



firstName: "John", lastName: "Doe", birthday: {day:01,month:05,year:1982}, address:[{city:"Heidelberg"}], enabled: true};

Creating a Data Binding Model Instance

Now you create a new JSON data model and add the data you have created to the model, so that the data is stored there and can be used for binding. Finally, you attach the model to the SAPUI5 core so that it can be used by various controls. It is also possible to attach the model to a specific control by calling oElement.setModel(oModel).

// create JSON model instancevar oModel = new sap.ui.model.json.JSONModel();// set the data for the modeloModel.setData(data);// set the model to the coresap.ui.getCore().setModel(oModel);

Creating Controls and Property Binding

Now you can create the SAPUI5 controls and define the binding to the properties. In the sample, you first define a TextView control and a TextField control. Both controls should display the firstName property of the model. The corresponding control properties have to be bound to the model property. You do this directly in the control constructor by using {} braces and specifying the path to the property in the model. You do this for both controls.

// create your controls var oTextView = new sap.ui.commons.TextView("textView", { // bind text property of textview to firstName property in the model text: "{/firstName}", tooltip: "First Name"});var oTxt = new sap.ui.commons.TextField("txtField", { // bind text property of textfield to firstName property in the model value: "{/firstName}"});

Next you create a CheckBox control and bind its checked property to the enabled property in the model. You also do this for the previously created TextField by using an alternative binding notation:

// create your controlsvar oChkBx = new sap.ui.commons.CheckBox("box", { // bind checked property against enabled property in the model checked: "{/enabled}", change: handleCheckBoxChange});// generic bind method bindProperty(control property, model property)oTxt.bindProperty("enabled", "/enabled");

function handleCheckBoxChange(oEvent){ var bEnabled = oEvent.getParameter("checked"); // modify the enabled property value in the model to reflect changes



oModel.setData({enabled: bEnabled}, true); // true means merge the data instead of replacing};

The handleCheckBoxChange method sets the enabled property in the model, depending on the current checked state of the CheckBox.

In a last step, you create a button and define the update method for updating the firstName value in the model with the value of the TextField when the button is clicked.

// create your controlsvar oBtn = new sap.ui.commons.Button({ id: "btn", text: "Trigger Change", press: update});

function update(){ // modify the firstName property value in the model to reflect changes oModel.setData({firstName: sap.ui.getCore().byId("txtField").getValue()}, true);};

When you now open the sample application in the Web browser, you can see that the value of the firstName property is already displayed in the TextView and TextField. When you select the CheckBox, the enabled value is modified in the model (by the handleCheckBoxChange method), and the changes are immediately reflected in all control properties that are bound to this property. In this case, the TextField is enabled or disabled.

As described above, clicking the button modifies the firstName value in the model with the value of the TextView. When this happens, all control properties bound to this model field are updated immediately to reflect the changes (direction Model → View).

Additionally, since the JSON model supports two-way binding, entering a text value into the TextField will also update the corresponding value in the model, and the TextView will display the changes because it is bound to the same property (direction Model ← View).

The page then looks as shown in the following figure.



Aggregation Data Binding in a Simple Application

The above sample covers the binding of single properties to a control property. Now we want to focus on binding a collection of values, for example, binding multiple rows into a table, the values for a ListBox, or the items in a ComboBox.

In this example we use the RowRepeater control and bind it to a collection of data. Again, you start with the definition of data and set it to the model and the model to the core.

//create test datavar dataObject = { data : [{index:0, level: "Warning", description: "HAL: I'm sorry, Dave. I'm afraid I can't do that."}, {index:1, level: "Warning", description: "Windows Boot Manager has encountered a problem."}, {index:2, level: "Error", description: "Failwhale: Twitter is over capacity"}, {index:3, level: "Success", description: "Jun 25 12:20:47 pc1h kernel: lp0 on fire"}, {index:4, level: "Error", description: "Software failure. Press left mouse button to continue. Guru Meditation #00000004,#0000AACB."}, {index:5, level: "Error", description: "[root@localhost root]# Kernel Panic"}, {index:6, level: "Error", description: "That does not compute."}, {index:7, level: "Warning", description: "404 File not found. Stop messing with the URL."}, {index:8, level: "Success", description: "Blue Screen of Death."},};

//create JSON modelvar oModel = new sap.ui.model.json.JSONModel();oModel.setData(dataObject);sap.ui.getCore().setModel(oModel);

The next step covers the creation of the controls and the definition of a single Message control, which will be used as a template for all items in the RowRepeater. The Message control will hold the corresponding level and description values from the model so that these properties are bound to the model:

//create the template control that will be repeated and will display the datavar oRowTemplate = new sap.ui.commons.Message("rowTemplate", { text : "{description}", type : "{level}"});

Once the template is defined, you create the RowRepeater control. The RowRepeater has an aggregation rows, which can be any SAPUI5 control. In our case, this is the above mentioned Message control. You create an aggregation or list binding for this rows property. To do this, you specify the name of the array in the JSON model that contains the actual data (path) and also specify the Message row template:

//create the RowRepeater controlvar oRowRepeater = new sap.ui.commons.RowRepeater("rowRepeater", { design : "Standard", numberOfRows : 5, currentPage : 1, title : oTitle, // bind row aggregation rows : {path : "/data", template : oRowTemplate}});

The SAPUI5 runtime clones the row template for each entry in the JSON array for the data property and also binds the description and level properties for each message item.



The following figure shows a sample page.

1.4.4.2 Models and Data Binding in Applications

This page describes how data binding can be used in SAPUI5 applications. It describes how to create a model instance, how to assign it to the UI, and how the controls on the UI can be bound to the model.

SAPUI5 provides several binding modes and provides multimodel support.

Related Information

Creating a Model Instance [page 89]The first step when using data binding is to create a model instance and to provide the data for that model. This is different for each model.

Assigning the Model to the UI [page 104]Defining a Binding Path [page 105]Binding Controls to the Model [page 106]Multimodel Support [page 107]Setting the Default Binding Mode [page 106]

When a model instance is created, the instance has a default binding mode. You can overwrite this default setting.

1.4.4.2.1 Creating a Model Instance

The first step when using data binding is to create a model instance and to provide the data for that model. This is different for each model.

Prerequisites

You choose the model depending on the requirements and the availability of data formats on the server side. To help you to decide which model to choose, see: Models [page 52].



Procedure

To create a model instance for the respective model, choose one the following procedures:

○ Creating a Resource Model Instance [page 90]○ Implementing a JSON Model [page 92]○ Implementing an OData Model [page 94]○ Implementing an XML Model [page 101]○ If none of the predefined model meets your needs, create a custom model implementation, see

Implementing a Custom Model.

1.4.4.2.1.1 Creating a Resource Model Instance

The resource model is used as a wrapper for resource bundles. You can, for example, bind texts of a control to language-dependent resource bundle properties.

Procedure

1. With a bundleName, that is, the name of a resource bundle and equals a SAPUI5 module name within the require/declare concept

2. With a bundleUrl that points to the resource bundle

If you use the bundle name, the file must have the .properties suffix. If you do not specify a locale, the system uses the login language

var oModel = new sap.ui.model.resource.ResourceModel({bundleName:"myBundle",locale:"en"});

NoteIn this ResourceModel implementation you cannot pass parameters to your texts within the resource bundle. If you have to pass parameters, you must do this on your own. Therefore, you can load the bundle yourself or retrieve it from the model.

var myBundle = oModel.getResourceBundle();

After the instance has been created, you have a model containing the resource bundle texts as data.

Related Information

Modularization and Dependency Management [page 163]Localized Texts [page 273]



1.4.4.2.1.1.1 Binding Path Syntax for Resource Models

The ResourceModel has a simple binding path syntax, as it contains only a flat list of properties.

The following example shows a simple resource model that illustrates the possible binding paths: Resource bundle content:

CLOSE_BUTTON_TEXT=CloseOPEN_BUTTON_TEXT=OpenCANCEL_BUTTON_TEXT=Cancel

...Binding paths within the model:

CLOSE_BUTTON_TEXTOPEN_BUTTON_TEXTCANCEL_BUTTON_TEXT

1.4.4.2.1.1.2 Binding Texts to a Resource Bundle

To bind texts of a control in JSON views to a language-dependent resource bundle, define the resource bundle by a name (resourceBundleName property) or a URL (resourceBundleUrl property) and assign an alias (resourceBundleAlias property) for the bundle in the view definition.

Context

The ResourceModel required for binding these texts is created during view instantiation. The model is set as secondary model with the given alias to the view instance. If you want to bind other properties to another model, you have to create the model on your own in the corresponding controller or HTML page and attach it to the view with another alias. The binding itself behaves in the same way as every SAPUI5 data binding and as described above.

Procedure

1. Deifne the following resource bundle content: MY_TEXT=Hello World2. To bind this resource bundle contetn, insert the following code depending on the view type:

○ For a JSON view, insert the following code:

{ "Type": "sap.ui.core.JSONView", "controllerName":"my.own.views.test", "resourceBundleName":"myBundle", "resourceBundleAlias":"i18n", "content": [{ "Type":"sap.ui.commons.Panel", "id":"myPanel", "content":[{ "Type":"sap.ui.commons.Button",



"id":"Button1", "text":"{i18n>MY_TEXT}", "press": "doIt" }] }]}

○ For a XML view, insert the following code:

<core:View resourceBundleName="myBundle" resourceBundleAlias="i18n" controllerName="sap.hcm.Address" xmlns="sap.ui.commons" xmlns:core="sap.ui.core" xmlns:html="http://www.w3.org/1999/xhtml"> <Panel> <Button text="{i18n>MY_TEXT}"/> </Panel><core:View>

Related Information

Models and Data Binding [page 84]

1.4.4.2.1.2 Implementing a JSON Model

The JSON model can be used to bind controls to JavaScript object data, which is usually serialized in the JSON format. The JSON model is a client-side model and, therefore, intended for small datasets, which are completely available on the client. The JSON model does not support mechanisms for server-based paging or loading of deltas. It supports, however, two-way binding.

Procedure

1. To create a JSON model instance, insert the following code:

var oModel = new sap.ui.model.json.JSONModel();

2. After the instance has been created, there are different options to get the data into the model.

○ The easiest option is to set data by using the setData method:

oModel.setData({ firstName: "Peter", lastName: "Pan"});

NoteThe correct JSON notation uses double quotes for the keys and string values.



○ Usually, you do not define your data inline in the application but load it from a server-side service using an XHR request. The JSON model, however, also has a loadData method, which loads the JSON data from the specified URL asynchronously and applies it to the model:

oModel.loadData("data.json");

Next Steps

API Reference: sap.ui.model.json.JSONModel

1.4.4.2.1.2.1 Sorting and Filtering in JSON Models

Using a JSON model, all data is available on the client. Sorting and filtering are also implemented in JavaScript.

Context

This allows the usage of custom sorting and filtering methods in the JSONModel. To define custom methods, set the fnCompare method on the Sorter object or the fnFilter method on the Filter object after creating it.

Procedure

1. The fnFilter method of the Filter gets the value to test as the only parameter and returns, whether the row with the given value should be filtered or not.

var oFilter = new sap.ui.model.Filter("property");oFilter.fnFilter = function(value) { return (value > 100); };

2. The fnCompare method of the Sorter gets the two values to compare as parameters and returns -1, 0 or 1, dependent which of the two values should be ordered before the other:

var oSorter = new sap.ui.model.Sorter("property");oSorter.fnCompare = function(value1, value2) { if (value1 < value2) return -1; if (value1 == value2) return 0; if (value1 > value2) return 1;};



http://help.sap.com/disclaimer?site=https://sapui5.hana.ondemand.com/sdk/#docs/api/symbols/sap.ui.model.json.JSONModel.html

1.4.4.2.1.2.2 Binding Path Syntax for JSON Models

As the JSONModel only consists of named objects (properties, arrays, or nested objects), it has a simple binding path syntax.

The following example shows a simple JSONModel with the different binding paths:

{ company: { name: "Treefish Inc", info: { employees: 3, }, contacts: [ { name: "Barbara", phone: "873" }, { name: "Gerry", phone: "734" }, { name: "Susan", phone: "275" } ] }}

Absolute binding paths within this model:

/company/name/company/info/employees/company/contacts

Relative binding paths within the "/company" context:

nameinfo/employeescontacts

Relative binding paths within an aggregation binding of "/company/contacts":

namephone

1.4.4.2.1.3 Implementing an OData Model

Context

The OData model enables binding of controls to data from OData services. The OData model is a server-side model: the dataset is only available on the server and the client only knows the currently visible rows and fields. Sorting and filtering is done on the server. The client has to send a request to the server to accomplish these tasks.



NoteBe aware of the Same-Origin-Policy security concept which prevents access to backends on different domains or sites.

Procedure

1. To create an OData model instance:

var oModel = new sap.ui.model.odata.ODataModel("http://services.odata.org/Northwind/Northwind.svc/");

Requests to the service to fetch data are made automatically according to the data bindings defined in the controls.

The service URL is the first parameter of the constructor. One OData model instance can only cover one OData service. If you need access to multiple services, you have to create multiple instances of the OData model.

2. To add additional parameters:

When using OData services, you can use URL parameters for configuration. SAPUI5 sets most of the required URL parameters automatically according to the data binding. Two options for adding custom parameters to the request exist: URL parameters can be appended to the service URL and a map of parameters can be passed when using bindElement or bindAggregation.

Additional parameters, which are added to the OData service URL, are included in every request sent to the OData server. This is useful for authentication tokens or general configuration options.

var oModel = new sap.ui.model.odata.ODataModel("http://myserver/MyService.svc/?custom1=value1&custom2=value2");

3. For other parameters it makes no sense to include them in every request. These parameters should only be added to specific aggregation or element bindings, for example, $expand or $select. For this, the binding methods can pass a map of parameters, which is then included in all requests for this specific binding. Currently, the ODataModel only supports $expand and $select.

○ To use the $expand parameter see the following snippet below:

oControl.bindElement("/Category(1)", {expand: "Products"});

oTable.bindRows({ path: "/Products", parameters: {expand: "Category"}});

In the first example all products of Category(1) are embedded inline in the server response and loaded in one request. In the second example the Category for all Products is embedded inline the response for each product.

○ The $select parameter returns only the specified properties of requested entries.

oControl.bindElement("/Category(1)", {expand: "Products", select: "Name,ID,Products"});



oTable.bindRows({ path: "/Products", parameters: {select: "Name,Category"}});

In the first example the properties Name and ID ofCategory(1) and all properties of the embedded products are returned. In the second example the properties Name and Category are included for each product. The Category property will contain a link to the related Category entry.

4. To add custom query options:

You can add custom query options by placing them as a query string in the URL. The name of a query string does not begin with a $ character:

http://services.odata.org/OData/OData.svc/Products?x=y

You can also use custom query options as input parameters for service operations. You can specify the custom parameters during aggregation binding as follows:

oTable.bindRows({path: "/Products", parameters: { custom: { param1: "value1", param2: "value2" } }, template: rowTemplate });

For bindElement, you can specify custom parameters as follows:

oTextField.bindElement("/GetProducts", { custom: { "price" : "500" } });

5. To create virtual entries:

You can create empty objects for a specified collection name. The application can bind against these objects. By calling the submitChanges function, you can determine the point in time when these objects are persisted in the backend. The application has to trigger this explicitly. Before the objects are persisted in the backend, all created virtual entries are stored in a request queue and can still be removed. The application can choose which properties are included in the created object and may pass own default values for these properties. Otherwise, the property values remain empty.

Make sure that the collection and properties exist on the OData service and are defined in the metadata document as well. Here is an example:

// create an entry of the Products collection with the specified properties and values var oContext = oModel.createEntry("Products",{ID:99,Name:"Product",Description:"new Product",ReleaseDate:new Date(),Price:"10.1",Rating:1}); // use the returned context for binding against this entry oLayout.setBindingContext(oContext); oSimpleListBox.addItem(new sap.ui.core.ListItem({text: "Added entry: " + oContext.getPath()})); // to delete a created entry from the request queue without persisting it provide the created context to the deleteCreatedEntry function oModel.deleteCreatedEntry(oContext);

The createEntry function returns a context object which can be used to bind against the newly created entry. See the following example for how to write the entries in the request queue to the backend:

// provide optional success and error functions which are called for each request in the queue oModel.submitChanges(fnSuccess, fnError);



Next Steps

The default binding mode of the OData model is one-way, but as experimental write support is implemented, two-way binding can be enabled. For more information, see OData Write Suport.

API Reference: sap.ui.model.odata.ODataModel

1.4.4.2.1.3.1 Binding Path Syntax for OData Models

You access the data provided by the ODataModel according to the structure of the OData service as defined in the metadata of a service. The syntax of the binding path matches the URL path relative to the service URL used in OData to access specific entries or collections. URL parameters such as filters cannot be added to a binding path. The following samples of bindings within the ODataModel are taken from the well-known Northwind demo service.

Absolute binding paths:

/Customers/Customers('ALFKI')/Orders

Relative binding paths within a Customer context:

CompanyNameAddressOrders

Relative binding paths within an aggregation binding of "/Customer('ALFKI')/Orders:

OrderIDShipNameShipAdressEmployee/LastNameOrder_Details/Discount

1.4.4.2.1.3.2 OData Write Support

NoteAs these features are experimental, changes in future versions of SAPUI5 may occur. Currently, all write operations have to be performed by the application and are triggered synchronously.

SAPUI5 supports the following operations and features for the OData model:

● write● create● remove● update● read



http://help.sap.com/disclaimer?site=https://sapui5.hana.ondemand.com/sdk/#docs/api/symbols/sap.ui.model.odata.ODataModel.html

● get metadata service document● Cross-site request forgery (XSRF) token support for the REST library● refresh

The default binding mode is sap.ui.model.BindingMode.OneWay. You can also set the binding mode to sap.ui.model.BindingMode.TwoWay.

Create Request

The create function triggers a POST request to an OData service which was specified during creation of the OData model.

The application has to specify the collection where to create the entry and the entry data payload.

To get the result of the request, the application can hand over callback handler functions. To recreate and update the bindings, a refresh is triggered automatically after the successful creation.

The following code triggers a new entry in the Products collection:

var oEntry = {};oEntry.Name = "IPad";oEntry.Price = "499$";oModel.create('/Products', oEntry, null, function(){ alert("Create successful"); },function(){ alert("Create failed");});

Delete Request

The remove function triggers a DELETE request to an OData service which was specified during creation of the OData model. The application has to specify the path to the entry which should be deleted. To update the bindings in the model, a refresh is triggered automatically after successful deletion.

A single parameter oParameters can be passed into the function and can carry all optional attributes, such as attributes for success and error handling functions as well as ETag attributes. ETags can be used for concurrency control if the OData service is configured to provide them. For more information, see the section about concurrency control and ETags in the OData documentation.

If an ETag is specified in oParameters, it will be used inthe If-Match-Header nstead of any ETag found in the metadata of an entry. If not, the ETag is retrieved from the entry's metadata. In fo ETag is found, no If-Match-Header will be used.

The following code delets the product entry with ID=1 from the Products collection of the data service:

oModel.remove('/Products(1)', null, function(){ alert("Delete successful"); },function(){ alert("Delete failed");});



Update Request

The update function triggers a PUT request to an OData service which was specified during creation of the OData model. See the ODataModel API for information about attribute use.

The application has to specify the path to the entry which should be updated with the specified updated entry.

After a successful request to update the bindings in the model, a refresh is triggered automatically.

The following code updates the price:

var oEntry = {};oEntry.Price = "599$";oModel.update('/Products(1)', oEntry, null, function(){ alert("Update successful"); },function(){ alert("Update failed");});

The flag bMerge has been introduced to also allow a MERGE request to perform a differential update.

Read Request

The read function triggers a GET request to a specified path which should be retrieved from the OData service which was specified during creation of the OData model.

The retrieved data is returned in the success callback handler function.

oModel.read('/Products(1)', null, null, true, function(oData, oResponse){ alert("Read successful: " + JSON.stringify(oData)); },function(){ alert("Read failed");});

Refresh

The Refresh function triggers a refresh for each binding to check if a value has been updated, or not. For a list binding a new request is triggered to reload the data from the server.

Additionally, if the XSRF token is not valid any more, a read request is triggered to fetch a new XSRF token from the server.

XSRF Token

To address the challenge of Cross Site Request Forgery an OData service might require XSRF tokens for change requests by the client application for security reasons. In this case the client has to fetch a token from the server and send it with each change request to the server.



The OData model fetches the XSRF token when reading the metadata and then automatically sends it in each write request header. If the token is not valid any more a new token can be fetched by calling the refresh function on the OData model.

Metadata

The getServiceMetadata function returns the parsed metadata document as a JavaScript object.

1.4.4.2.1.3.2.1 Experimental Two-Way Binding

NoteThis feature is experimental and may change in future versions of SAPUI5.

The two-way binding mode enables the application to update values of a single collection entry without triggering an immediate change request. create and delete operations are not collected and can be called by the application as described above.

If the two-way binding mode is enabled, the setProperty function of the OData model is called automatically to update the value in the specified entry upon user input. If an update to a property of another entry is performed and there is already an update to an existing entry pending, a rejectChange event is fired and no change to the property value is stored in the model. The application can register to this event. Thus, before updating a different entry, the application has to submit or reset existing changes of the current entry:

● To reset the current changes the application can call the resetChanges function.● To trigger the final update request for the modified entry the application should call the submitChanges

function.

Callback handlers for these functions can be handed over as parameters.

To enable the two-way binding for the OData model the default binding mode has to be changed as follows:

oModel.setDefaultBindingMode(sap.ui.model.BindingMode.TwoWay);

After the binding is done, the application should attach to the rejectChange event to handle the user modifications to different entries accordingly and, for example, allow or reject user input for a specific entry.

oModel.attachRejectChange(this,function(oEvent){ alert("You are already editing another Entry! Please submit or reject your pending changes!");});

The application can use the hasPendingChanges function to determine if there is a pending change.

The application can then decide (or let the user decide) when to submit or reject the changes:

var oUpdateBtn = new sap.ui.commons.Button({ text : "Update", style : sap.ui.commons.ButtonStyle.Emph, press : function(){



oModel.submitChanges(function(){ alert("Update successful");); },function(){ alert("Update failed");}); }});

var oCancelBtn = new sap.ui.commons.Button({ text : "Cancel", style : sap.ui.commons.ButtonStyle.Reject, press : function(){ oModel.resetChanges(); }});

The submitChanges function also has an optional parameter oParameters which currently can have an attribute for an ETag.

1.4.4.2.1.4 Implementing an XML Model

The XML model allows to bind controls to XML data. It is a client-side model intended for small datasets, which are completely available on the client. The XML model does not contain mechanims for server-based paging or loading of deltas. It supports two-way binding.

Procedure

1. To instantiate the model:

var oModel = new sap.ui.model.xml.XMLModel();

2. The XML model also has a setData method. As XML documents cannot be embedded inline in JavaScript, the XMLModel uses an XML document reference as a parameter.

oModel.setData(oXMLDocument);

3. To create inline XML data or to get XML data as a string, the XML model provides a setXML method. This method takes XML in text format and uses the browser's XML parser to create a document.

oModel.setXML("<?xml version=\"1.0\"?><some><xml>data</xml></some>");

4. Usually, you load your data from the server using an HTTP-based service, so the loadData method provides an easy way to load XML data from the given URL:

oModel.loadData("data.xml");

Next Steps

For a complete listing of the available methods and parameters, see the API Reference.



1.4.4.2.1.4.1 Sorting and Filtering in a XML Model

When using an XML model, all data is available on the client. Sorting and filtering are implemented in JavaScript.

Context

To define custom methods, set the fnCompare method on the Sorter object or the fnTest method on the Filter object after creating it.

Procedure

1. To implement a filter:

The fnTest method of the Filter gets the value to test as the only parameter and returns, whether the row with the given value should be filtered or not.

var oFilter = new sap.ui.model.Filter("property");oFilter.fnFilter = function(value) { return (value > 100);};

2. To implement a sorter:

The fnCompare method of the Sorter gets the two values to compare as parameters and returns -1, 0 or 1, dependent which of the two values should be ordered before the other.

var oSorter = new sap.ui.model.Sorter("property");oSorter.fnCompare = function(value1, value2) { if (value1 < value2) return -1; if (value1 == value2) return 0; if (value1 > value2) return 1;};

1.4.4.2.1.4.2 XML Namespace Support

The XML model supports documents using XML namespaces.

For this purpose, you must declare namespaces using the setNameSpace method. The namespace prefixes do not necessarily need to be the same as in the XML document, they only used in the binding paths which are used to address nodes in the document.

Assumed this sample XML document:

<data xmlns="http://tempuri.org/base" xmlns:ext="http://tempuri.org/ext"> <ext:entry id="1" value="foo" /> <ext:entry id="1" value="foo" /></data>



The namespaces must be declared in the JavaScript like this, to be able to bind to them:

var oModel = new sap.ui.model.xml.XMLModel(oXMLDoc);oModel.setNameSpace("http://tempuri.org/base");oModel.setNameSpace("http://tempuri.org/ext", "e"); [...]oTable.bindRows("/e:entry");

1.4.4.2.1.4.3 Binding Path Syntax for XML Models

XML differentiates between attributes and content, XML has no arrays and defines lists as multiple elements with the same name instead.

This makes data binding in XML models more difficult. For attributes, a special selector using the "@" character exists and "text()" can be used to reference the content text of an element. Lists are referenced by using the path to the multiple element.

NoteFor the XML model the root must not be included in the path.

#!xml<companies> <company name="Treefish Inc"> <info> <employees>3</employees> </info> <contact phone="873">Barbara</contact> <contact phone="734">Gerry</contact> <contact phone="275">Susan</contact> </company></companies>

Absolute binding paths within this model:

/company/@name/company/info/employees

Relative binding paths within the /company context:

@nameinfo/employees/text()

Relative binding paths within an aggregation binding of /company/contact:

text()@phone

NoteIn a similar JSON model you would use /companies/company/locations as binding path for the locations collection. In an XML model the respective collection binding path is: /company/locations/location.



1.4.4.2.1.5 Implementing a Custom Model

Context

To create a custom model implementation, proceed as follows:

Procedure

1. Extend the Model class and specify the binding modes that the model should support (for example, two-way, one-way, one-time).

2. Extend the Binding class to suit your specific binding or reuse the existing specific binding implementations PropertyBinding, ListBinding, and/or TreeBinding.

3. To enable the filtering functionality, use the Filter class with FilterOperator enum in your binding implementation.

4. To enable the sorting functionality, use the Sorter class in your binding implementation.

Results

You can find all necessary classes in the sap.ui.model namespace.

As a starting point, take a look at the JSONModel implementation in sap.ui.model.json.JSONModel.

1.4.4.2.2 Assigning the Model to the UI

Context

Before you can bind controls to a model instance, you have to make it known to the framework. SAPUI5 provides a flexible and modularized concept in which you can not only define one model for your applications, but define different areas in your application with different models and assign single controls to a model. You can also define nested models, for example, a JSON model defined for the application and an OData model for a table control contained in the application.

In order to find the model it should bind to, the control looks up the parent hierarchy until it finds a control or UI area that has an assigned model. A control can only bind to one model, so if you have a container control with an assigned model, all controls contained in this container can only see the local model of the container and are no longer able to bind to the global model.



Procedure

Choose one of the following options:

○ You can define a global model that can be accessed by all controls from all UI areas by using the setModel method on the SAPUI5 core object. This is useful for simple form applications or demo applications.

sap.ui.getCore().setModel(oModel);

○ You can also define a specific model for sections within a UI area, for example, inside a panel or for a table control. In this case, you can use the setModel method available on any control:

var oTable = sap.ui.getCore().byId("table");oTable.setModel(oModel);

1.4.4.2.3 Defining a Binding Path

Context

You use binding paths to address the different properties and lists contained in a model. The binding path defines how a specific node in the hierarchical data tree can be found. A binding path contains a number of name tokens, which are separated by a separator char. In all models provided by the framework, the separator char is the slash "/".

A binding path can either be absolute or relative: Absolute binding paths start with a slash, relative binding paths start with a name token and are resolved relative to the contet of the control that is bound.

A context exists either for each entry of the aggregation in case of aggregation binding or can be set explicitly for a control by using the setBindingContext method. Relative bindings without a defined context are resolved relative to the model root.

The syntax is specific to the respective model.

Procedure

The syntax to define a binding path is different for each model:

○ JSON model: Implementing a JSON Model [page 92]○○○



1.4.4.2.4 Binding Controls to the Model

To retrieve data from the model for visualization in the UI, the controls have to be bound to the model, using a binding path as explained above. In general, the control itself, all properties of controls, and all multiple aggregations can be bound to a model.

Element binding allows to bind elements to a specific object in the model data, which will create a binding context and allow relative binding within the control and all of its children. This is especially helpful in master/detail scenarios.

Property binding allows properties of the control to get automatically initialized and updated from model data. You can only bind control properties to model properties of a matching type, or you use a formatter function or datatype to convert the data as needed.

Aggregation binding can be used to automatically create child controls according to model data. This can be done either by cloning a template control, or by using a factory function. Aggregations can only be bound to lists defined in the model, that is, to arrays in a JSON model or a collection in the OData model.

Related Information

Binding Types [page 107]

1.4.4.2.5 Setting the Default Binding Mode

When a model instance is created, the instance has a default binding mode. You can overwrite this default setting.

Procedure

1. To change the default binding mode directly after model creation, call the setDefaultBindingMode method on the model as follows:

var oModel = new sap.ui.model.json.JSONModel();oModel.setDefaultBindingMode(sap.ui.model.BindingMode.OneWay);

In this example, all new bindings for the model will have the one-way binding mode by default.2. You can, however, only set supported binding modes as default binding mode. You can check if a binding

mode is supported as follows:

var oModel = new sap.ui.model.json.JSONModel();if (oModel.isBindingModeSupported(sap.ui.model.BindingMode.OneTime)) { // true oModel.setDefaultBindingMode(sap.ui.model.BindingMode.OneTime); }



1.4.4.2.6 Multimodel Support

You can set an additional model for an element or for the core by specifying a name for the model to identify it:

var oModel = new sap.ui.model.json.JSONModel();// define data for that modeloModel.setData({ test: "Test", enabled: true});

// define a name for that modelsap.ui.getCore().setModel(oModel, "myModel");

To create property bindings for this model call

oText.bindValue("myModel>/test").

You can also create aggregation bindings for this model by calling:

oListItem.bindProperty("text", "myModel>text");oComboBox.bindItems("myModel>/items", oListItem);

You specify the model name and following the > sign you specify the binding path to the values in the model that is to be bound.

NoteYou can create a model with an identifying name without first creating a model without a name.

1.4.4.3 Binding Types

The following sections introduce the data binding types provided by SAPUI5:

● Property Binding● Aggregation Binding● Element Binding

1.4.4.3.1 Property Binding

To define a property binding on a control, the following two options exist:

● In the settings object in the constructor of a control● Using the bindProperty method of a control

Once you have defined the property binding, the property is updated automatically every time the bound model property value is changed.



The most convenient way to define a property binding, which is sufficient in most cases, is to include the binding path within curly brackets as a string literal in the settings object:

var oTextField = new sap.ui.commons.TextField({ value: "{/company/name}"});

Alternatively, you can use an extended syntax for property bindings. This extended syntax allows you to define additional binding information to be contained in the settings object, such as a formatter function. In this case you use a JS object instead of a string literal. This must contain a path property containing the binding path and can contain additional properties:

var oTextField = new sap.ui.commons.TextField({ value: { path: "/company/name", mode: sap.ui.model.BindingMode.OneWay }});

Depending on the use case, it can be useful to define the binding at a later time, using the bindProperty method:

oTextField.bindProperty("value", "/company/name");

This option also allows the use of the same object-literal as in the constructor to define the binding

oTextField.bindProperty("value", { path: "value", type: new sap.ui.model.type.Integer()});

Some controls offer convenience methods for the main properties of a control that are most likely to be bound by an application.

oTextField.bindValue("/company/name");

To remove a property binding, you can use the unbindProperty method. The property binding is removed automatically whenever a control is destroyed.

oTextField.unbindProperty("value");

For a complete list of supported parameters, see the API Reference.

Formatting Property Values

The values in the data are often represented in some internal format and need to be converted to an external format for visual representation. This is especially necessary for numbers, dates, and times with locale dependent external formats. SAPUI5 provides two different conversion options: Formatter functions allow one-way conversion only, while data types can also be used for two-way binding as they cannot only format, but also parse user input. You can choose freely for each binding, depending on your scenario.

The formatter function can either be passed as a third parameter to the bindProperty method, or contained in the binding info with the key "formatter". It has a single parameter value, which is the value which needs to be formatted to an external representation, and is executed as a member of the control, so can access additional control properties or model data.



oTextField.bindProperty("value", "/company/title", function(sValue) { return sValue && sValue.toUpperCase();});

oControl = new sap.ui.commons.TextField({ value: { path:"/company/revenue", formatter: function(fValue) { if (fValue) { return "> " + Math.floor(fValue/1000000) + "M"; } return "0"; } }}) The formatter function, as it can contain any JavaScript, can not only be used for formatting a value, but can also do type conversion or calculate results from a given value, for example to show a special traffic light image depending on a boolean value:oImage.bindProperty("src", "/company/trusted", function(bValue) { return bValue ? "green.png" : "red.png";});

Using Data Types

The type system provides the possibility to format and parse data, as well as validating if the entered data is within defined constraints. You can define a type to be used for a property binding, by passing it as a third parameter in bindProperty or by adding it to the binding information with the key "type".

oTextField.bindProperty("value", "/company/title", new sap.ui.model.type.String());

oControl = new sap.ui.commons.TextField({ value: { path:"/company/revenue", type: new sap.ui.model.type.Float({ minFractionDigits: 2, maxFractionDigits: 2 }) }}) You can define custom types by inheriting from sap.ui.model.SimpleType and implementing the three methods formatValue, parseValue and validateValue. formatValue will be called whenever the value in the model is changed to convert it to the type of the control property it is bound to and may throw a FormatException. parseValue is called, whenever the user modified a value in the UI and the change is transported back into the model. It may throw a ParseException in case the value cannot be converted. In case of successful parsing validateValue is called to check additional constraints, like minimum or maximum value, and throws a ValidateException in case constraints are violated.

sap.ui.model.SimpleType.extend("sap.test.PLZ", { formatValue: function(oValue) { return oValue; }, parseValue: function(oValue) { return oValue; }, validateValue: function(oValue) { if (!/^(\d{5})?$/.test(oValue)) { throw new sap.ui.model.ValidateException("PLZ must have 5 digits!");



} }});

For more information, see Using the Data Binding Type System.

Binding Mode

By default, all bindings of a model instance have the default binding mode of the model. You can change this behavior. When creating a PropertyBinding, you can specify a different binding mode, which is then used exclusively for this specific binding. Of course, a binding can only have a supported binding mode of the model.

var oModel = new sap.ui.model.json.JSONModel();// default binding mode is Two WayoModel.setData(myData);sap.ui.getCore().setModel(oModel);var oText = new sap.ui.commons.TextField();// bind value property one way only // propertyname, formatter function, binding modeoText.bindValue("/firstName", null, sap.ui.model.BindingMode.OneWay);oText.placeAt("target1");oText = new sap.ui.commons.TextField();// bind value property two way which is the defaultoText.bindValue("/firstName");oText.placeAt("target2");}

In the example above, two TextFields are created and their value property is bound to the same property in the model. The first TextField binding has a one-way binding mode, whereas the second TextField has the default binding mode of the model instance, which is two-way. So, when text is entered in the first TextField, the value will not be changed in the model. This happens only if text is entered in the second TextField. Then, of course, the value of the first TextField will be updated as it has a one-way binding, which means from model to view.

1.4.4.3.2 Aggregation Binding

You can define aggregation binding either in the settings object in the constructor or by calling the bindAggregation method. Aggregation binding requires the definition of a template, which is cloned for each bound entry of the list. For each clone that is created, the binding context is set to the respective list entry, so that all bindings of the template are resolved relative to the entry. The aggregated elements are destroyed and recreated whenever the bound list in the data model is changed.

Controls for the visualization of large data sets, for example Table or RowRepeater, only create clones for the currently visible entries and not for all list entries by using a custom updateAggregation method.

To bind an aggregation, you create a template or provide a factory function, which is then passed when defining the aggregation binding itself. In the settings object, this looks as follows:

var oItemTemplate = new sap.ui.core.ListItem({text:"{name}"});var oComboBox = new sap.ui.commons.ComboBox({ items: {



path: "/company/contacts", template: oItemTemplate }});

You can also define the aggregation binding by using the bindAggregation method of a control:

oComboBox.bindAggregation("items", "/company/contacts", new sap.ui.core.ListItem({text:"{name}"}));

Some controls have a typed binding method for aggregations that are likely to be bound by the application:

oComboBox.bindItems("/company/contacts", oItemTemplate);

To remove an aggregation binding, you can use the unbindProperty method. The aggregation binding is then removed automatically whenever a control is destroyed.

oComboBox.unbindAggregation("items");

For more information, see the API Reference.

Using Template Controls

For structured data with list entries with the same properties using template controls within the aggregation binding is recommended. A template is not necessarily a single control as in the examples above, but can be a tree of controls. For each list entry, a deep clone of the template is created and added to the bound aggregation.

var oMatrixLayout = new sap.ui.commons.layout.MatrixLayout();

var oRowTemplate = new sap.ui.commons.layout.MatrixLayoutRow({ cells: [ new sap.ui.commons.layout.MatrixLayoutCell({ content: new sap.ui.commons.Label({text:"Name:"}) }), new sap.ui.commons.layout.MatrixLayoutCell({ content: new sap.ui.commons.TextView({text:"{name}"}) }) ]});

oMatrixLayout.bindAggregation("rows", "/company/contacts", oRowTemplate);

Using Factory Functions

The factory function is a more powerful approach for creating controls from model data. The factory function is called for each list entry to create the controls necessary to represent the current entry. The developer can decide, whether it is the same control with different properties or even a completely different control for each entry.



The factory function gets the parameters sId. These parameters must be used as they identify the created control and the context object oContext, which allows accessing data from the list entry. It returns an instance of sap.ui.core.Element.

oContainer.bindAggregation("content", "/company/properties", function(sId, oContext) { var value = oContext.getProperty("value"); switch(typeof value) { case "string": return new sap.ui.commons.TextField(sId, { value: { path: "value", type: new sap.ui.model.type.String(); } }); case "number": return new sap.ui.commons.TextField(sId, { value: { path: "value", type: new sap.ui.model.type.Float(); } }); case "boolean": return new sap.ui.commons.CheckBox(sId, { checked: { path: "value" } }); }});

Initial Sorting and Filtering for Aggregation Binding

You can provide initial sorting and filtering when specifying the aggregation binding. Proceed as follows:

● Define a sorter and/or filters:

var oSorter = new sap.ui.model.Sorter("name", true); // sort descendingvar oFilter1 = new sap.ui.model.Filter("name", sap.ui.model.FilterOperator.StartsWith, "M");var oFilter2 = new sap.ui.model.Filter("name", sap.ui.model.FilterOperator.Contains, "Paz");var oFilter3 = new sap.ui.model.Filter("name", sap.ui.model.FilterOperator.BT, "A","G"); // name between A and G

● Hand the sorter and/or filters to the aggregation binding:

var oComboBox = new sap.ui.commons.ComboBox({ items: {path:"/company/contacts", template:oItemTemplate, sorter:oSorter, filters:[oFilter1,oFilter2,oFilter3]}});

You can also use the other aggregation binding possibilities (for example bindAggregation, bindItems) and provide the sorter and filters as parameters.



Manual Sorting and Filtering for Aggregation Binding

To sort/filter data manually after the aggregation binding is complete you can do so by getting the corresponding binding and calling the sort/filter function:

var oSorter = new sap.ui.model.Sorter("name", true); // sort descendingvar oFilter1 = new sap.ui.model.Filter("name", sap.ui.model.FilterOperator.StartsWith, "M");var oFilter2 = new sap.ui.model.Filter("name", sap.ui.model.FilterOperator.Contains, "Paz");var oFilter3 = new sap.ui.model.Filter("name", sap.ui.model.FilterOperator.BT, "A","G"); // name between A and G

// manual sortingoTable.getBinding("rows").sort(oSorter);

// manual filteringoTable.getBinding("rows").filter([oFilter1,oFilter2,oFilter3]);oComboBox.getBinding("items").filter([oFilter1,oFilter2,oFilter3]);

To get the binding of a control you have to know the name of the aggregation which is for example 'rows' for the table control.

For more information about the various sorting and filter methods and operators, see the documentation for Filter, Sorter, and Filter operations in the API Reference.

1.4.4.3.3 Element Binding

Binding an element allows to set the binding context of the element to the object referenced by the given binding path. Thus, all relative bindings within the control and all of its children are resolved relative to this object. For server-side models, the element binding triggers the request to the server to load the referenced object in case it is not yet available on the client.

Element bindings can also be defined relatively. In case of relative element bindings, the binding context is updated when the parent binding context is changed.

To define an element binding, use the bindElement method on a control:

oControl.bindElement("/company");oControl.bindProperty("value", "name");

Element binding is especially interesting for containers or layouts containing many controls that are all visualizing properties of the same model object.

var oMatrixLayout = new sap.ui.commons.layout.MatrixLayout();oMatrixLayout.bindElement("/company");oMatrixLayout.createRow( new sap.ui.commons.Label({text: "Name:"}), new sap.ui.commons.TextField({value: "{name}"}));

oMatrixLayout.createRow( new sap.ui.commons.Label({text: "Revenue:"}), new sap.ui.commons.TextField({value: "{revenue}"}));oMatrixLayout.createRow(



new sap.ui.commons.Label({text: "Employees:"}), new sap.ui.commons.TextField({value: "{employees}"}));

Setting a New Context for the Binding (Master Detail)

You create a new binding context for an element that is used to resolve bound properties or aggregations relative to the given path. You can use this method if the existing binding path changes or has not been provided before, for example in master detail scenarios.

Below is a simple example:

var data = {clients:[{firstName:"Donald", lastName:"Duck"}]};...// create and set model herevar oLabel = new sap.ui.commons.Label("myLabel");oLabel.bindProperty("text", "firstName");oLabel.bindElement("/clients/0");

The bindProperty method binds the text value of the label to the firstName property in the model. As the path to this property in the model is not set, this will not resolve. To resolve the binding, you use the bindElement method which creates a new context from the specified relative path.

To remove the current binding context, call the unbindElement method on the label. By this, all bindings now resolve relative to the parent context again.

You can also use the bindElement method in conjunction with aggregation binding:

var data = {clients:[ {firstName:"Donald", lastName:"Duck"}, items: [ {name: "iPhone"}, {name:"iPad"} ] } ]};...// create and set model herevar oLB = new sap.ui.commons.ListBox("myLb", {height:"100px"});var oItemTemplate = new sap.ui.core.ListItem(); oItemTemplate.bindProperty("text", "name");oLB.bindAggregation("items", "items", oItemTemplate);oLB.bindElement("/clients/0");

In this example, the ListBox is used to display the detailed data (items data) for a specified client. Another control can now be used to show the master data (client data) in the same way as in the first example with the label.

This example only works if the additional detailed data in the model which should be displayed in the ListBox (items in the example) is nested in the corresponding parent data (the client in the example). As you can see in the model, the items are contained in the client data.

You can also use a filtering function, for example in a table, to display detailed data for selected master data. In this case, nested data is not necessary in the model.



1.4.4.4 Using the Data Binding Type System

Data binding supports the definition of types which can be handed over when binding properties. These types define the data type for properties in the model. The values are then automatically formatted for display in the UI. In addition to this, the input values in UI controls are parsed and converted back to the defined type in the model. If an error occurs during formatting or parsing, the following exception occurs: sap.ui.model.FormatException / sap.ui.model.ParseException.

All types inherit from the abstract sap.ui.model.Type class. A subclass of this class is sap.ui.model.SimpleType. The currently available types inherit from SimpleType class.

You can generate the following parameters for each SimpleType in the constructor:

● format options: Format options define how a value is formatted and displayed in the UI.● constraints: Constraints are optional and define how an input value entered in the UI should look like.

During parsing the value is validated against these constraints. For example, a String type has a constraint for maxLength and minLength which are automatically validated when parsing the input values.

The following sections describe the available constraints and format options for each type.

1.4.4.4.1 Example: Using Data Types

The following example shows how to use data types:

A sap.ui.model.type.Float type is created with the formatting options minimum/maximum fraction digits equals 2 and a maximum value constraint of 10:

// creating of a float type with 2 format options and one constraintvar oFloat = new sap.ui.model.type.Float( { minFractionDigits: 2, maxFractionDigits: 2 }, { maximum: 10 });

To use the defined data type for the binding, proceed as follows:

// specify the binding and the type directly in the control constructorvar oText = new sap.ui.commons.TextField({value: {path: "/sliderValue", type: oFloat}});// or alternatively do it afterwardsoText.bindValue("/sliderValue", oFloat);

Input parsing and output formatting are now carried out automatically. If, for example, the float value in the model is 2.3345, the text field displays the value 2.33. A user enters a value which is validated after user entry. To be valid, the entered value must be lower than 10.



1.4.4.4.2 Handling Wrong User Input

You can register a handler to validate, parse, and format issues by using the following functions of sap.ui.getCore():

● attachFormatError● attachParseError● attachValidationError● attachValidationSuccess

1.4.4.4.3 Simple Types

The following sections introduce the simple types that are currently available for data binding in SAPUI5.

NoteUse the following data types only with data binding.

● sap.ui.model.type.Integer● sap.ui.model.type.Float● sap.ui.model.type.String● sap.ui.model.type.Boolean● sap.ui.model.type.Date● sap.ui.model.type.Time● sap.ui.model.type.DateTime

The types use the below listed formatter classes. The formatters can, however, also be used standalone for formats, such as dates.

NoteThe formatter classes do not provide validation.

List of formatter classes:

● sap.ui.core.format.DateFormat● sap.ui.core.format.NumberFormat

1.4.4.4.3.1 sap.ui.model.type.Integer

The Integer type represents an integer value. The source value (value given in the model) must be given as a number and is transformed into the type of the bound control property:

● float: Value is rounded using Math.floor



● integer: No transformation needed● string: Value is formatted or parsed according to the given output pattern

Examples how an Integer type can be initialized:

// The source value is given as Javascript number. Output is transformed into the type of the bound control property.// If this type is "string" (e.g. the value property of the TextField control) the used default output pattern parameters depend on locale and fixed settings.var oType = new sap.ui.model.type.Integer();

// The source value is given as Javascript number. Output is transformed into the type of the bound control property.// If this type is "string" (e.g. the value property of the TextField control) the given output pattern is used (parameters which are not specified are taken from the default pattern)

oType = new sap.ui.model.type.Integer({ minIntegerDigits: 1, // minimal number of non-fraction digits maxIntegerDigits: 99, // maximal number of non-fraction digits minFractionDigits: 0, // minimal number of fraction digits maxFractionDigits: 0, // maximal number of fraction digits groupingEnabled: false, // enable grouping (show the grouping separators) groupingSeparator: ",", // the used grouping separator decimalSeparator: "." // the used decimal separator});

The Integer type supports the following validation constraints:

● maximum● minimum

1.4.4.4.3.2 sap.ui.model.type.Float

The Float type represents a float value. The source value (value given in the model) must be given as a number and is transformed into the type of the bound control property:

● float: No transformation needed● integer: Value is rounded using Math.floor● string: Value is formatted or parsed according to the given output pattern

Examples how a Float type can be initialized:

// The source value is given as Javascript number. Output is transformed into the type of the bound control property.// If this type is "string" (e.g. the value property of the TextField control) the used default output pattern parameters depend on locale and fixed settings.

var oType = new sap.ui.model.type.Float();

// The source value is given as Javascript number. Output is transformed into the type of the bound control property.// If this type is "string" (e.g. the value property of the TextField control) the given output pattern is used (parameters which are not specified are taken from the default pattern)

oType = new sap.ui.model.type.Float({ minIntegerDigits: 1, // minimal number of non-fraction digits maxIntegerDigits: 99, // maximal number of non-fraction digits



minFractionDigits: 0, // minimal number of fraction digits maxFractionDigits: 99, // maximal number of fraction digits groupingEnabled: true, // enable grouping (show the grouping separators) groupingSeparator: ",", // the used grouping separator decimalSeparator: "." // the used decimal separator});

The Float type supports the following validation constraints:

● maximum● minimum

1.4.4.4.3.3 sap.ui.model.type.String

The String type represents a string. The source value (value given in the model) must be given as a number and is transformed into the type of the bound control property:

● string: No transformation needed● integer/float: String is parsed accordingly● boolean: "true" or "X" are interpreted as true, false, and " " as false

The string type does not have any format options.

Example how a String type can be initialized:

// The source value is given as string. The length of the string must not greater than 5.var oType = new sap.ui.model.type.String(null, {maxLength: 5});

The String type supports the following validation constraints:

● maxLength (expects an integer number)● minLength (expects an integer number)● startsWith (expects a string)● startsWithIgnoreCase (expects a string)● endsWith (expects a string)● endsWithIgnoreCase (expects a string)● contains (expects a string)● equals (expects a string)● search (expects a regular expression)

1.4.4.4.3.4 sap.ui.model.type.Boolean

The Boolean type represents a string. The source value (value given in the model) must be given as boolean and is transformed into the type of the bound control property:

● boolean: No transformation needed● string: "true" or "X" are interpreted as true, "false" and "" as false

The Boolean type has no format or validation constraint options.



Example how a Boolean type can be initialized:

// The source value is given as boolean.var oType = new sap.ui.model.type.Boolean();

1.4.4.4.3.5 sap.ui.model.type.Date

The Date type represents a date (without time). It transforms a source value (given value in the model) into a formatted date string and the other way round.

The format patterns must be defined in LDML Date Format notation. For the output, the use of a style ("short, "medium", "long" or "full") instead of a pattern is preferred, as it will automatically use a locale-dependent date pattern.

Examples how a Date type can be initialized:

// The source value is given as Javascript Date object. The used output pattern depends on the locale settings (default).var oType = new sap.ui.model.type.Date();// The source value is given as Javascript Date object. The used output pattern is "yy-MM-dd": e.g. 09-11-27oType = new sap.ui.model.type.Date({pattern: "yy-MM-dd"}); // The source value is given as string in "yyyy/MM/dd" format. The used output style is "long". The styles are language dependent.// The following styles are possible: short, medium (default), long, full// This usecase might be the common one.oType = new sap.ui.model.type.Date({source: {pattern: "yyyy/MM/dd"}, style: "long"}); // The source value is given as string in "yyyy/MM/dd" format. The used output pattern is "EEEE, MMMM d, yyyy": e.g. Saturday, August 22, 2043oType = new sap.ui.model.type.Date({source: {pattern: "yyyy/MM/dd"}, pattern: "EEEE, MMMM d, yyyy"}); // The source value is given as timestamp. The used output pattern is "dd.MM.yyyy": e.g. 22.12.2010oType = new sap.ui.model.type.Date({source: {pattern: "timestamp"}, pattern: "dd.MM.yyyy"}); // The source value is given as string. The used input pattern depends on the locale settings (default). The used output pattern is "dd '|' MM '|' yyyy": e.g. 22 | 12 | 2010oType = new sap.ui.model.type.Date({source: {}, pattern: "dd.MM.yyyy"});

The Date type supports the following validation constraints:

● maximum (expects an date presented in the source-pattern format)● minimum (expects an date presented in the source-pattern format)

1.4.4.4.3.6 sap.ui.model.type.Time

The Time type represents a time (without date). It transforms a source value (given value in the model) into a formatted time string and the other way round.

The format patterns must be defined in LDML Date Format notation. For the output, the use of a style ("short, "medium", "long" or "full") instead of a pattern is preferred, as it will automatically use a locale dependent time pattern.



Examples how a Time type can be initialized:

// The source value is given as Javascript Date object. The used output pattern depends on the locale settings (default).var oType = new sap.ui.model.type.Time();// The source value is given as Javascript Date object. The used output pattern is "hh-mm-ss": e.g. 09-11-27oType = new sap.ui.model.type.Time({pattern: "hh-mm-ss"}); // The source value is given as string in "hh-mm-ss" format. The used output style is "short". The styles are language dependent.// The following styles are possible: short, medium (default), long, full// This usecase might be the common one.oType = new sap.ui.model.type.Date({source: {pattern: "hh-mm-ss"}, style: "short"}); // The source value is given as string in "hh/mm/ss/SSS" format. The used output pattern is "HH:mm:ss '+' SSS 'ms'": e.g. 18:48:48 + 374 msoType = new sap.ui.model.type.Time({source: {pattern: "hh/mm/ss/SSS"}, pattern: "HH:mm:ss '+' SSS 'ms'"}); // The source value is given as timestamp. The used output pattern is "HH 'Hours' mm 'Minutes'": e.g. 18 Hours 48 MinutesoType = new sap.ui.model.type.Time({source: {pattern: "timestamp"}, pattern: "HH 'Hours' mm 'Minutes'"}); // The source value is given as string. The used input pattern depends on the locale settings (default). The used output pattern is "hh:mm a": e.g. 06:48 PMoType = new sap.ui.model.type.Time({source: {}, pattern: "hh:mm a"});

The Time type supports the following validation constraints:

● maximum (expects an time presented in the source-pattern format)● minimum (expects an time presented in the source-pattern format)

1.4.4.4.3.7 sap.ui.model.type.DateTime

The DateTime type represents an exact point of time (date and time). It transforms a source value (given value in the model) into a formatted date+time string and the other way round.

The format patterns must be defined in LDML Date Format notation. For the output, the use of a style ("short, "medium", "long" or "full") instead of a pattern is preferred, as it will automatically use a locale-dependent date and time pattern.

CautionWhen talking about exact points in time, time zones are imported. The formatted output of the DateTime type currently shows the "local" time which equals the time settings of the machine on which the browser runs. If the source value is given as a Javascript Date object or as a timestamp, the exact moment is sufficiently defined. For string source values this value is interpreted in "local" time if it does not explicitly have a time zone. Currently, all accepted time zone notations must be based on GMT/UTC.

Examples how a DateTime type can be initialized:

// The source value is given as Javascript Date object. The used output pattern depends on the locale settings (default).var oType = new sap.ui.model.type.DateTime();// The source value is given as Javascript Date object. The used output pattern is "yyyy/MM/dd HH:mm:ss": e.g. 2011/04/11 09:11:27oType = new sap.ui.model.type.DateTime({pattern: "yyyy/MM/dd HH:mm:ss"}); // The source value is given as string in "yyyy/MM/dd HH:mm:ss" format. The used



output style is "full". The styles are language dependent.// The following styles are possible: short, medium (default), long, full// This usecase might be the common one.oType = new sap.ui.model.type.Date({source: {pattern: "yyyy/MM/dd HH:mm:ss"}, style: "full"}); // The source value is given as string in "dd.MM.yyyy HH:mm:ss" format (no timezone given). The used output pattern is "MMMM d, yyyy, HH:mm:ss.SSS": e.g. August 22, 2043, 18:48:48.374oType = new sap.ui.model.type.DateTime({source: {pattern: "dd.MM.yyyy HH:mm:ss"}, pattern: "MMMM d, yyyy, HH:mm:ss.SSS"});// The source value is given as timestamp. The used output pattern is "dd.MM.yyyy HH:mm": e.g. 22.12.2010 13:15oType = new sap.ui.model.type.DateTime({source: {pattern: "timestamp"}, pattern: "dd.MMM.yyyy HH:mm"}); // The source value is given as string. The used input pattern depends on the locale settings (default). The used output pattern is "hh-mm-ss '/' yy-MM-dd": e.g. 06-48-48 / 43-08-22oType = new sap.ui.model.type.DateTime({source: {}, pattern: "hh-mm-ss '/' yy-MM-dd"}); // The source value is given as string in "dd.MM.yyyy HH:mm:ss X" format (timezone is defined in ISO8601 format, e.g. "+02:00"). The used output pattern depends on the locale settings (default).oType = new sap.ui.model.type.DateTime({source: {pattern: "dd.MM.yyyy HH:mm:ss X"}});// The source value is given as string in "dd.MM.yyyy HH:mm:ss Z" format (timezone is defined in RFC822 format, e.g. "+0200"). The used output pattern depends on the locale settings (default).oType = new sap.ui.model.type.DateTime({source: {pattern: "dd.MM.yyyy HH:mm:ss Z"}});// The source value is given as string in "dd.MM.yyyy HH:mm:ss z" format (timezone is currently defined as e.g. "GMT+02:00", "UTC+02:00", "UT+02:00" or "Z" (shortcut for "UTC+00:00")).// The used output pattern depends on the locale settings (default).oType = new sap.ui.model.type.DateTime({source: {pattern: "dd.MM.yyyy HH:mm:ss z"}});

The DateTime type supports the following validation constraints:

● maximum (expects an dateTime presented in the source-pattern format)● minimum (expects an dateTime presented in the source-pattern format)

1.4.4.4.4 Data Types for Use Without Data Binding

The simple types in the previous sections are not intended to be used without data binding. But they use formatter classes, which can also be used standalone to format, for example, dates. The formatter classes do not provide validation.

You can use the following formatter classes:

● sap.ui.core.format.DateFormat● sap.ui.core.format.NumberFormat

1.4.4.4.4.1 sap.ui.core.format.DateFormat

The DateFormat class can be used to parse a string representing a date, time or datetime into a JavaScript date object and vice versa (also known as format).



The format pattern must be defined in LDML date format notation. The following options are available:

● style: Can be "short", "medium", "long" or "full" and will use a locale dependent pattern● pattern: A date pattern in LDML Date Format notation

In case both, style and pattern, are defined, the pattern is used and the style ignored.

Example how the DateFormat class can be used:

jQuery.sap.require("sap.ui.core.format.DateFormat");var oDateFormat = sap.ui.core.format.DateFormat.getDateTimeInstance({pattern: "dd/MM/yyyy HH:mm"}); //Returns a DateFormat instance for date and time//var oDateFormat = sap.ui.core.format.DateFormat.getInstance({pattern: "dd/MM/yyyy"}); //Returns a DateFormat instance for date//var oDateFormat = sap.ui.core.format.DateFormat.getTimeInstance({pattern: "HH:mm"}); //Returns a DateFormat instance for time

var oField = new sap.ui.commons.TextField();oField.setValue(oDateFormat.format(oDate)); // Set the formatted value on the text fieldoField.attachChange(function(){

//Parse the user input oDate = oDateFormat.parse(oField.getValue());});

1.4.4.4.4.2 sap.ui.core.format.NumberFormat

The NumberFormat class can be used to parse a string representing a number (float or integer) into a Javascript number and vice versa (also known as format). The following format options are possible. For parameters which are not specified default values according to the type are used:

● minIntegerDigits: minimal number of non-fraction digits● maxIntegerDigits: maximal number of non-fraction digits● minFractionDigits: minimal number of fraction digits● maxFractionDigits: maximal number of fraction digits● groupingEnabled: enable grouping (show the grouping separators)● groupingSeparator: used grouping separator● decimalSeparator: used decimal separator

Example how the NumberFormat class can be used:

var fValue = 20001000.563; jQuery.sap.require("sap.ui.core.format.NumberFormat");var oNumberFormat = sap.ui.core.format.NumberFormat.getFloatInstance({ maxFractionDigits: 2, groupingEnabled: true, groupingSeparator: ",", decimalSeparator: "."}); //Returns a NumberFormat instance for float/*var oNumberFormat = sap.ui.core.format.NumberFormat.getIntegerInstance({ maxFractionDigits: 0, groupingEnabled: false}); //Returns a NumberFormat instance for integer*/

var oField = new sap.ui.commons.TextField();



oField.setValue(oNumberFormat.format(fValue)); // Set the formatted value on the text fieldoField.attachChange(function(){ //Parse the user input fValue = oNumberFormat.parse(oField.getValue()); alert(fValue);});

1.4.4.5 Calculated Fields for Data Binding

The calculated fields feature enables the binding of multiple properties in different models to a single property of a control. For example, the value property of a text field may be bound to a property firstName and a property lastName in a model. The application can access these values in a formatter function and can decide how they should be processed or combined together. If no formatter function is specified, the values are joined together by default. You can use the useRawValues property to specify if the parameter values in the formatter function are formatted according to the type of the property or not.

The multiple property bindings are stored in a CompositeBinding and can be accessed by calling the getBindings function. You can access the composite binding, for example, by using the getBinding('value') function of the control. The composite binding has no path, model, context, and type because it contains multiple property bindings containing the necessary information. A composite binding may, for example, store two property bindings which belong to different models and have different types.

If you have specified a formatter function, it is also available in the composite binding.

NoteCurrently, calculated fields work only from model to view, read only, and the values can be accessed via a formatter function.

There are several options to create multiple bindings for a control. The syntax is very similar to the normal single binding declaration.

Each binding is created by the specified parts and assigned information. A part must contain the path to the property in the model and may contain additional information for the binding, for example a type. If multiple parts exist, the binding mode is automatically set to one-way binding.

Constructor Declaration

1. Use binding objects to add additional parameters, for example the type:

oTxt = new sap.ui.commons.TextField({ value: { parts: [ {path: "/firstName", type: new sap.ui.model.type.String()}, {path: "/lastName"}, {path: "myModel2>/amount", type: new sap.ui.model.type.Float()} // path to property in another model ]



}});

2. Use strings which only take the path:

oTxt = new sap.ui.commons.TextField({ value: { parts: [ "/firstName", "/lastName", "myModel2>/fraud" // path to property in another model ] }});

Bind Property Declaration

1. Use binding objects to add additional parameters, for example the type:

oTxt.bindValue({ parts: [ {path: "/firstName", type: new sap.ui.model.type.String()}, {path: "/lastName"} ]});

2. Use strings which only take the path:

oTxt.bindValue({ parts: [ "/firstName", "/lastName" ]});

These samples also work with a relative binding path, when you use them as a template in an aggregation binding.

1.4.4.5.1 Custom Formatter Functions

The examples for constructor declaration and bind property declaration (see Calculated Fields for Data Binding) do not contain a formatter function. In this case, all values of the various parts are joined together as a string with a space seperator. To specify your own formatter, proceed as shown in the following example:

oTxt.bindValue({ parts: [ {path: "/firstName", type: new sap.ui.model.type.String()}, {path: "/lastName", type: new sap.ui.model.type.String()}, {path: "/amount", type: new sap.ui.model.type.Float()}, {path: "/currency", type: new sap.ui.model.type.String()} ], formatter: function(firstName, lastName, amount, currency){ // all parameters are strings if (firstName && lastName) { return "Dear " + firstName + " " + lastName + ". Your current balance is: " + amount + " " + currency;



} else { return null; } }});

The values provided in the parameters of the formatter function are already formatted to the output type of the control, which is a string in this case (that is, the value property of text field is a string).

Custom Formatter Function with Raw Values

If you do not want the provided values in the formatter function being already formatted according to their type, you can set a flag to get the raw unformatted values. These values are also stored in the model. In this case, the types of the parts are ignored:

oTxt.bindValue({ parts: [ {path: "/firstName", type: new sap.ui.model.type.String()}, {path: "/lastName", type: new sap.ui.model.type.String()}, {path: "/amount", type: new sap.ui.model.type.Float()}, {path: "/model2>debts", type: new sap.ui.model.type.Float()} ], formatter: function(firstName, lastName, amount, debt){ // string, string, float, float if (firstName && lastName) { return "Dear " + firstName + " " + lastName + ". Your current balance is: " + (amount - debts); } else { return null; } }, useRawValues : true});

1.4.5 Implementing Views

This section provides information on how to implement functions depending on the view type.

Related Information

Namespaces in XML Views [page 126]

Aggregation Handling in XML Views [page 126]

Using Native HTML in XML Views [page 127]The use of native HTML depends on the XHTML feature set.

Using CSS Style Sheets in XML Views [page 128]



You include style sheets like plain HTML. You can add further CSS classes to SAPUI5 controls by using the class attribute.

Handling Events in XML Views [page 129]Event handlers are used as attributes. The attribute name is the event name, such as "press" for a button, and the attribute value as event handler name. The event handler must be defined as a function in the view's controller.

Handling Events in JSON Views [page 129]Event handlers are used as attributes with the attribute name as event name like "press" for a button and the attribute value as event handler name. The event handler must be defined as a function in the view's controller.

Instantiating Views [page 129]You use the factory method sap.ui.view to instantiate views.

1.4.5.1 Namespaces in XML Views

Analogous to generic XML mapping features, the names of SAPUI5 control libraries are mapped to XML namespaces. You can choose any of the required namespaces as default and, thus, the respective control tags do not need a prefix.

The <View> tag is required and in the example above, the core namespace is defined in the first line. Of course you can define any name. To keep the tag names shorter, for example, you can also use "c" instead of "core".

NoteIf controls are located in a subpackage of a control library, for example sap.ui.commons.layout.MatrixLayout, they must have their own XML namespace:

<core:View controllerName="sap.hcm.Address" xmlns="sap.ui.commons" xmlns:core="sap.ui.core" xmlns:layout="sap.ui.commons.layout"> <layout:MatrixLayout> ...

1.4.5.2 Aggregation Handling in XML Views

You can simply add child controls as child tags, as shown in the example above where a <Button> tag is added to a <Panel> tag.

Some controls have more than one content area, for example the shell control that has the main content area, a pane bar, a headerItems aggregation, worksetItems, and so on. Hence, an aggregation tag usually serves as direct child of a container and contains children. It is only possible to directly add children as shown in the example above if the container control has marked one of the child aggregations as default.

Some containers may not have default content, for example, the splitter container has two equally important content areas.



NoteThe framework supports you by issuing error message in case of errors in the aggregation handling in XML views.

You fill aggregations as shown in the following example.

NoteThe namespace of the parent control tag and the aggregation tag must be the same.

<core:View controllerName="sap.hcm.Address" xmlns="sap.ui.commons" xmlns:core="sap.ui.core"> <Panel> <content>  <Image src="http://www.sap.com/global/ui/images/global/sap-logo.png"/> <Button text="Press Me"/> </content> </Panel><core:View>

1.4.5.3 Using Native HTML in XML Views

The use of native HTML depends on the XHTML feature set.

Context

When mixing XHTML and SAPUI5 controls, observe the following rules:

● XHTML elements can be used instead of the SAPUI5 type control, for example, in the root of an XML view or in the content aggregation of a layout container.

● When embedding XHTML in an aggregation of a SAPUI5 control, the XHTML must not consist of a single text node. The topmost node of an embedded XHTML tree must be an XHTML element. Embedding pure text into an aggregation is not supported.

● The XHTML nodes are converted 1:1 to HTML, the XMLView does not deal with any differences between XHTML and HTML (for example rewriting and auto-closing tags)

● The created HTML DOM nodes are preserved during re-rendering of an XML view: Modifications to the DOM are not lost.

NoteAs an alternative to embedding XHTML, you can use the sap.ui.core.HTML control. As this requires content encoding it is, however, less convenient.

Procedure

To mix SAPUI5 controls with native XHTML, you only need the XHTML namespace to use (X)HTML:

<core:View controllerName="sap.hcm.Address" xmlns="sap.ui.commons" xmlns:core="sap.ui.core" xmlns:html="http://www.w3.org/1999/xhtml"> <Panel> <Button text="Press Me. I am a SAPUI5 Button"/> <html:button>No, press me. I am native HTML Button.</html:button> </Panel><core:View>

1.4.5.4 Using CSS Style Sheets in XML Views

You include style sheets like plain HTML. You can add further CSS classes to SAPUI5 controls by using the class attribute.

Context

The effect is the same as calling myButton.addStyleClass(...).

TipWe recommend to carefully choose the elements that you style as the CSS always affects the whole page and is not restricted to the view.

Procedure

To add a style sheet, add the style definition.To add a style class and define a button that uses it, add the following coding:

<core:View controllerName="sap.hcm.Address" xmlns="sap.ui.commons" xmlns:core="sap.ui.core" xmlns:html="http://www.w3.org/1999/xhtml"> <html:style> .mySuperRedButton { color: red; } </html:style> <Panel> <Button class="mySuperRedButton" text="Press Me"/> </Panel><core:View>



1.4.5.5 Handling Events in XML Views

Event handlers are used as attributes. The attribute name is the event name, such as "press" for a button, and the attribute value as event handler name. The event handler must be defined as a function in the view's controller.

Procedure

To attach en event handler in a XML view, insert the following declaration: ... <Button text="Press Me" press="doSomething"/> ...The method controller.doSomething() is executed when the button is pressed.

1.4.5.6 Handling Events in JSON Views

Event handlers are used as attributes with the attribute name as event name like "press" for a button and the attribute value as event handler name. The event handler must be defined as a function in the view's controller.

Procedure

The following declaration causes controller.doSomething() to be executed when the button is pressed:

... { "Type":"sap.ui.commons.Button", "id":"MyButton", "text":"Press Me", "press":"doSomething" }...

1.4.5.7 Instantiating Views

You use the factory method sap.ui.view to instantiate views.

Procedure

To pass required information for the instantiation, use an object with the following properties:a) type: The type can be JSON, JS, XML or HTML. All possible types are declared in the enumeration

sap.ui.core.mvc.ViewType.



b) viewName: View name corresponding to the module conceptc) viewContent: Only relevant for XML views and JSON views. Defines the XML or JSON string

representation of the view definition. If viewName and viewContent are given, the viewName property is used to load the view definition.

d) Controller: Any controller instance; the given controller instance overrides the controller defined in the view definition

e) viewData: Only used for JS views; this property contains user-specific data that is available during the whole lifecycle of the view and the controller

... var myController = sap.ui.controller("my.own.controller"); var myView = sap.ui.view({ type: sap.ui.core.mvc.ViewType.XML, viewName: "my.own.view", controller: myController });...

All regular properties of a view (control) can be passed to the object as usual.

1.4.6 Custom Data - Attaching Data Objects to Controls

To attach data to SAPUI5 controls, the method data() has been added to the base class sap.ui.core.Element. You can use the method to set and get data. The API is equivalent to jQuery.data().

You can also use the following other possibilities to attach data to SAPUI5 controls:

● Attaching data declaratively in XML views and JSON views● Using data binding● For strings only: Writing data to the HTML DOM as "data-*" attribute.

Setting and Retrieving Data

To set and retrieve data, use the following code:

myButton.data("myData", "Hello"); // attach some data to the Button

alert(myButton.data("myData"); // alerts "Hello"

var dataObject = myButton.data(); // a JS object containing ALL dataalert(dataObject.myData); // alerts "Hello"

Binding Data: Use in a List Binding

For list bindings, use the following code:

// create a JSONModel, fill in the data and bind the ListBox to this model



You can use data binding with the following notation:

#!xml

<core:View xmlns:core="sap.ui.core" xmlns:mvc="sap.ui.core.mvc" xmlns="sap.ui.commons" controllerName="my.own.controller" xmlns:app="http://schemas.sap.com/sapui5/extension/sap.ui.core.CustomData/1"> <Button id="myBtn" text="Click to show stored coordinates data" app:coords="{data}" press="alertCoordinates"></Button></core:View>

Use in JSON Views

To add custom data to an element in a JSON view, add the following code to the element properties (these examples include data binding):

customData: { Type:"sap.ui.core.CustomData", key:"coords", value:"{data}" // bind custom data }

To add multiple data elements, use an array:

customData: [{ Type:"sap.ui.core.CustomData", key:"coords", value:"{data}" // bind custom data }, { Type:"sap.ui.core.CustomData", key:"coords", value:"{data}" // bind custom data }]

In context, this looks as follows:

var json = { Type: "sap.ui.core.JSONView", controllerName:"my.own.controller", content: [{ Type:"sap.ui.commons.Panel", content:[{ Type:"sap.ui.commons.Button", text:"{actionName}", press: "doSomething", customData: { Type:"sap.ui.core.CustomData", key:"coords", value:"{data}" // bind custom data } }] }] };



1.4.6.1 Writing Data to the HTML DOM as DATA-* Attribute

It can be useful to write the custom data to the HTML DOM, for example to generate markers in the HTML from data binding which then can be used for data-dependent styling, or to create stable anchors in the HTML which can be used for automated tests.

A "data-" prefix is added to the key and the result is then written as attribute into the root HTML element of the control. The CustomData value is written as attribute value.

This only works when the key is a valid HTML ID and the value is a string (otherwise an error is logged). Note that HTML attribute names are case-insensitive and browsers may convert the key to lowercase.

NoteDo not write too much data into DOM.

In JavaScript the flag can be set like this:

myButton.data("mydata", "Hello", true); // attach some data to the Button and mark it as "write to HTML"

In XMLViews the aggregation has currently to be written in expanded notation to set the writeToDom flag:

<Button ... > <customData> <core:CustomData key="mydata" value="Hello" writeToDom="true" /> </customData></Button>

Resulting HTML:

<button ... data-myData="Hello" ... >

Now CSS can use attribute selectors to check presence or the value of the custom data attribute:

button[data-mydata="Hello"] { border: 3px solid red !important; }

1.4.7 Declarative Support

The SAPUI5 library can be extended to support declarative programming which allows you to define the UI within the HTML document as elements. For this, a plugin (sap.ui.core.plugin.DeclarativeSupport) can be included either as required or marked as a module in the initial bootstrap script tag. The plugin parses the document and converts its tags with special attributes into SAPUI5 controls.

Declarative support is aware of properties, associations, events, and aggregations in a SAPUI5 control manner. This means that you can specify them within the markup of the HTML document either as data attributes or as child elements.

The following sections provide an overview of the declarative support and introduce the use of declarative support in SAPUI5.



Example

The following example shows the concept by combining a sap.ui.commons.TextField with a sap.ui.commons.Button control. When you click the button, the value of the text field is displayed in an alert box:

<!Doctype HTML><html> <title>Declarative Programming for SAPUI5 - sample01</title>

<script id="sap-ui-bootstrap" type="text/javascript" src="http://veui5infra.dhcp.wdf.sap.corp:8080/sapui5/resources/sap-ui-core.js" data-sap-ui-theme="sap_platinum" data-sap-ui-libs="sap.ui.commons" data-sap-ui-modules="sap.ui.core.plugin.DeclarativeSupport" > </script>

</head><body class="sapUiBody">

<div data-sap-ui-type="sap.ui.commons.TextField" id="message" class="my-button" data-value="Hello World"></div> <div data-sap-ui-type="sap.ui.commons.Button" data-text="Click me!" data-press="handlePress"></div>

</body></html>

Summary: Attributes Used by Declarative Support

The table summarizes the attributes used by declarative support and gives examples.

Attribute Description Example

data-sap-ui-type Type of control <div data-sap-ui-type="sap.ui.commons.Button"></div>

data-sap-ui-aggregation Defines the aggregation that shall be used for the element or child element

<div data-sap-ui-type="sap.ui.commons.Panel"><div data-sap-ui-aggregation="title" data-sap-ui-type="sap.ui.commons.Title" data-text="My Panel"></div></div>

data-sap-ui.default-aggregation

Sets or overrides the default aggregation of a control

<div data-sap-ui-type="sap.ui.commons.Panel" data-sap-ui-default-aggregation="title"><div data-sap-ui-type="sap.ui.commons.Title"



Attribute Description Example

data-text="My Panel"></div></div>

id Defines the ID property of a control <div data-sap-ui-type="sap.ui.commons.Button" id="myButton"></div>

class Adds a style class to the control <div data-sap-ui-type="sap.ui.commons.Button" class="myButton"></div>

1.4.7.1 Enabling Declarative Support

To use declarative support you need to enable the declarative support in your HTML document by adding an attribute to the SAPUI5 bootstrap script tag. This is done as follows:

data-sap-ui-modules="sap.ui.core.plugin.DeclarativeSupport"

SAPUI5 then requires (loads) the plugin sap.ui.core.plugin.DeclarativeSupport. When started, the plugin parses and enhances special HTML tags in the HTML document. The complete bootstrap script tag for SAPUI5 (based on a CDN version) looks as follows:

<script id="sap-ui-bootstrap" type="text/javascript" src="http://veui5infra.dhcp.wdf.sap.corp:8080/sapui5/resources/sap-ui-core.js" data-sap-ui-theme="sap_platinum" data-sap-ui-libs="sap.ui.commons" data-sap-ui-modules="sap.ui.core.plugin.DeclarativeSupport" ></script>

1.4.7.2 Defining Controls

After you have enabled the declarative support, define controls in your HTML document as HTML tags with the following data attribute:

data-sap-ui-type="sap.ui.commons.Button"

This data attribute defines the SAPUI5 control that should be rendered in the HTML tag by using the HTML tag as its UI area. Rendering a button in the body of an HTML document without setting any property, association, event, or aggregation looks as follows:

<body> <div data-sap-ui-type="sap.ui.commons.Button"></div></body>



NoteMake sure that you close the tags properly. HTML5 does not support self-closing tags.

NoteAll attributes used to define properties, associations, events, or aggregations are data attributes except for attributes that exist in HTML, for example id or class. Data attributes are prefixed with data-*, for example data-text.

1.4.7.3 Declarative Support: Properties

To set a property, for example for a button, you define the property as a data attribute of the corresponding HTML tag. To add text to the button, add the attribute data-text to its HTML tag:

<div data-sap-ui-type="sap.ui.commons.Button" data-text="HelloWorld"></div>

NoteTo define a property with upper case characters, you have to "escape" them with a dash character, similar to CSS attributes. The following code gives an example:

<div data-sap-ui-type="sap.ui.commons.ApplicationHeader" data-display-logoff="false" data-display-welcome="false"></div>

As the name of the attributes of HTML tags are case-insensitive, the properties displayLogoff and displayWelcome of the ApplicationHeader control have to be "escaped" as data-display-logoff and data-display-welcome for the name of the attributes of the HTML tag. Keep this in mind when matching properties, associations ,or events as an attribute of the HTML tag.

The id attribute defines the ID of a control:

<div data-sap-ui-type="sap.ui.commons.Button" id="myButton"></div>

To add a CSS class to the control, use the class attribute:

<div data-sap-ui-type="sap.ui.commons.Button" class="my-button"></div>

1.4.7.4 Declarative Support: Associations

An association is defined as a data attribute of the HTML tag. Instead of passing the reference to another control you define the ID of another control. The following code gives an example:

<div data-sap-ui-type="sap.ui.commons.Label" data-text="Message:" data-label-for="message"></div><div data-sap-ui-type="sap.ui.commons.TextField" id="message"></div>



The code snippet defines the link between Label and TextField by using the ID of TextField as a value for the data-label-for attribute of the Label.

1.4.7.5 Declarative Support: Events

The value of the event data attribute contains the name of a JavaScript function which will be used as callback once the event has been triggered. The following code snippet gives an example how a change of TextField results in an alert with its new value when the focus is lost:

<script> function handleChange (oEvent) { alert (oEvent.getSource().getValue()); }</script>

<div data-sap-ui-type="sap.ui.commons.TextField" data-value="Change me!" data-change="handleChange"></div>

Currently, SAPUI5 only supports to specify the name of a callback function. You can define callback functions within any class, see the following code example:

<div data-sap-ui-type="sap.ui.commons.TextField" data-value="Change me!" data-change= "my.company.MyClass.handleChange"></div>

1.4.7.6 Declarative Support: Aggregations

Agrregation support is required to allow nested controls for layout containers and/or add elements to a control, for example, for ComboBox.

SAPUI5 uses the control's default aggregation as default. If, for example, the panel control has the default aggregation content, all child elements of the data-sap-ui-type="sap.ui.commons.Panel" element are added to this aggregation:

<div data-sap-ui-type="sap.ui.commons.Panel"> <div data-sap-ui-type="sap.ui.commons.Button" data-text="My Button 1"></div> <div data-sap-ui-type="sap.ui.commons.Button" data-text="My Button 2"></div> <div data-sap-ui-type="sap.ui.commons.Button" data-text="My Button 3"></div> <div data-sap-ui-type="sap.ui.commons.Button" data-text="My Button 4"></div></div>

The markup in the example above generates an instance of the sap.ui.commons.Panel control and adds implicit four buttons to the default aggregation content of the control.

You can also explicitly declare an aggregation. In general, an explicit aggregation is expressed with a meta HTML tag between the parent controls HTML tag and the HTML tags of the children. The following code adds four buttons explicitly to the "content" aggregation of the declared panel:

<div data-sap-ui-type="sap.ui.commons.Panel"> <div data-sap-ui-aggregation="content"> <div data-sap-ui-type="sap.ui.commons.Button" data-text="My Button 1"></div> <div data-sap-ui-type="sap.ui.commons.Button" data-text="My Button 2"></div> <div data-sap-ui-type="sap.ui.commons.Button" data-text="My Button 3"></div>



<div data-sap-ui-type="sap.ui.commons.Button" data-text="My Button 4"></div> </div></div>

For aggregations with the cardinality "0..1" the "data-sap-ui-aggregation" attribute can be written directly to the control tag:

<div data-sap-ui-type="sap.ui.commons.Panel"> <div data-sap-ui-aggregation="title" div data-sap-ui-type="sap.ui.commons.Title" data-text="My Panel"></div></div>

The default aggregation of the declarative support is usually also the default aggregation of the control as defined in the control's meta information. However, when no default aggregation is set or another aggregation should be used as a default, for example to avoid unnecessary meta tags, it can be useful to define a so-called default aggregration attribute on the parent controls HTML tag. This is done as follows:

data-sap-ui-default-aggregation="title"

With this, all children which are not included in the data-sap-ui-aggregation meta tag are added to the default aggregation. This is shown in the following example:

<div data-sap-ui-type="sap.ui.commons.Panel" data-sap-ui-default-aggregation="title"> <div data-sap-ui-type="sap.ui.commons.Title" text="My Panel"></div> <div data-sap-ui-default-aggregation="content"> <div data-sap-ui-type="sap.ui.commons.Button" data-text="My Button 1"></div> <div data-sap-ui-type="sap.ui.commons.Button" data-text="My Button 2"></div> </div>/div>

You can now apply this to the MatrixLayout as follows:

<div data-sap-ui-type="sap.ui.commons.layout.MatrixLayout" data-layout-fixed="false> <div data-sap-ui-type="sap.ui.commons.layout.MatrixLayoutRow"> <div data-sap-ui-type="sap.ui.commons.layout.MatrixLayoutCell"> <div data-sap-ui-type="sap.ui.commons.TextField" data-value="Hello World"></div> </div> <div data-sap-ui-type="sap.ui.commons.layout.MatrixLayoutCell"> <div data-sap-ui-type="sap.ui.commons.Button" data-text="Hello World"></div> </div> </div></div>

Or you can add ListItems to a ComboBox:

<div data-sap-ui-type="sap.ui.commons.ComboBox" data-value="Item 1"> <div data-sap-ui-type="sap.ui.core.ListItem" data-text="Item 1"></div> <div data-sap-ui-type="sap.ui.core.ListItem" data-text="Item 2"></div> <div data-sap-ui-type="sap.ui.core.ListItem" data-text="Item 3"></div> <div data-sap-ui-type="sap.ui.core.ListItem" data-text="Item 4"></div> <div data-sap-ui-type="sap.ui.core.ListItem" data-text="Item 5"></div></div>



1.4.7.7 Declarative Support: Data Binding

Data binding is supported seamlessly by the declarative support. Just add the model path in curly brackets and bind the model to the control (or parent control):

<div data-sap-ui-type="sap.ui.commons.Button" data-text="{/stringValue}" data-enabled="{model2>/booleanValue}"></div>

0..n aggregations can define templates to use for the aggregation binding:

<div data-sap-ui-type="sap.ui.commons.Carousel" data-content="{/buttons}"> <div data-sap-ui-type="sap.ui.commons.Button" data-text="{title}"></div></div>

In the example above, the button template is used for the carousel content data binding.

Related Information

Data Binding [page 84]

1.4.7.8 Compiling Declarative HTML

The plugin only works for controls that are defined as declarative markup on startup time. To compile the declarative UI markup deferred, for example, when the markup is dynamically loaded and added to the DOM you can call the sap.ui.core.plugin.DeclarativeSupport.compile method, see the following code snippet:

<div id="button"> <div data-sap-ui-type="sap.ui.commons.Button" data-text="This button is added dynamically"></div></div>

<script> sap.ui.core.plugin.DeclarativeSupport.compile(document.getElementById("button"));</script>

1.4.8 SAPUI5 Components

Components are independent and resuable parts used in SAPUI5 applications. An application can use components from different locations from where the application is running. Thus, components can be developed by different development teams and be used in different projects.

NoteConstraints due to cross-origin issues also apply to components.



Components also support the encapsulation of closely related parts of an application into a particular component. This makes the structure of an application and its code easier to understand and to maintain.

SAPUI5 provides the following two types of components:

● UI components (class: sap.ui.core.UIComponent)UI components represent a screen area or element on the user interface, for example, a button or a shell, along with the respective settings and metadata.

● Faceless components (class: sap.ui.core.Component)Faceless components do not have a user interface and are used, for example, for a service that delivers data from a back end system.

The sap.ui.core.Component class is the base class for UI and faceless components. To extend the functionality, components can inherit from their base class or from another component.

Structure of a Component

A component is a folder. The folder name defines the component name and contains all optional and required resources that are used in the component except for the required SAPUI5 libraries and child components. Optional resources are, for example, the CSS and internationalization files, views, and images. The following files are mandatory for components:

● component.jsThis is the component controller and provides the runtime metadata (properties, aggregation, events) and the component methods. The name parameter that is passed to the component constructor represents the package name under which you can find the component.

● component.jsonThis is the component descriptor and contains the design-time metadata; you need this file for design-time environments such as the AppDesigner. The file is not loaded during runtime.

NoteAll paths within a component are relative paths to the component.js file and not to the index.html file.

The following figure gives an example of a component folder structure.



The ComponentContainer control wraps a UI component. You use the control in the SAPUI5 control tree in the same way as any other control.

Related Information

Defining a Component for SAPUI5 from Scratch [page 141]Describes how to define a component for SAPUI5 from scratch

1.4.9 Defining a Component for SAPUI5 from Scratch

Describes how to define a component for SAPUI5 from scratch

Context

This procedure describes how you create a new component for SAPUI5 from scratch. The example component used in the procedure has a button with configurable text.

Procedure

1. Create a new folder with the name of your component, for example button.2. Create the following files in your folder:

○ Component.js

// define a new (simple) UIComponentjQuery.sap.require("sap.ui.core.UIComponent");



jQuery.sap.require("sap.ui.commons.Button");jQuery.sap.declare("samples.components.button.Component");

// new Componentsap.ui.core.UIComponent.extend("samples.components.button.Component", {

metadata : { properties : { text: "string" } }});

samples.components.button.Component.prototype.createContent = function(){ this.oButton = new sap.ui.commons.Button("btn"); return this.oButton; };

/** Overrides setText method of the component to set this text in the button*/samples.components.button.Component.prototype.setText = function(sText) { this.oButton.setText(sText); this.setProperty("text", sText); return this;};

○ Component.json

{ "name": "samples.components.button", "version": "0.1.0", "description": "Sample button components", "keywords": [ "button", "example" ], "dependencies": { }}

The component is now ready to be used in an application. The following code snippet gives an example of the use of the component in two instances:

// Create a component var oComp1 = sap.ui.getCore().createComponent({ name: "samples.components.button", id: "Comp1", settings: {text: "Hello World"} }); // Create a Ui container var oCompCont1 = new sap.ui.core.ComponentContainer("CompCont1", { component: oComp1 }); // place this Ui Container with the Component inside into UI Area oCompCont1.placeAt("target1");

// You can also create a component and container at once. // In this example the container will create a new component according to the name. var oCompCont2 = new sap.ui.core.ComponentContainer("CompCont2", { name: "samples.components.button", settings: {text: "Hello World again"}



}); oCompCont2.placeAt("target2");

Related Information

SAPUI5 Components [page 62]

Using UI Components in Applications [page 145]

1.4.9.1 component.js File

The component.js file is the component controller and provides the runtime metadata and the component methods.

A component can depend on the entire SAPUI5 library. If you only require particular controls, you can also start with the corresponding require statements directly. The following code snippet is an example for a declaration statement:

jQuery.sap.declare ("samples.Components.shell.Component");

To create a UI component, you extend the UI component's base class and pass to it the name of the new component and its package path as shown in the following code snippet:

// Shell Componentsap.ui.core.UIComponent.extent("samples.components.shell.Component", {[...]

The metadata provide the information to ensure the completeness of the elements of which the component consists of. This facilitates the decoupling of the application logic as much as possible from the logic within a particular component. The following metadata parameters can be defined in the component.js file:

● abstract● version● includes● dependencies

○ external○ libs○ components○ ui5version

● publicMethods● aggregations● library● autoDestroy



● initOnBeforeRender

The following code snippet is taken from the component sample application and contains examples for all metadata parameters in the component.js file::

sap.ui.core.UIComponent.extend("samples.components.shell.Component", { metadata : { "abstract": true, version : "1.0", includes : [ "css/shell.css" ], //array of css and/or javascript files that should be used in the component dependencies : { // external dependencies libs : [ ],// array of required libraries, e.g. UX3 if your component depends on them components : ["samples.components.products.overview", "samples.components.products.details", "samples.components.products.supplier"], // nested components - more about these, later on ui5version : "1.13.0" }, publicMethods: [ "render" ], aggregations: { "rootControl": { type: "sap.ui.core.Control", multiple: false, visibility: "hidden" } // needs to be set to enable databinding functionality }, library: "samples.components.shell", // inherited from ManagedObject, if omitted, the current package is automatically retrieved autoDestroy: false, // destroy component when view should be destroyed initOnBeforeRender: true }});

You can add a properties section to the metadata for all properties that can adopt different values during runtime. The getters and setters for these properties are generated automatically, but you can overwrite them if you require additional functionality.

sap.ui.core.UIComponent.extend("samples.components.shell.Component", { metadata : { "abstract": true, version : "1.0", includes : [ "css/shell.css" ],

[… omitting some lines to make the example shorter]

initOnBeforeRender: true, properties : { appTitle: { name:"appTitle", type:"string", defaultValue:"Default Value that will be replaced with something meaningful through the setter for this property" },someOtherProp: { name:"myProperty", type:"string", defaultValue:"Some text" } }, }});

You can use the following methods to control the initial instantiation of the component:

● initOverwrite this method for example to connect the model between the control and the component. This method is not called by the application directly, but called automatically when you create the instance of the component.

● createContentThe createContent method needs to be overwritten within your component implementation. You use this method to place all the code which is required to fill your component with the respective content, for example,



creating an instance of the controls that should be used, or connecting the view that should be displayed. For the latter, you simply need to set this view to the view you whish to use. See the following code snippet for an example:

this.view = sap.ui.view({id:"myView",viewName:"samples.components.products.details.view.Details",type:sap.ui.core.mvc.ViewType.JS});

1.4.9.2 Using UI Components in Applications

To render UI components, you must wrap them in a ComponentContainer. UI components cannot be directly placed in a page with the placeAt method. A component container carries specific settings and also contains the lifecycle methods of a regular control, such as the onInit and onBeforeRendering methods. The methods of the ComponentContainer call the corresponding methods of the UI component internally.

Within an application, two different options to instantiate a ComponentContainer and a UI component exist. The following example assumes that the samples.components.button component exists and is loaded:

● Option 1: Create the component first, then add the component to the container, and finally use the placeAt method to place the component on the page:

var oComp = sap.ui.getCore().createComponent({ name: "samples.components.shell", id: "Comp1", settings: {appTitle: "Hello World 1"} });

var oCompCont = new sap.ui.core.ComponentContainer("CompCont1", { component: oComp }); oCompCont.placeAt("target1");

● Option 2: Pass the component to the componentContainer constructor:

var oCompCont2 = new sap.ui.core.ComponentContainer("CompCont2", { name: " samples.components.shell", settings: {text: "Hello World 2"} }); oCompCont2.placeAt("target2");

1.4.10 Component Configuration

You use the component configuration for the definition of static configuration for components. The configuration is available in the component metadata and you can access the configuration without creating instances of the component.

The following code snippet shows how you define the configuration for components.

sap.ui.core.UIComponent.extend("sap.samples.Component", {



metadata : { version : "1.0", config: { "sap.samples.config1": { "Key1-1": "Value1-1", "Key1-2": "value1-2" }, "sap.samples.config2": { "Key3-1": "Value3-1", "Key3-2": "Value3-2" } } }});

To access the configuration without creating an instance of the component, simply require the component as follows:

jQuery.sap.require("sap.samples.Component");var oConfig = sap.samples.Component.getMetadata().getConfig();

A component instance can access its configuration as shown in the following code snippet:

[...]

init: function() { var oConfig = this.getMetadata().getConfig(); }

[...]

When you extend a component and add additional configuration, the configuration is merged with the original component:

sap.samples.Component.extend("customer.Component", {

metadata : { version : "1.0", config: { "sap.samples.config1": {

"Key1-3": "Value1-3"

}, "customer.config1": { "Key1-1": "Value1-1" } } }});



The merged configuration then looks as follows:

var oConfig = { "sap.samples.config1": { "Key1-1": "Value1-1", "Key1-2": "value1-2", "Key1-3": "Value1-3" }, "sap.samples.config2": { "Key3-1": "Value3-1", "Key3-2": "Value3-2" }, "customer.config1": { "Key1-1": "Value1-1" }};

1.4.11 Extensibility Concept: Adapting SAPUI5 Applications

SAPUI5 supports the adaptation of standard applications to specific requirements. The information about the adapted objects is stored in the component configuration. The standard application itself is not changed. The customized application becomes the start-up project and launches the standard application with the additional customizing configuration.

SAPUI5 supports the following adaptations of the standard::

● View extensions by using extension points to insert custom content (views or fragments)● Replacing standard views with customized views● Modifying views by changing specific properties● Controller extensions by adding code or overriding existing code● Customizing i18N resource texts

1.4.11.1 Example: Component Configuration

The component configuration contains the required information about the extension metadata and the objects that are replaced or extended. It is contained in the component.js file of the custom application.

Note● The component of the custom application needs to inherit from the main component of the original

application.● To make the location of the original application or component known to SAPUI5, it may be necessary to use

registerModulePath(...).● The configuration in the customizing section contains the extension metadata and describes the objects

that are replaced or extended.

To The following code snippet shows an example of a configuration structure.

some.sap.Component.extend("some.customer.Component", {



metadata : { .....some configuration config: { .....some configuration }, customizing: { "sap.ui.viewExtensions": { "samples.components.ext.sap.Sub2": { "extension2": { className: "sap.ui.core.Fragment", fragmentName: "samples.components.ext.customer.CustomFrag1", type: "XML" }, "extension3": { className: "sap.ui.core.mvc.View", viewName: "samples.components.ext.customer.CustomSubSubView1", type: "XML" } } }, "sap.ui.viewModifications": { "samples.components.ext.sap.Sub3": { "customizableText": { "visible": false } } },

"sap.ui.viewReplacements": { "samples.components.ext.sap.Sub1": { viewName: "samples.components.ext.customer.CustomSub1", type: "XML" } }, "sap.ui.controllerExtensions": { "samples.components.ext.sap.Main": { "controllerName": "samples.components.ext.customer.MainExtension" } } } }});

"sap.ui.viewExtensions": Provides customized view content in a specified extension point in the standard application

sap.ui.viewModifications": Used for overriding control properties of the standard application

"sap.ui.viewReplacements": Used for replacing a standard view with a customized view

"sap.ui.controllerExtensions": Used for replacing a standard controller with a customized controller



1.4.11.2 View Extension

SAPUI5 uses extension points to indicate the position within a view where you can insert customized content. You insert the extension point in a standard view. In the code snippet below, three extension points are defined: extension1, extension2. and extension.

<mvc:View xmlns="sap.ui.commons" xmlns:core="sap.ui.core" xmlns:mvc="sap.ui.core.mvc"> <core:ExtensionPoint name="extension1" /> <TextView text="SAP View 'Sub2' - this one is extended by the customer and there should be a button after this text"></TextView> <core:ExtensionPoint name="extension2" /> <core:ExtensionPoint name="extension3" /> </mvc:View>

In the component customizing you can then assign the customized view to the respective extension point:

customizing: { "sap.ui.viewExtensions": { "samples.components.ext.sap.Sub2": { "extension2": { className: "sap.ui.core.Fragment", fragmentName: "samples.components.ext.customer.CustomFrag1", type: "XML" }, "extension3": { className: "sap.ui.core.mvc.View", viewName: "samples.components.ext.customer.CustomSubSubView1", type: "XML" } }, .....some more content

The following code snippet gives an example of a customized view that is assigned to extension2:

<mvc:View xmlns="sap.ui.commons" xmlns:core="sap.ui.core" xmlns:mvc="sap.ui.core.mvc"> <core:ExtensionPoint name="extension1" /> <TextView text="Customer View 'SubSubView1' - this one extends the original SAP View 'Sub2' - and even custom Views can be extended:"></TextView> <core:ExtensionPoint name="extension2" /> </mvc:View>

1.4.11.3 View Modification

You can modify views by changing the property of a standard view control. The following code snippets give an example for a view modification. The someCustomizableTextControl control of the standard view Sub3.view.xml shall not be visible in the modified view:

<mvc:View xmlns="sap.ui.commons" xmlns:mvc="sap.ui.core.mvc"> <TextView text="SAP View 'Sub3' - the text after this one is hidden by customizing: "></TextView> <TextView id="someCustomizableTextControl" text="This text is made invisible by customization"></TextView> </mvc:View>



In customizing, you identify the customizableText controller and set the visible property to false:

customizing: { "sap.ui.viewModifications": { "samples.components.ext.sap.Sub3": { "someCustomizableTextControl": { "visible": false } } }}

1.4.11.4 View Replacement

If the extension of a view is not sufficient to meet your requirement, you can replace a standard view with a customized view. The following code snippet gives an example for a view replacement.

The following view is delivered in the standard application:

<mvc:View xmlns="sap.ui.commons" xmlns:mvc="sap.ui.core.mvc"> <TextView text="SAP View 'Sub1' - this one should have been replaced by the customer View"></TextView> </mvc:View>

You want to replace this standard view with the following customized view:

<mvc:View xmlns="sap.ui.commons" xmlns:mvc="sap.ui.core.mvc"> <TextView text="Custom View 'Sub1' - this one replaces the original SAP View 'Sub1'"></TextView> </mvc:View>

You connect the two views in customizing:

customizing: { .....some more content "sap.ui.viewReplacements": { "samples.components.ext.sap.Sub1": { viewName: "samples.components.ext.customer.CustomSub1", type: "XML" } }, .....some more content

1.4.11.5 Controller Extension

In SAPUI5, you can extend or overwrite the functionality of a base controller by merging the standard controller with a new controller that meets your specific requirements.

NoteThe controller extension concept of SAPUI5 does not use inheritance but merging on JavaScript object level.



The methods of your new controller override the standard methods with the same name. The following controller lifecycle methods are, however, an exception to this rule: onInit, onExit, onBeforeRendering, onAfterRendering. The controller methods of your customized application are called either after (for onInit and onAfterRendering), or before (for onExit and onBeforeRendering) the standard lifecycle methods. The following code snippets show how the replacment of controllers works.

The following code snippet shows the standard controller Main.controller.js that you want to replace:

sap.ui.controller("samples.components.ext.sap.Main", { onInit : function () { console.log("samples.components.ext.sap.Main - onInit"); },

doSomething: function() { alert("this is an original standard action"); },

doSomeStandardAction: function() { alert("this is another original standard action"); }});

You replace the standard controller with the following new controller CustomMain.controller.js:

sap.ui.controller("samples.components.ext.customer.CustomMain", { onInit : function () { console.log("samples.components.ext.customer.CustomMain - onInit"); },

doSomething: function() { alert("this is a customer action"); },

doSomeCustomAction: function() { alert("this is another customer action"); }});

Im customizing, you connect the new controller with the standard controller:

customizing: { "sap.ui.controllerExtensions": { "samples.components.ext.sap.Main": { controllerName: "samples.components.ext.customer.CustomMain" } }, .....some more content

With this customizing, the samples.components.ext.customer.CustomMain controller functions are merged every time the controller is called. The log contains the following messages after initialization:

samples.components.ext.sap.Main - onInitsamples.components.ext.customer.CustomMain - onInit

The doSomething method of the new controller overwrites the doSomething method of the standard Controller. Thus, if the method is invoked, an alert popup with the following text appears: this is a customer action.

The doSomeStandardAction method remains available without changes, as no method with the same name exists in the new controller.

The doSomeCustomAction method is additionally available and you can use it, for example, in a view extension.



The controller extensions are applied to all controllers with the specified name within the customized component, regardless of whether the controller is instantiated explicitly or belongs to a view.

1.4.11.5.1 Providing Hooks in the Standard Controller

Controller extensions can override any method. As this is a powerful but also fragile feature, you can provide specific extension points in the controller code, so-called hooks. You can document these controller points and keep them stable, thus providing more robust hooks across application updates for your extensions.

The process for this is as follows:

1. In the application, identify a strategic location within the controller code where customers may want to plug in and execute their customized code.

2. In the application, define a new function name which is reserved for the extension, document the function and any arguments the function may receive or return.

3. Add code lines in the application (see code snippet below) to check whether the function has been implemented, and, if so, to call the function. We also recommend to implement sanity checks for return values.

4. The customer can then configure a controller extension, implementing exactly this one function.5. The SAPUI5 runtime merges the new controller extension into the standard controller. If the customizing is

enabled, the new function can be executed.

Example

By receiving the data object oSomeData from the server, the application enables you to access and modify the data object. The extension function name is onDataReceived and gets a reference to the data object as argument.

Standard controller:

// ...data object oSomeData has been received, possibly from an Ajax response... if (this.onDataReceived) { // check whether any extension has implemented the hook... this.onDataReceived(oSomeData); // ...and call it } // ...continue working with the (now possibly modified) data...

New controller:

sap.ui.controller("customer.xy.Sub2ControllerExtension", { onDataReceived: function(oData){ // oSomeData will be passed in if (oData && oData.status === "important") { oData.message = oData.message + "!!!"; // modify some part of the data object, adding exclamation marks to a message text } } // no need to return anything as in this example the original object is modified});



NoteThis only works for one extension layer as the most specific or last extension overrides any other hook implementations. To allow multi-layer extensions, we recommend that middle-layer extensions provide and document their own hook functions.

1.4.11.6 Controller Replacement

For a view replacement, you can either use the standard controller of the replaced view by setting its name as controllerName, or use and extend the standard controller, or you can replace the controller by specifying a new controller name in the new view and implementing the new controller.

1.4.11.7 I18n Resource Text Customization

You can enhance the sap.ui.model.resource.ResourceModel with customized resource bundles. For this, the ResourceBundle provides the possibility to enhance it with other bundles:

var oModel = new sap.ui.model.resource.ResourceModel({bundleUrl:"./testdata/messages.properties"});oModel.enhance({bundleUrl:"./testdata/messages_custom.properties"});

An enhanced ResourceModel tries to resolve the i18n texts from the customized bundle first. If a text does not exist there, it tries to look up the i18n text in the standard bundle.

The additional resource bundles are not part of the customizing configuration, but can be added as part of a controller extension.

1.4.11.8 Supportability and Limitations

If a customized application does not run properly, you can disable the customizing. In a support case, for example, you can set a breakpoint early in the sap-ui-core.js and then execute the following code in the console:

#!js window["sap-ui-config"] = window["sap-ui-config"] ||{}; window["sap-ui-config"]["xx-disableCustomizing"] = true;

NoteFor security reasons, it is not possible to use a URL parameter.

View Modifiation (with <core:ExtensionPoint />) and Control property modification are supported only for XML type of views Control property modification is only possible for the "visible" property and only for controls which have a given ID (one which is specified in the XMLView)



Limitations

The view modifications by means of extension points and the modification of control properties are only supported for XML view types.

The control property modification is only supported for the visible property and only for controls with a given ID specified in the XML view.

1.4.12 Navigation

Navigation in SAPUI5 enables you to pass data from the hash to any view, and to adjust a current hash so that you can use it as a bookmarkable URL. Depending on the hash, you can also generate views automatically.

To notify your application that a hash has changed to a certain value, you use a route. If the route matches the hash, it provides the data that has been passed over to the hash to a defined handler. If you use a UI component, the component creates the router, see [Link]. In the following example, the URL is www.myApp.com#product/5. To get the information that the hash points to the product and that the value is "5", you need the following configuration:

//Somewhere at the start of your application var aRoutes = [ { pattern : "product/{id}", // will be the url and from has to be provided in the data name : "specificProduct" // name used for listening or navigating to this route } ];

var oRouter = new sap.ui.core.routing.Router(aRoutes);

//this is used to retrieve the instance again oRouter.register("appRouter");

//starts reacting on the hashchange + parses the current hash and notifies callbacks oRouter.initialize();

With this configuration, the route pattern is matched against the hash. The curly brackets indicate that this segment of the URL is passed to a handler with the contained value. In the example the value is "5".

The following code snippet shows how you can register to this:

sap.ui.controller("MyApp.View1", { //inside of a controller onInit: function() { var oRouter = sap.ui.core.routing.Router.getRouter("appRouter");

oRouter.attachRouteMatched(function(oEvent) { if (oEvent.getParameter("name") !== "specificProduct") { return; //we only want to react to events for the specificProductRoute } //We now know we hit the specificProduct route and retrieve the id this._selectItemWithId(oEvent.getParameter("arguments").id); //bind the this pointer to the callback



}, this); },

_selectItemWithId : function(id) { //implementation eg: select an item in a list }

1.4.12.1 Routing in UI Components

UI Components can intitialize a router based on the component metadata. For the routing metadata, the following two parameters exist:

● routes: Contains an array with all routes defined by the component● config: Contains default values; the default values are applied, if the route does not specify a setting and are

overwritten by custom values

metadata : { ... routing: { config: { // default values for routing viewType : "XML", viewPath: "default.path.view", clearTarget: false }, routes: { // contains routing configuration objects "myRouteName" : { name : , pattern : "FirstView/{from}", view : "myViewId" } } } ...}

To intialize the router, the UI component uses the init function as follows:

init : function() { sap.ui.core.UIComponent.prototype.init.apply(this, arguments); // this component should automatically initialize the router! this.getRouter().initialize();}

To access the router and to use its functions, use the getRouter() function or the static getRouterFor function of the UI component. You can pass either a controller, or a view:

var oRouter = sap.ui.core.UIComponent.getRouterFor(this);

All views which are generated by the router are automatically created in the context of the respective UI component.



1.4.12.2 Configuration Parameters for Navigation

To use navigation in SAPUI5, you have to provide configuration for routes and for the router. The following configuration parameters exist for routes:

● name (mandatory)The route name parameter identifies the route and has to be unique within one router instance. If you add a callback on the routeMatched event of the router, you need to check for the route name. You also need to provide the route name as first parameter if you want to use the navTo method of the router.Example:

"routing" : { // name used for listening or navigating to this route "specificProduct" : { //all the optionalParameters } }

● pattern (optional)The pattern parameter defines the string that is matched against the hash. Only the first route with a matching pattern triggers the callback. The following special character and URL segments exist:

○ / - seperator for a URL segment○ {variableName} - mandatory variable, for example foo/{bar} does not match against the hash /foo○ :optionalVariableName: - optional variable, for example foo/:bar: matches against foo/, but bar

is undefined in the callback○ :myVariable*: - ignores separators and puts everything that follows in this variable, for example foo/

{bar*} matches against foo/bar/one and the value of bar is "bar/one"○ :query?: - puts the key value pairs into a query variable, for example ?foo=bar&one=two adds a

parameter { query : { foo : "bar" , one : "two" } }

NoteUndefined patterns match the empty hash. You usually only skip the pattern for subroutes and subroutes are registered before their parents. So, as a workaround, use the same pattern as one of the subroutes.

● subroutes (optional)The subroutes parameter contains an array of routes and can contain the complete route configuration. Routes that are added to subroutes may have subroutes themselves.

● view (optional)The view parameter contains the name of the view that is created on the first time a route is matched. To place the view in a control, use targetAggregation and targetControl. Views are only created once.

● viewType (optional)The view type parameter defines the view type that is created.

● viewPath (optional)The view path parameter specifies a prefix that prepends the view; if, for example, view is set to "myView" and viewPath is set to "myApp", the created view is myApp.myView.

● targetParent (optional)The target parent parameter defines the ID of the parent of the targetControl parameter.

● targetControl (optional)Views are put into a container control, for example a shell control or a NavContainer for mobile applications, or into any other container. The targetControl parameter contains the ID of this control.



● targetAggregation (optional)The target application parameter contains the name of an aggregation of the target control that contains views. A NavContainer, for example, has an aggregation called Pages and the shell container has Content.

● clearTarget (optional)The clear target parameter defines a boolean that is used to specify if the aggregation should be cleared before adding the view to it.

● callback (optional)The callback parameter is an optional function that is executed after the route has matched.

The router configuration supports the same values as the route. If the route does not provide a value, the application uses the router configuration. The following code snippet gives an example:

//provides the default values for all viewsvar oRouterConfig = { viewType : "XML", viewPath: "MyApp.view", };var aRoutes = [{ viewType : "JS", pattern : "foo", name : "myRoute"}];

//results in following config:

{ viewPath: "MyApp.view", viewType : "JS", pattern : "foo", name : "myRoute"}

1.4.12.3 Methods and Events for Navigation

You use the navTo(routeName, data) method to navigate to the given route and to fill the hash with data. Data is also provided to the listener callbacks of controllers that listen to this route.

sap.ui.controller("MyApp.View2", {

anyEvent: function() { sap.ui.core.routing.Router.getRouter("appRouter").navTo("View2",{ from: "View 1"}); }});

NoteThe hash in this example will not change to product/5 because view1 matches the name of the route defined in the example configuration.

The productId property of the data object has to match the placeholder in the pattern of the route. The listeners to the hash are informed because the hash is changed.

SAPUI5 provides the following events for navigation: routematched and viewcreated.



The route matched event is fired every time a changed hash matches a route. If you only want to react to specific routes, check if the name parameter matches the route you want to listen to. The event has the following parameters:

● name - name of the route that has matched● arguments - object of arguments that are part of the route● targetControl - control instance, in which the view was inserted (only if targetControl is provided)● view - instance of the view

Example:

sap.ui.controller("MyApp.View1", {

onInit: function() { var oRouter = sap.ui.core.routing.Router.getRouter("appRouter");

oRouter.attachRouteMatched(function(oEvent) { if (oEvent.getParameter("name") === "view1") {

this._selectItemWithId(oEvent.getParameter("arguments").id);

}, this); },

_selectItemWithId : function(id) { //implementation }

The viewcreated event is fired every time a new view has been created by the navigation system. The event has the following parameters:

● view - view instance● viewName - name of the view● type - view type

1.4.12.4 Route Matching

For route matching, the order of route definition is important: Only the first matching route will be matched. Therefore, define specific routes first as shown in the following code snippet:

//this is '''correct'''{ "firstRoute" : { "pattern" : "foo/bar" }, "secondRoute" : { "pattern" : "foo/{id}" }}

In this example, #foo/bar matches the first route and foo/anything matches the second route.

If you do it the other way round as shown in the following example, the secondRoute is hit passing bar as ID whereas the first route will never be hit:

//this is '''correct'''{



"firstRoute" : { "pattern" : "foo/bar" }, "secondRoute" : { "pattern" : "foo/{id}" }}

1.4.12.5 Building a Catchall Route

For requests that do not match any route, you can use catchall routes. If you define a catchall route, make sure that you define it as the last route, because the first route that gets hit is informed. All routes after this route are ignored.

Example:

routes : [// a lot of other routes before this one{ pattern : ":all*:", //catchall viewId : "Master", // any request not matching a hash will go to master name : "catchall", // name used for listening or navigating to this route } ]

1.4.13 HTML Templating in SAPUI5

The HTML templating concept in SAPUI5 is based on handlebars, which supports you in building semantic templates. You can either use standard expressions and helpers together for the context of a template instance, or the custom helpers for handlebars provided by SAPUI5, which you can use together with the SAPUI5 models. This enables you to bind texts against properties in the model. If the property in the model changes, the text is updated accordingly. You can create and bind the value DOM elements including their DOM attributes. For input DOM elements like INPUT, TEXTAREA or SELECT, SAPUI5 establishes a two-way binding: On change of the DOM element value the model is updated if the value is bound against a SAPUI5 model. You can also define controls in the template similar to the declarative support but in handlebars helper notation.

Prerequisites

To get started with HTML templating, you must comply with the following requirements:

● An inline template is defined.● The templating framework is triggered to parse the inline template.



Example:

// register all available templates in the documentsap.ui.template();

<div id="myControlTemplate" data-type="text/x-handlebars-template"> <h3>Control Template (using "control" expression)</h3> {{control sap-ui-type="sap.ui.commons.Label" design="Bold" text="{/title}"}} <ul> {{#each path="/persons"}} <li>{{control sap-ui-type="sap.ui.commons.TextView" text="{lastName}, {firstName}"}}</li> {{/each}} </ul> </div>

1.4.14 Expressions and Helpers for HTML Templating

For HTML templating in SAPUI5, you can use the following expressions and helpers:

● plain handlebarsThe plain handlebars expressions do not refer to SAPUI5 models, but to a context which is passed along when, for example, an instance for the template is created. The following example shows how you can use plain handlebars expressions and helpers.

<h3>{{title}}</h3><ul>{{#each persons}} <li>{{firstName}} {{lastName}}</li>{{/each}}</ul>

For more information about handlebars expressions and helpers, see the handlebars documentation.● SAPUI5-specific helpers

SAPUI5 provides the following helpers for HTML templating

○ {{text}}You use the text helper to bind texts to properties of SAPUI5 models. The helper registers to changes in the SAPUI5 model and updates the template instance if the property in the model changes. When the templating engine parses the helper, it is replaced with the new value in the model. The path attribute supports the standard SAPUI5 data binding syntax.Example: {{text path="/title"}}To bin proprties from named models, such as translatable text, you can specify this in the path attribute as follows:{{text path="i18n>MY_TEXT"}}

○ {{element}}You use the element helper to create single DOM elements. You can nest DOM elements and bind DOM attributes against values of the model.Example: {{element tag="div" text="Hello World" data-myattr="myvalue" style="border: 1px solid black;" class="myStyleClass"}}



Example for use with data binding with a span DOM element as default tag name: {{element text="{/title}"}}Example for use with data binding and named models: {{element tag="div" text="{i18n>MY_TEXT}"}}Example for use with editable DOM elements for two-way binding (binding the value of an input field against a model property):

{{element tag="input" value="{/title}"}}{{element tag="textarea" text="{/title}"}}

DOM elements have the advantage that you can update them individually when the property value in the model has changed. You do not need to re-render the template completely.

○ {{control}}You use the control helper to creat or embed SAPui5 controle intro a template instance. It is aligned with declarative support. The following example shows how you embed a sap.ui.commons.TextField in a template:{{control sap-ui-type="sap.ui.commons.TextField" value="{/title}"}}

○ {{each}}You can use the each helper together with SAPUI5 data binding by specifiying the path attribute:

{{#each path="/persons"}} {{element text="firstName"}}{{/each}}

1.4.15 Example: Use of HTML Templating in SAPUI5

The following example demonstrates the use of the helpers for HTML templating that can be used in SAPUI5:

<!DOCTYPE HTML><html><head>

<meta http-equiv="X-UA-Compatible" content="IE=edge" /> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">

<title>Template - sap.ui.core.tmpl</title>

<script id="sap-ui-bootstrap" type="text/javascript" src="resources/sap-ui-core.js" data-sap-ui-libs="sap.ui.commons" data-sap-ui-theme="sap_goldreflection" data-sap-ui-xx-bindingSyntax="complex" > </script> <script> // sample code jQuery(function() { // define the model var oModel = new sap.ui.model.json.JSONModel({ title: "Persons", persons: [{



firstName: "Peter", lastName: "Muessig" }, { firstName: "Tim", lastName: "Back" }, { firstName: "Christoph", lastName: "Kraemer" }] }); sap.ui.getCore().setModel(oModel); // register all available templates in the document sap.ui.template(); }); </script>

</head><body class="sapUiBody" role="application">

<div id="mySimpleTemplate" data-type="text/x-handlebars-template"> <h3>Text Template (using "text" expression)</h3> <b>{{text path="/title"}}:</b> <ul> {{#each path="/persons"}} <li>{{text path="firstName"}} {{text path="lastName"}}</li> {{/each}} </ul> </div>

<div id="myAdvancedTemplate" data-type="text/x-handlebars-template"> <h3>Advanced Text Template (using "element" expression)</h3> {{element tag="b" text="{/title}"}}: <ul> {{#each path="/persons"}} {{element tag="li" text="{firstName} {lastName}"}} {{/each}} </ul> </div>

<div id="myAdvancedEditTemplate" data-type="text/x-handlebars-template"> <h3>Advanced Text Template (using editable "element" expression)</h3> {{element tag="textarea" text="{/title}" rows="2" cols="40"}} <ul> {{#each path="/persons"}} <li>{{element tag="input" value="{firstName}"}} {{element tag="input" value="{lastName}"}}</li> {{/each}} </ul> </div>

<div id="myControlTemplate" data-type="text/x-handlebars-template"> <h3>Control Template (using "control" expression)</h3> {{control sap-ui-type="sap.ui.commons.Label" design="Bold" text="{/title}"}} <ul> {{#each path="/persons"}} <li>{{control sap-ui-type="sap.ui.commons.TextView" text="{lastName}, {firstName}"}}</li> {{/each}}



</ul> </div>

<div id="myControlEditTemplate" data-type="text/x-handlebars-template"> <h3>Advanced Control Template (using editable "control" expression)</h3> {{control sap-ui-type="sap.ui.commons.TextArea" value="{/title}" rows="2" cols="40"}} <ul> {{#each path="/persons"}} <li>{{control sap-ui-type="sap.ui.commons.TextField" value="{lastName}"}}, {{control sap-ui-type="sap.ui.commons.TextField" value="{firstName}"}}</li> {{/each}} </ul> </div>

</body></html>

1.4.16 Modularization and Resource Handling

The following sections provide information abour the modularization concepts and resource handling for SAPUI5.

1.4.16.1 Modularization and Dependency Management

The SAPUI5 framework has built-in support for modularizing comprehensive JavaScript applications. That means, instead of defining and loading one large bundle of JavaScript code, an application can be splitted into smaller parts which then can be loaded at runtime at the time when they are needed. These smaller individual files are called modules.

To load a module, the jQuery.sap.require function must be used. Assume the following page:

#!js

 <script id="sap-ui-bootstrap" src="./resources/sap-ui-core.js" data-sap-ui-libraries="sap.ui.commons"></script>

<script> jQuery.sap.require("sap.ui.commons.MessageBox");

function onPressButton() { sap.ui.commons.MessageBox.alert("Hello World!"); }

</script>

At first, the SAPUI5 framework initializes and then loads the sap.ui.commons.MessageBox module. Internally, the framework analyzes the module name and derives the module URL from it:

./resources/sap/ui/commons/MessageBox.js

The module script is then loaded from that URL and executed.

What is a Module

A module simply is a JavaScript file that can be loaded and executed in a browser. There are no rules or definitions what code belongs to a module, and what code does not. It is up to the developer what content to bundle into a single module. But typically, the content of a module has some topic in common. Either it forms a JavaScript class or namespace, or the contained functions address a specific topic, for example client to server communication, mathematical functions, and so on.

There is also no special syntax or structure defined for modules. However, there are some features that module developers should be aware of and that they can use:

Name: A module is loaded by calling jQuery.sap.require with the name of the module. So, all modules are identified by a name. Human readers often associate a module with the main JavaScript object declared in it. Therefore, the module names by convention are a hierarchical sequence of dot-separated identifiers (like sap.ui.core.Core). It is best practice to use all but the last identifier to group modules in a logical and/or organizational way (much like packages in Java) and to use the last identifier to give the module a meaningful, semantical name, for example, the 'topic' common to the code in the module.

Declaration: Modules can declare themselves by calling the static jQuery.sap.declare function with their name. This helps SAPUI5 to check at runtime whether a loaded module really contains the expected content (compare the required name against the declared name). As a side effect, jQuery.sap.declare will ensure that the parent namespace of the module name exists in the current global namespace (window). More details can be found in the API documentation of declare.

If a module does not contain a declaration, the framework assumes that the module has the expected content and automatically declares it with the name used for loading it. In some rare cases - which are explained below - a module declaration is mandatory.

Description: Furthermore, modules can contain a description which helps others to decide whether a module is useful for them, or not. By convention, any JavaScript comment preceeding a module's declaration (jQuery.sap.declare statement) is interpreted as its description. The configuration UI displays such descriptions next to the module name.

Dependencies: Last but not least, modules can use the jQuery.sap.require method to load other modules that they depend on. While jQuery.sap.require internally has the effect of a "loadModule" call, it can also be regarded as a dependency declaration (therefore its name 'require'). These dependency declarations can be evaluated at runtime (as explained above), but they can also be analyzed at built time or at runtime on the server.

Example:

A typical module that uses all of the above features might look like this (the module name is my.useful.SampleModule);

#!js

/* * A short documentation of the module. This documentation is not evaluated at runtime, only during build time */ jQuery.sap.declare("my.useful.SampleModule"); // declaration of the module. Will ensure that the containing namespace 'my.useful' exists.



// list of dependencies of this module jQuery.sap.require("sap.ui.core.Core"); jQuery.sap.require("some.other.Module"); jQuery.sap.require("you.can.Also", "list.multiple.Modules", "if.you.Want"); ...

// create the 'main' object of the module my.useful.SampleModule = {};

Loading a Module

As mentioned already, modules are loaded by calling function jQuery.sap.require with the name of a required module. The framework then checks whether the named module is loaded already. If so, the function simply returns. Otherwise it tries to load and execute the module synchronously. If any of these two steps fails, an exception is thrown and execution of the calling module thereby is disrupted.

To summarize it: A call to jQuery.sap.require ensures that the required module is loaded and has been executed before execution of the caller continues (*). (*) this is only true as long as no cyclic dependencies occur.

When loading a module, its dot-separated name must be transformed to an URL. This is done by replacing all dots ('.') with slashes ('/') and appending the standard suffix '.js' to it. This transformed name is then appended to the UI5 resource root URL (a prefix of the URL where UI5 has been loaded from, see explanation of bootstrap). The resulting URL is then used to load the module as a text. If loading succeeds, the module is first declared with the original module name and then executed in a global context (window). If either loading the module or executing it fails, the module name is internally marked as "failed" and an exception is thrown indicating the cause for the failure. Any further tries to load the same module will fail immediately, reproducing the same error message.

Multiple Module Locations

It is a common use case for web applications that different modules are located in different locations (servers, web apps). Imagine for example that your web application is deployed as an individual web app and that it contains some very important modules to be loaded at runtime. But for administrative reasons, SAPUI5 and its provided modules have to be loaded from a content delivery network (CDN) or from a centrally deployed web app. As explained above, SAPUI5 by default will try to load any required modules from its resource root URL, namely from the centrally deployed web application. This would fail for the modules contained in your web application.

Such mixed location scenarios are supported with the jQuery.sap.registerModulePath function:

jQuery.sap.registerModulePath = function(sModuleNamePrefix, sURL);

It associates a module name prefix with an URL prefix. Any module whose name starts with the module name prefix will be loaded from the registered URL instead of the standard resource root URL. In the scenario prethought above, this can be used to redirect the request for the application-specific modules to the corresponding web application:

#!js

 <script src="http://www.sap.com/sapui5/1.0/resources/sap-ui-core.js" ></script>

dependency resolution tool wraps any embedded module with a few lines of additional coding. These additional checks will be evaluated during execution of the merged module and will have the same effect as the original runtime checks in an unmerged scenario:

...

// code of enclosing module ...

// location of a jQuery.sap.require('xyz');

if ( !jQuery.sap.isDeclared('xyz') ) { // check whether module 'xyz' has been loaded already

jQuery.sap.declare('xyz'); // will only be added if the module 'xyz' doesn't contain a declaration

// original text of module 'xyz' ... }

... // further code of enclosing module ...

NoteThe generated wrapper coding will also contain a module declaration if the module doesn't contain one. The wrapper avoids double loading no matter whether a module has been loaded as an individual file or as part of a bigger, merged module. It is even possible to recursively merge files (merged module A includes a merged module B).

Why not Simply Concatenating Modules?

One might wonder why multiple modules can not simply be concatenated into a bigger module. Why have the modules to be parsed and to be nested according to the original jQuery.sap.require calls? The answer simply is that this makes the runtime behavior of the merged file more predictable. As soon as you look at concrete modules with complex (or even cyclic) dependencies, order of module execution becomes significant. The main promise of jQuery.sap.require that the caller continues only after the required module has been successfully loaded and executed can be hold only if the required module is embedded exactly at the place where the jQuery.sap.require call was located.

In cases where a use of the dependency resolution tool is not possible at all, one might indeed simply concatenate modules. But then the following two criteria must be ensured 'manually' by the developer:

● The order of the files must obey the dependencies. A module must not 'require' another module that is only merged later on.

● All merged modules must do a declaration with jQuery.sap.declare, otherwise the framework will not know that the modules have been loaded and potentially load them again.



Configurator Servlet

As mentioned already, one way of executing the dependency resolution tool is to call it via a servlet. Such a servlet has been included in the phoenix-cdn application that is part of our drop. By default, the servlet is configured to react on the URL http:// host:port /sapui5/download/configurator. It accepts several parameters

URL Parameter Default Description

modules None Mandatory: A comma separated, ordered list of module names that should be included in the resulting module. If the parameter occurs multiple times, the values will be concatened

out "sap-ui-custom.js" Name of the resulting module. The resulting module will contain a declaration with that name. When the servlet is used from the configurator Web UI, then the name will also be suggested in the download dialog.

minimize False Activates the JavaScript minimization for the output (experimental feature)

The Configurator WebUI, which is part of phoenix-cdn as well, uses the servlet to create a downloadable JavaScript file containg all selected modules.

But it is also possible to use the servlet directly from within an application page and to load UI5 and the required controls etc. in one step. The following HTML fragment shows an example (line breaks added for better readability):

<script id="sap-ui-bootstrap" data-sap-ui-theme="sap_platinum" type="text/javascript" data-sap-ui-libs="sap.ui.commons" src="/sapui5/download/configurator?modules=jquery-1.4.2,jquery.sap.global,sap.ui.core.Core,sap.ui.commons.Button,sap.ui.commons.ButtonRenderer,sap.ui.commons.layout.MatrixLayout,sap.ui.commons.layout.MatrixLayoutRow,sap.ui.commons.layout.MatrixLayoutCell,sap.ui.commons.layout.MatrixLayoutRenderer" > </script>

Special Cases

How to Load jquery.sap.require?

Obviously, modules can only be loaded as soon as the jQuery.sap.require function is available. The implementation of this function is located in module 'jquery.sap.global' which in turn requires jQuery itself (located in module 'jquery-1.7.1'). At runtime, these two modules can not be loaded with 'jquery.sap.require' but must be loaded by some other mean. The SAPUI5 framework includes both modules in its bootstrap files sap-ui-core.js and sap-ui-core-lean.js. The first one also embeds the SAPUI5 core functionality and needs no



further modules. The second one only contains the two bootstrap modules and a require statement for the core. It is better suited for the development scenario described above (loading the modules separately).

If you create a new bootstrap file with the configuration UI and decide to include the jquery.sap.global or jquery modules, they always will be the first modules in the created file, and they will always be embedded. This ensures the availability of jQuery.sap.require.

Cyclic Dependencies

Sometimes, the functionality in two modules A and B might be interdependent. That means module A requires module B to execute and module B requires module A. We stated above that jQuery.sap.require ensures that the execution of a calling module doesn't continue until the required module has been loaded and executed. Taking this serious, cyclic dependencies could not be resolved but would lead to an endless series of requests (A->B->A->B->...).

This situation can be avoided by a workaround: As soon as a module A has been loaded and is about to execute, it is regarded as declared. So, when this module A embeds another module B which has not been loaded, module B will be loaded and executed. If B now again requires A, then the dependency resolution runtime will find that A has been declared already (despite the fact that its execution has not been finished yet) and simply returns. This workaround helps to break the endless loop, but it doesn't re-ensure the original promise of jQuery.sap.require.

Cyclic modules have to deal with that gap on their own. There are several ways/best practices how to do this:

● Variant 1: Merge A and BIf the conflicts can not be resolved easily, or if the modules are so highly related that they will be used together most of the time, then merging them into one module is the most simple solution.

● Variant 2: Interlaced Execution of A and BThis variant makes use of the fact that the module loading takes place exactly at the source location where the jQuery.sap.require function is executed. Let's assume that the content of modules A and B can be structured as follows:

// Module A, Part A.1

// Module Section A.1, does not depend on Module B and provides all code that module B depends on.

jQuery.sap.require("B");

// Module Section A.2, might depend on code in Module Section B.1

// Module B, Part B.1

// Module Section B.1, does not depend on Module A and provides all code that module A depends on.

jQuery.sap.require("A");

// Module Section B.2, might depend on code in Module Section A.1

Further assume (WLOG) that module A is loaded first. Then section A.1 will be executed and will be available to the outside world before the require('B') is executed. During the require, the framework will detect that



B is not available yet, will load and execute it. The execution starts with section B.1 which succeeds as it does not depend on A. When the execution of B reaches the require('A') statement, the framework detects that A has been loaded already and continues without loading A again. But remember, that the code from section A.2 is not available yet. The execution of B however continues and succeeds as - by assumption - B.2 does not depend on A.2. Now, the first require('B') succeeds and returns and section A.2 will be executed. And it might use the code from section B.1.

Procedure and result are similar in the case that B is loaded first.

1.4.16.2 Resource Handling

The resource handling of SAPUI5 is separated in two parts - a client-side and a server-side resource handling. Both are not dependent on each other. Furthermore they are complementary.

The server-side mechanism is not required. This is an optional component which improves the client-server interaction (server-side locale fallback instead of client-side with multiple requests) and especially is used for the Eclipse IDE development to support modularized development of SAPUI5 application and libraries.

Client-side Resource Handling

On the client-side SAPUI5 provides the following mechanism for resources:

● Modularization Concept (!Require/Declare for JavaScript files)● Localization Concept (Resource Bundles)

Both concepts are loading additional resources from a server where this server might be any kind of web server (simple, Java, ABAP, ...). It does not depend on any server side technology.

Server-side Resource Handling

For the Java server and also the integration into the Eclipse IDE SAPUI5 provides a resource handler. This resource handler is aligned with the concept of the JavaServer Faces - Resource Handler:

● The default implementation must support packaging resources in the web application root under the path resources/<resourceIdentifier> relative to the web app root.

● Resources packaged in the classpath must reside under the JAR entry name META-INF/resources/<resourceIdentifier>

The SAPUI5 resource handler extends this concept to support standard and test-relevant resources. Therefore we package our resources into the following paths:

● resources/**Resources are all kind of JavaScript, CSS, Mimes, Resource Bundles, which are relevant for the runtime.

● test-resources/**Test resources are resources which are samples and only relevant for testing purposes e.g. the content of the SAPUI5 test suite.



Other additional features of the resource handler are:

● Theme fallback:If resources are not available for the current theme it automatically checks the base theme for such resources and returns this resource instead without returning a 404.

● Resource bundle fallback:Similar to the client-side mechanism for loading resource bundles but it negotiates the request on the server and returns the best found resource bundle instead without 404, e.g.:messagebundle_en_US.properties > messagebundle_en.properties > messagebundle.properties

Resource Servlet

For Java Servlet containers SAPUI5 provides a ResourceServlet which manages the access to SAPUI5 resources within the web application and the various UI libraries in the classpath. The following snippet shows how to enable the resource servlet for SAPUI5:

#!text/xml

  

<servlet>

<display-name>ResourceServlet</display-name>

<servlet-name>ResourceServlet</servlet-name>

<servlet-class>com.sap.ui5.resource.ResourceServlet</servlet-class>

</servlet>

<servlet-mapping>


<url-pattern>/resources/*</url-pattern>

</servlet-mapping>

<servlet-mapping>


<url-pattern>/test-resources/*</url-pattern>

</servlet-mapping>

Before you can use it you need to make sure that the ResourceServlet is available in the classpath as JAR file.

Configuration

The resource handler is configured via context parameter which are defined in the web.xml. The following table gives an overview about configuration parameters:

Key Description

com.sap.ui5.resource.USE_CACHE flag to enable resource cache or not (default: "true")

com.sap.ui5.resource.MAX_AGE max age of resources in millis (default: "604800000" - 1 week)

com.sap.ui5.resource.ACCEPTED_ORIGINS list of accepted origins, e.g. * or *sap.corp,vesapui5.dhcp.wdf.sap.corp (default: empty)

com.sap.ui5.resource.DEV_MODE flag to enable the development mode (default: "false")

com.sap.ui5.resource.TEMPLATE_PATH template for the resource listing (default: "/templates/listing.html")

com.sap.ui5.resource.VERBOSE verbosity of the resource handler (default: "false")

com.sap.ui5.resource.REMOTE_LOCATION location which is used to proxy requests to for resources not being located locally (default: empty)

com.sap.ui5.resource.PREFER_REMOTE_LOCATION flag to prefer resolving the resource from the remote location before fallback to the classpath (default: false)

Configuration parameters are added as context parameters to the web.xml.

Development Mode

When starting to develop SAPUI5 controls and modules being located inside the servlet paths resources/ or test-resources/ it makes simplifies this development process by disabling the caching of such resources as well as enabling the resource browsing. To activate the development mode you need to add the following context parameter.

#!text/xml

 <context-param> <param-name>com.sap.ui5.resource.DEV_MODE</param-name> <param-value>true</param-value> </context-param> 

Resource Browsing

In case of having the development mode turned on you can browse resources via the resource browser:

● %SERVER_URL%/resources/ ● %SERVER_URL%/test-resources/

Tunneling a Remote Location

The ResourceServlet offers the opportunity to tunnel/proxy requests to another server providing SAPUI5 resources. This is the alternative instead for referring to SAPUI5 from remote location inside the bootstrap script tag to avoid cross domain issues. To activate this remote location tunneling/proxying you need to add the following context parameter to the web.xml of your application:

#!text/xml <context-param> <param-name>com.sap.ui5.resource.REMOTE_LOCATION</param-name> <param-value>http://%server%:%port%/sapui5</param-value> </context-param>

This will dispatch requests from resources/sap/ui/commons/Button.js to http://%server%:%port%/sapui5/resources/sap/ui/commons/Button.js.

If you are located behind a proxy and the remote location is outside your local network you can configure the proxy settings via the standard Java Networking and Proxy configurations by setting the system properties (for HTTP): http.proxyHost, http.proxyPort, http.nonProxyHosts, or (for HTTPS) https.proxyHost, https.proxyPort, https.nonProxyHosts of your Java runtime environment.

In general for the resources returned from the proxy the ResourceServlet is enabling caching. It by default uses the configured com.sap.ui5.resource.MAX_AGE to avoid to much load on the ResourceServlet.

Verify that a Resource was Retrieved from Remote Location

When in development mode it is possible to verify that a resource was retrieved from the desired remote location by checking the response header of the respective request. In this case the response header has an entry x-sap-ResourceUrl = remote resource URL, for example:

x-sap-ResourceUrl = http://%server%:%port%/sap/public/bc/ui5_ui5/resources/sap-ui-core.js

Resource Packaging

This section describes the resource packaing for web applications and Java modules which could be any kind of a JAR file (SAPUI5 UI library, ...) available in the classpath of the web application.

● For a web application this means you have to store the resources in the following way:

WebContent/ resources/ **/** test-resources/ **/**

● For the SAPUI5 UI libraries we store the resources in the following way:

META-INF/ resources/ **/** test-resources/ **/**

For custom JAR files you need to apply to this on your own.



OSGi Servlet Container

When running SAPUI5 as an OSGi Web Bundle and referencing the UI libraries as OSGi bundles you may need to know about a technical detail how SAPUI5 OSGi bundles are determined:

● In the OSGi servlet container we extend the ResourceServlet by using an OSGi fragment which is responsible to add the OSGi flavor for the determination of UI libaries. Now the ResourceServlet is aware about the OSGi bundles and can search within the OSGi Servlet Container for UI libraries.

● The MANIFEST.MF of UI library JAR files contains a special entry which is used for the determination:

x-sap-ui5-ContentTypes: UILibrary

This is used by the OSGiResourceServlet to determine the relevant UI libraries.

1.4.16.2.1 SAPUI5 Library Location Used for Testing

If the SAPUI5 bootstrap tag contains src="resources/sap-ui-core.js", the SAPUI5 runtime libraries from the Eclipse plugin are used.

If you want to test your SAPUI5 application in Eclipse against a different SAPUI5 Library location, for example on the ABAP server when running in the SAP NetWeaver UI AddOn scenario, you can configure the ResourceServlet. For that, open the web.xml file located in the <WebContent folder name>/WEB-INF folder and configure the parameter com.sap.ui5.resource.REMOTE_LOCATION and com.sap.ui5.resource.PREFER_REMOTE_LOCATION of the ResourceServlet where the placeholders {protocol}, {host name}, {port number}, {path to UI5 library} are to be exchanged by the real protocol, host name, port number and path to the SAPUI5 library, see Resource Handling, section Tunneling a Remote Location.

<servlet> <display-name>ResourceServlet</display-name> <servlet-name>ResourceServlet</servlet-name> <servlet-class>com.sap.ui5.resource.ResourceServlet</servlet-class> </servlet> ...  <context-param> <param-name>com.sap.ui5.resource.PREFER_REMOTE_LOCATION</param-name> <param-value>true</param-value> </context-param>  <context-param> <param-name>com.sap.ui5.resource.REMOTE_LOCATION</param-name> <param-value>{protocol}://{host name}:{port number}/{path to UI5 library}</param-value> </context-param>

1.4.16.3 Cache Buster

A cache buster allows the application to notify the browser to refresh the resources only when the application resources have been changed. Otherwise the resources can always be fetched from the browser's cache.

When you want to cache your resources permanently, you simply need to change the URL in the SAPUI5 bootstrap tag from resources/sap-ui-core.js to resources/sap-ui-cachebuster/sap-ui-core.js.

The cache buster mechanism allows to always put the SAPUI5 resources into the browsers cache until a UI library or a web application has been changed. The default behavior of the SAPUI5 resource handler is either to cache the resources for a specific amount of time or alternatively in development mode it is using the 304/NOT MODIFIED mechanism to check the SAPUI5 resources for being up-to-date. Both mechanisms are not optimal in a final, productive scenario - that is the reason for the implementation of the cache buster mechanism. Applications, which want to use the cache buster mechanism have to explicitly decide to use it.

The cache buster mechanism is part of the resource servlet. In general requests to JavaScript resources can be handled via the cache buster mechanism. Typically this is used for the initial request for the bootstrap JavaScript:

#!text/html

<script type="text/javascript" id="sap-ui-bootstrap" src="resources/sap-ui-cachebuster/sap-ui-core.js" data-sap-ui-libs="sap.ui.core,sap.ui.commons,sap.ui.table" data-sap-ui-theme="sap_goldreflection"></script>

The bootstrap JavaScript will be included via the URL resources/sap-ui-cachebuster/sap-ui-core.js instead of resources/sap-ui-core.js.

Mechanism

The basic mechanism is implemented in the ResourceServlet. For the request to the bootstrap JavaScript it now serves a JavaScript file with the following content:

#!js

(function() { var sTimeStamp = '~20120716-0201~'; var sScriptPath = 'sap\x2dui\x2dcore.js'; var aScriptTags = document.getElementsByTagName('script'); for (var i = 0; i < aScriptTags.length; i++) { if (aScriptTags[i].src) { var iIdxCb = aScriptTags[i].src.indexOf('/sap-ui-cachebuster/'); if (iIdxCb >= 0 && aScriptTags[i].src.substring(iIdxCb + '/sap-ui-cachebuster/'.length) == sScriptPath) { var sBasePath = aScriptTags[i].src.substring(0, iIdxCb); sBasePath += '/' + sTimeStamp + '/'; window["sap-ui-config"] = window["sap-ui-config"] || {}; window["sap-ui-config"].resourceRoots = window["sap-ui-config"].resourceRoots || {}; window["sap-ui-config"].resourceRoots[''] = sBasePath; document.write('<script type="text/javascript" src="' + sBasePath + sScriptPath + '"></script>') break; } } }})();

This script basically ensures that the global SAPUI5 configuration variable (window["sap-ui-config"]) exists, without modifying any existing values. It defines the resource root of SAPUI5 (the location where SAPUI5 loads all JavaScript modules, controls and control related resources from). Finally, another script tag is added to the page



that points to the real boostrap JavaScript. The new resource root and the request path to the bootstrap JavaScript now contain a timestamp. Additionally the cache headers of the reponses now look like the following:

Date: Mon, 16 Jul 2012 05:17:54 GMTExpires: Thu, 14 Jul 2022 05:17:54 GMTCache-Control: max-age=315360000, public

By default all cache buster resources will be cached for one year.

Request Flow

When using the cache buster mechanism, the first request must never be cached because it is being used to determine the timestamp / and to finally redirect to the correct script. The following list explains the flow:

● resources/sap-ui-cachebuster/sap-ui-core.js => NO_CACHE● resources/~201106210204~/sap-ui-core.js =>CACHE

Timestamp

If you are interested in the timestamp of the cache buster, you can grab it with the following request:

resources/sap-ui-cachebuster

The response is text/plain with such value: ~20120716-0201~

1.4.16.4 Application Cache Buster

The Application Cache Buster (short AppCacheBuster) is similar to the Cache Buster but is used for application resources.

Applications provide an index file (created on the fly) containing the last modified timestamps of all included files (scripts, properties – files which we load via XHR programmatically). Technically this file is a mapping between the request path (below the context path of the application) and the last modified timestamp.

The server in general caches all the above resources (not using the 304/not modified mechanism). For the index file we are using the 304/not modified mechanism to avoid to load when it has not been changed.

On the client-side we initially load this file of the application when enabled via configuration option sap-ui-appcachebuster and use this for the XHR requests. If the request path is contained in the above mentioned index file we simply add the timestamp as leading path segment to this request. If the timestamp doesn’t change the URL is unique and therefore it will be taken from cache. Once the file is modified the URL parameter will be changed and therefore loaded again from the backend.

The server has to delete the timestamp from this URL to lookup the file properly. For the Java applications SAPUI5 provides a AppCacheBusterFilter and for ABAP the logic is implemented in the ICF handler. Both backend implementations also generate the index file on-the-fly.



NoteThe Application Cache Buster does not work across application borders. If you require resources from another application they are not loaded via this mechanism.

1.4.16.4.1 Application Cache Buster: Index File

Unlike the cache buster mechanism for runtime resources, the application files have an own timestamp for each file. Thus, the application provides the index file sap-ui-cachebuster-info.json. This file in JSON format includes all files that should use this mechanism. The index file looks as follows:

{ "mvc/MyMVC.view.js": "20120907134005", "mvc/MyMVC.controller.js": "20120907134005", "mvc/MyMVC.view2.js": "20120906113301", "mvc/MyMVC.controller2.js": "20120906113023"}

1.4.16.4.2 Application Cache Buster: Configuration

To activate the Application Cache Buster the configuration data-sap-ui-appCacheBuster="./" must be added to the bootstrap script of the application page:

<script id="sap-ui-bootstrap" src="resources/sap-ui-cachebuster/sap-ui-core.js" data-sap-ui-libs="sap.ui.core,sap.ui.commons,sap.ui.table" data-sap-ui-theme="sap_goldreflection" data-sap-ui-appCacheBuster="./"></script>

The parameter data-sap-ui-appCacheBuster is a string[] which means you can pass a list of base URLs for other applications. By default it should contain the base path of your local application.

These base URLs are used to load the index files. This allows to handle not only the local resources via the Application Cache Buster. Furthermore other applications could then also be handled.

1.4.16.4.3 Application Cache Buster: Request Flow

When using the Application Cache Buster mechanism, the first request must never be cached because it is being used to fetch the index file. The following list explains the flow:

1. http://myserver/myapp/sap-ui-cachebuster-info.json ⇒ NO_CACHE2. http://myserver/myapp/~201106210204~/mvc/MyMVC.view.js ⇒ CACHE

○ http://myserver/myapp/mvc/MyMVC.view.js ⇒ internally resolve to this URL



1.4.16.4.4 Enable the Filter for Java Applications

To enable the server-side part of the Application Cache Buster mechanism the following filter needs to be configured in the web.xml:

  

<filter> <display-name>AppCacheBusterFilter</display-name> <filter-name>AppCacheBusterFilter</filter-name> <filter-class>com.sap.ui5.resource.AppCacheBusterFilter</filter-class> </filter> <filter-mapping> <filter-name>AppCacheBusterFilter</filter-name> <url-pattern>/*</url-pattern> </filter-mapping>

1.4.16.4.5 Application Cache Buster: Enhanced Concept

The first iteration of the Application Cache Buster only supports files which have been loaded via jQuery.ajax. The enhanced concept supports the transformation of URLs for jQuery.sap.includeScript, jQuery.sap.includeStyleSheet, and properties of the type sap.ui.core/URI. This ensures that the Application Cache Buster mechanism takes care about most of the URLs in a general way. Additionally the enhanced concept allows to register components or base URLs which are considered by the Application Cache Buster. This base URL is used to load the index file with the timestamp information.

Registration of external URLs

If you do not specify all the applications in the bootstrap configuration, you can also register them during runtime. To register additional locations, use the following API:

sap.ui.core.AppCacheBuster.register("/sap/bc/my/other/component");

Avoid handling of specific URLs

To avoid handling of specific URLs, you can override the default behavior as follows:

sap.ui.core.AppCacheBuster.handleURL = function(sURL) { return sURL !== "my/specific/url";};

1.4.17 Control Devlopment Topics

The following sections introduce control development topics:

● Developing UI5 Controls in JavaScrip● Handling Events in Controls● Writing a Control Renderer● Focus Handling● Item Navigation● Right-to-Left Support

1.4.17.1 Developing UI5 Controls in JavaScript

The following sections explain how to create new controls in JavaScript on the fly, so-called notepad controls). For this basic development approach you do not need to define libraries or run generation steps. You can extend existing controls and create completely new controls.

This functionality is not restricted to controls: You can also create or extend arbitrary objects derived from sap.ui.base.Object.

Technically, the resulting controls are not different from controls developed with SAPUI5 tools.

Notepad Controls vs. Eclipse-based Controls

Notepad controls have the advantage that you create them very quickly without tools, build, or dependency overhead. You can create them, for example, inline within an application. All JavaScript can be in one file and the application CSS, which may be present anyway, contains the required styles. So notepad controls are a very light-weight approach, but still offering all the features of a real SAPUI5 control.

The control can, however, not be reused easily from different locations and applications: There is no formal way to address it and there is no package which you can reference to import the control. Also, if the control has to support multiple themes and you want to style it by using SAPUI5 theme parameters which are editable in the Theme Editor, if the right-to-left version of the styles should be generated automatically, the Eclipse-based tools offer everything with their integrated build. Checks are not run on a notpad control and no JSDoc documentation can be created.

If a control is supposed to be reused in different applications or by people who do not closely communicate with the control developer, and if a control is more complex than a very basic control, we recommend to consider formally creating a Control Library and using the SAPUI5 Eclipse to create the controls.



1.4.17.1.1 Basic Concept: Extend MethodThe extend() method is available on all controls (and the base classes) and is used to define a new subclass. The following code creates a new control from scratch:

sap.ui.core.Control.extend(...)

The following code creates a new control which inherits from Button:

sap.ui.commons.Button.extend(...);

The function has the name and the definition of the new control type as parameters. The definition contains information about the control API, that is, the properties, aggregations, events and so on, as well as the implementation of the control methods. In addition to that it provides the function that creates the control's HTML structure.

NoteSAPUI5 creates some methods automatically, such as the getters and setters for properties and aggregations or methods for attaching/detaching event handlers. You can in fact develop a non-default implementation that provides more or other functionality.

1.4.17.1.2 A First Basic ExampleThe following code creates a simple control with a name property. The purpose of the control is to render the text "Hello <name>":

#!js

sap.ui.core.Control.extend("my.Hello", { // call the new Control type "my.Hello" // and let it inherit from sap.ui.core.Control metadata : { // the Control API properties : { "name" : "string" // setter and getter are created behind the scenes, // including data binding and type validation } },

renderer : function(oRm, oControl) { // the part creating the HTML oRm.write("<span>Hello "); oRm.writeEscaped(oControl.getName()); // write the Control property 'name', with XSS protection oRm.write("</span>"); }});

The new control is ready for use now. It can be instantiated and displayed as usual:

#!js

new my.Hello({name:"UI5"}).placeAt("content");



1.4.17.1.3 Technical Background

A control is an object that defines the appearance and the behavior of a screen area.

A control has properties, such as "text" or "width". These properties modify the appearance or relate to the data displayed by the control. A control can aggregate other controls: It serves as a sort of container or layout control where the application can add child controls or as a composite control if the control adds child controls and just reuses available components. A control can also have associated controls that are not part or children of this control, but rather loosely related.

A control can fire well-defined events. The meaning of these events typically relates to the control's purpose and functionality and is on a semantically higher level than "click" or other browser events. Examples for such events are triggerSearch in a search field or collapse in a panel.

This information is defined in the control metadata which is the public API of the control and can be queried at runtime and also contains useful information for runtime features like data binding and type validation checks.

Control Base Class

sap.ui.core.Control is the base class of all SAPUI5 controls. Specific controls can either inherit from this base class or from another control to inherit and extend the functionality. sap.ui.core.Element is the base class of sap.ui.core.Control. Elements can be like parts of controls or rather configuration packages for parts of controls, but in general they are not meant for standalone use and do not have their own renderer. The controls that use these elements do the rendering, for example, a ListItem element is rendered by the ListBox control. Whatever this page documents about controls, it usually also applies to Elements (but not to the renderer).

Control Name

The control name is a string that consists of Library name and control name. For both names, you use letters and dots for separation where you should avoid dublicates regarding other JS entity namings within the same application. It is also possible that you omit the library name and call the control Square. You would generally do this if you there is no need for assigning the control to a library which shall also be available

for developing other applications. When you write a control to be reused by others, a unique Library name is recommended: sap.byd.Square.

Control Metadata

For the creation of new controls, the metadata block defines the properties, aggregations, events etc. of the control. Depending on the control, not only the number of entries, but also their amount of information can be small or quite extensive.

For the use case class extension - where the classes do not inherit from control or Element but from a more generic class - these control-specific settings are not available. For more information, read chapter "Object



Metadata and Implementation" below. Note that all the object metadata described there is also applicable for extending controls.

Properties

A property is defined by at least its name and its type. Additionally, the default value of the property can be defined. So the available settings are:

● type: The data type of the control property. Automatic type validation is done in the UI5 core. Examples for valid types are:

○ string for a string property (default)○ int or float for number properties○ int[] etc. for arrays○ sap.ui.core.CSSSize for a custom-defined type

● defaultValue: The default value this property should have when the application does not set a value. If no default value is given, the property initially has value undefined.

So property definitions can look like this:

#!js

properties: { "title" : "string", // a simple string property, default value is {{{undefined}}} "buttonText" : {defaultValue: "Search"}, // when no type is given, the type is {{{string}}} "showLogoutButton" : {type : "boolean", defaultValue : true}, // a boolean property where a default value is given "width" : {type : "sap.ui.core.CSSSize", defaultValue : "50px"} // a CSS size property where a default value is given}

From the technical point of view, you could also define the "group" (the category into which this property falls), but this has no impact outside of development tools which may want to display and group the properties of your control.

Once such a property is defined, the control automatically has the methods setShowLogoutButton and getShowLogoutButton, which are responsible for storing the data. You can give your own custom definition for either of them, you have to call the generic property setter/getter setProperty/ getProperty then.

Events

Events are specified by the event name only. In many cases there is nothing to configure about them, so just give an empty object:

#!js

events: { "logout": {}}



As an advanced feature, controls can enable events to be interrupted by the application, when usually the control would immediately execute an action. For example, if a Tab control fires a "close" event and wants to enable the application to cancel the closing. To do so, the control needs to set the enablePreventDefault property of the Event to "true" (and check the return value after firing the event):

#!js

events: { "close": {enablePreventDefault : true} }

For every defined Event, methods for registering, de-registering and firing the event are created, in this case: attachLogout, detachLogout, fireLogout.

Aggregations and Associations

Aggregations and associations are again defined by their name, along with an object that can have the following information:

● type: This should be a type which is subclass of Element or control (default is sap.ui.core.control)● multiple: Whether it is a 0..1 aggregation or a 0..n aggregation (default is "true", which means 0..n, for

aggregations and "false" for associations)● singularName: For 0..n aggregations, the aggregation name typically is plural, but certain methods are

created where the singular form is required (for example, addWorksetItem} for the "worksetItem' s'" aggregation).

If only the type needs to be set, you can just give it as a string instead of the configuration object.

One example:

#!js

aggregations: { "acceptButton" : "sap.ui.commons.Button", // if only type is given, no object is required "content" : {singularName: "content"}, // default type is "sap.ui.core.Control", // which is appropriate for generic containers "worksetItems" : {type : "sap.ui.ux3.NavigationItem", multiple : true, singularName : "worksetItem"} // a fully specified aggregation}

Multiple methods are created, depending on the multiplicity, for example: getWorksetItems, insertWorksetItem, addWorksetItem, removeWorksetItem, removeAllWorksetItems, indexOfWorksetItem, destroyWorksetItems

If you want to mark one aggregation as default aggregation (in order to be able to omit the aggregation tag in XMLViews), you can do this by setting the defaultAggregation property to the name of the aggregation as follows:

aggregations: { "content": {singularName: "content"} // default type is "sap.ui.core.Control", multiple is "true"



},defaultAggregation: "content"

Methods

You can add any method to a new control by providing the implementation, without adding it to the metadata. By convention, all methods are public, exception here is if their name starts with an underscore, or if it is one of the special method types listed below.

Other controls and the application may only call public methods and the control needs to ensure they remain compatible. Though, there are no technical rules that prevent a call of private methods.

Public methods are the generated getter/setter methods for properties etc.

1.4.17.1.4 Control Implementation

After the metadata is defined, you can add any method implementations to your new control. In general, the method names can be chosen freely, but note that some method names must be avoided:

● Names of methods that are provided by a super class (or will be provided...). Your implementation overwrites their's, that's the deal with inheritance.

● set.../get.../insert.../add.../remove.../indexOf... may collide with setters/getters for properties or aggregations you defined

● attach.../detach.../fire may collide with methods created for events

As long as you do not introduce the respective property or so, you are of course safe to use a certain "set..." method name.

There are some method names you may use, but which have a special meaning:

● on...: Methods starting with "on" are event handlers that are automatically bound to browser events● init: Is the name of the initialization function called right after Control instantiation● renderer: Is a special name that holds either● the function that creates the Control's HTML or● a complete structure that contains this function and more (for more information see below)

Normal Methods

Any method, either public or private, is just appended to the implementation object. The convention is that private methods that may not be called from outside a Control start with an underscore. All other methods are considered public as long as they do not belong to the special method types listed below.

#!js

divide: function(x, y) { // a public method of the Control



if (this._checkForZero(y)) {

throw new Error("Second parameter may not be zero");

}

return x / y;

},

_checkForZero: function(y) { // private helper method

if (y === 0) {

return true;

}

return false;

}

init() Method

The init() method is invoked by the SAPUI5 core for each control instance right after the constructor. Use this to set up things like internal variables or sub-Controls of a composite. Note that any values given in the control constructor are NOT yet available! This is intentional to prevent the typical error where controls would only work fine when values are set initially, but not when values are changed later. This method is considered private and only to be called by the SAPUI5 core.

#!js

init: function() {

this._bSearchHasBeenTriggered = false;

this._oSearchButton = new sap.ui.commons.Button(this.getId() + "-searchBtn", {text: "Search"});

}

Event Handler Methods

Methods that have a name starting with "on" are reserved for event handlers. For common events such as "click" or "keydown", browser event handlers for these methods are registered automatically by the SAPUI5 core. So it is sufficient to simple add a handler method, and it will automatically be called. Additionally, the SAPUI5 core fires events with a richer semantic meaning, so control developers do not need to check so many keycodes etc. The name of these events starts with "sap", they are defined in jquery.sap.events.js. One example for such an event is sapnext which is triggered by "arrow down" or "arrow right" (or "arrow left" in right-to-left mode). Therefore, multiple checks would be required to check whether the user wants to navigate to the next item. The



sapnext event takes over all these checks. The "evt" object given to the handler method contains more information. These methods are considered to be private and may only be called by the UI5 core.

#!js

onclick: function(evt) {

alert("Control " + this.getId() + " was clicked.");

},

onsapnext: function(evt) {

// navigate to next item, an arrow key was pressed

...

}

Renderer Method / Object

This method is responsible for creating the HTML structure that makes up the control. It is different from the other methods, as it is a static one, so the "this" keyword is not available. Instead, a control instance and a RenderManager instance are given to the method. The RenderManager is used as a sort of "writer" - it is a collector for string fragments and takes care of efficiently concatenating them and placing them into the appropriate DOM position.

#!js

renderer: function(rm, oControl) { oRenderManager.write("<div>", oControl.getText(), "</div>");}

All the features and rules of writing the control Renderer in normal control development apply here as well. The control must, for example, only have one HTML element as root node and inside this node oRenderManager.writeControlData(oControl); must be called, so this root element can be marked as UI5 control root and the ID of the control is written.

The newly created renderer type will inherit from the renderer of the parent control. So if your new control extends TextField, the given function will be added to a class that inherits from sap.ui.commons.!TextFieldRenderer (and will have access to that one's other functions).

If an existing renderer should be used without modification, you can give the name of this renderer class:

#!js

renderer: "sap.ui.commons.ButtonRenderer"

However, a normal control renderer can also override or implement methods from its renderer superclass. Or just separate out some helper functions.

This is possible as well here, but in this case these methods need to be packed together into an object, so the extend method knows they should all go into the control renderer. The main rendering method is called "render" -



just like in a normal control renderer. The keyword "this" actually refers to the Control Renderer type here, so it is used to access the other methods:

#!js

renderer: {

render: function(rm, oControl) {

rm.write("<div>");

rm.writeEscaped(this.square(oControl.getValue()));

rm.write("</div>");

},

square: function(value) {

return value * value;

}

}

1.4.17.1.5 Object Metadata and Implementation

For extending plain objects that are not elements or controls, only the following metadata is available (it is also available for extending controls, though!):

● "interfaces": an optional array of strings that denotes the implemented interfaces● "publicMethods": an optional list of methods that should be part of the public API. By default all methods that

do not start with an underscore are public.● "abstract": an optional flag to mark the type as abstract● "final": an optional flag to mark the type as final

Regarding the implementation, all methods given outside the metadata are attached to the new type. There is one reserved method name: "constructor". The function given under this name will be the constructor of the new class. While technically you can also define a constructor for new elements and controls, you should not do it. Your control may otherwise break in certain scenarios like with list bindings, or may break later when UI5 extends the constructor signature.

1.4.17.1.6 Examples for Creating New Controls

To create an entirely new control type, you extend the sap.ui.core.Control class. You define the control API and the implementation from scratch.



Simple "Square" Control

A "Square" control that is rendered as a red square and has some text written inside and pops up an alert when clicked, looks like this:

#!js

sap.ui.core.Control.extend("Square", { // call the new Control type "Square" and let it inherit // from sap.ui.core.Control

// the Control API: metadata : { properties : { // setter and getter are created behind the scenes, // incl. data binding and type validation "text" : "string", // in simple cases, just define the type "size" : {type: "sap.ui.core.CSSSize", defaultValue: "200px"} // you can also give a default value and more } },

// the part creating the HTML: renderer : function(oRm, oControl) { // static function, so use the given "oControl" instance // instead of "this" in the renderer function

oRm.write("<div"); oRm.writeControlData(oControl); // writes the Control ID and enables event handling - important! oRm.addStyle("width", oControl.getSize()); // write the Control property size; the Control has validated it // to be a CSS size oRm.addStyle("height", oControl.getSize()); oRm.writeStyles(); oRm.addClass("mySquare"); // add a CSS class for styles common to all Control instances oRm.writeClasses(); // this call writes the above class plus enables support // for Square.addStyleClass(...)

oRm.write(">"); oRm.writeEscaped(oControl.getText()); // write another Control property, with protection // against cross-site-scripting oRm.write("</div>"); },

// an event handler: onclick : function(evt) { // is called when the Control's area is clicked - no event registration required alert("Control clicked! Text of the Control is:\n" + this.getText()); } });

The control definition and implementation is finished now, but some styling remains to be done.

The visual appearance could have been written to the control HTML in the renderer method, just like the instance-specific width and height was written. But it is better to define style that is common to all control instances in a CSS file, or at least in a <style> tag, so it only needs to be written once and it can be easily modified by the application.



So we add a grey background, a red border and some alignment stuff:

#!css

<style> .mySquare { /* style the CSS class that has been written by the renderer method */ display: inline-block; /* enable squares to appear next to each other within one line */ border: 1px solid red; /* add some border, so the square can actually be seen */ background-color: #ddd; padding: 8px; text-align: center; -moz-box-sizing: border-box; /* consider padding+border part of the width/height */ box-sizing: border-box; }</style>

Use

This custom control can now be used like any SAPUI5 control:

#!js

var myControl = new my.Square({text:"Hello", size: "100px"});myControl.placeAt("content");

Simple Container Control

A container control that can hold arbitrary child controls and renders them in a row, with a colored box around each child, looks like this:

#!js

sap.ui.core.Control.extend("ColorBoxContainer", { // call the new Control type "Square" // and let it inherit from sap.ui.core.Control

// the Control API: metadata : { properties : { // setter and getter are created behind the scenes, // incl. data binding and type validation "boxColor" : "string" // the color to use for the frame around each child Control }, aggregations: { content: {singularName: "content"} // default type is "sap.ui.core.Control", multiple is "true" } },

// the part creating the HTML: renderer : function(oRm, oControl) { // static function, so use the given "oControl" instance // instead of "this" in the renderer function



oRm.write("<div"); oRm.writeControlData(oControl); // writes the Control ID and enables event handling - important! oRm.writeClasses(); // there is no class to write, but this enables // support for ColorBoxContainer.addStyleClass(...) oRm.write(">");

var aChildren = oControl.getContent(); for (var i = 0; i < aChildren.length; i++) { // loop over all child Controls, // render the colored box around them oRm.write("<div>"); oRm.addStyle("display", "inline-block"); oRm.addStyle("border", "3px solid " + oControl.getBoxColor()); // specify the border around the child oRm.writeStyles(); oRm.write(">");

oRm.renderControl(aChildren[i]); // render the child Control // (could even be a big Control tree, but you don't need to care)

oRm.write("</div>"); // end of the box around the respective child }

oRm.write("</div"); // end of the complete Control } });

There is no additional CSS required, as the Control has no appearance on its own, but basically consists of its children and the boxes around them.

Use

This strange container control can now be used like any SAPUI5 container:

#!js

var btn = new sap.ui.commons.Button({text:'Hello World'}); var tf = new sap.ui.commons.TextField({value:'edit text here'});

var container = new ColorBoxContainer({ boxColor: "#ff7700", content:[ btn, tf ]}); container.placeAt('content');

1.4.17.1.7 Examples for Extending Existing Controls

The following sections are examples of extending existing controls.



Extendig the Button with an Additional Event

Let's build a new control, named "HoverButton" that is just like the normal button, but fires a "hover" event in addition when the mouse enters its area.

#!js

sap.ui.commons.Button.extend("HoverButton", { // call the new Control type "HoverButton" // and let it inherit from sap.ui.commons.Button metadata: { events: { "hover" : {} // this Button has also a "hover" event, in addition to "press" of the normal Button } }, // the hover event handler: onmouseover : function(evt) { // is called when the Button is hovered - no event registration required this.fireHover(); },

renderer: {} // add nothing, just inherit the ButtonRenderer as is; // In this case (since the renderer is not changed) you could also specify this explicitly with: renderer:"sap.ui.commons.ButtonRenderer" // (means you reuse the ButtonRenderer instead of creating a new view });

Use

Use this ToggleButton in an application just like a regular button - but you can now attach a handler to the "hover" event.

#!js

var myControl = new HoverButton("myBtn", { text: "Hover Me", hover: function(evt) { alert("Button " + evt.getSource().getId() + " was hovered."); } });

myControl.placeAt("content");

Extending the TextField Rendering

This example builds a new control type that inherits from TextField and has all its features, but changes the rendering to be very highlighted with yellow background.

The control API and even the "render" method can be inherited as is. You only overwrite the renderInnerAttributes method of the TextFieldRenderer:

#!js

sap.ui.commons.TextField.extend("HighlightField", { // call the new Control type



"HighlightField" // and let it inherit from sap.ui.commons.TextField

renderer: { // note that NO render() function is given here! The TextField's render() function is used. // But one function is overwritten: renderInnerAttributes : function(oRm, oTextField) { oRm.addStyle('background-color', '#ffff00'); // this change could also be done with plain CSS!! // But you get the idea... } } });

Use

Use this HighlightField in an application just like a regular TextField. It has all the normal features and behavior. But it has the modified rendering.

#!js

var myControl = new HighlightField({value:"Highlighted editing"});myControl.placeAt("content");

1.4.17.2 Handling Events in Controls

Two types of events exist in SAPUI5 applications:

● Events fired by the browser; these events are well-known, for example "click" and "blur"● Events fired by SAPUI5 controls; these events are usually semantically richer and related to the control

functionality; for example a browser-level "click" on the respective icon in a panel header that triggers a "maximize" or "minimize" event

Applications can listen to both types of events.

The following sections describe how control implementations can use browser events (type 1) to implement their behavior and to eventually fire control events (type 2).

Registering for Browser Events

When a control needs to react on browser events, there are two ways to register for the events, the "standard" way and an "optimized SAPUI5" way:

● Explicitly register for browser events on certain DOM elements, typically using jQuery.bind() (using the respective browser methods like addEventListener would also be possible).The event registration must be done in the onAfterRendering method of the Control, so the event binding is always repeated after the control is re-rendered (new DOM elements are created and old ones are discarded). Furthermore, to prevent memory leaks, the event binding must be removed (with jQuery.unbind()) in the "onBeforeRendering" method and in the "exit" method (which is called before the control is destroyed).



○ Pro:ANY type of browser event can be handledWorks exactly like in any web page or jQuery-based web application

○ Con:Quite some code required to do the binding and unbinding of the event handlerRegistering many event handlers can affect performance

Example:

MyControl.prototype.onAfterRendering = function() {

this.$().bind("click", jQuery.proxy(this.handleClick, this)); // could also be: jQuery.sap.byId(this.getId).bind("click", jQuery.proxy(this.handleClick, this)); }

MyControl.prototype.onBeforeRendering = function() { this.$().unbind("click", this.handleClick); }

MyControl.prototype.exit = function() { this.$().unbind("click", this.handleClick); }

MyControl.prototype.handleClick = function(oEvent) { // do something... }

● Just implement the event handler for certain "common" event types, using a name convention for the handler method.SAPUI5 automatically registers event handlers for a list of commonly used event types on the root element of a complete tree of SAPUI5 controls. If the respective event occurs anywhere in the tree and the respective Control implements the on<eventName> method, this method is invoked as if it had been registered with jQuery.bind().

○ Pro:Saves Control codeSaves number of event handler registrations in the DOMSaves evet handler registrations and deregistrations executed on every re-rendering

○ Con:Only works for a certain (comprehensive) list of events

Example:

MyControl.prototype.onclick = function(oEvent) { // do something...}

As you can see from these examples, the SAPUI5 event handling functionality saves code.

List of Supported Browser Events

The following events are available to be handled by just implementing an "on<eventName>" method (list is also available via API, see JSDoc of jQuery.sap.ControlEvents):



● click● dblclick● dragend● dragenter● dragleave● dragover● dragstart● drop● focusin● focusout● keydown● keypress● keyup● mousedown● mouseout● mouseover● mouseup● paste● select● selectstart

Pseudo Events

In addition to the native browser events listed above, SAPUI5 also creates so-called "pseudo events" which are semantically enriched, but can also be handled implementing an on<eventName> method. So they "feel like" browser events (but they cannot be used with jQuery.bind()).

These events help avoiding additional checks for modifier keys in the event handler or checking for certain keycodes.

The complete documentation of these events can be found in the JSDoc of jQuery.sap.PseudoEvents. The list is as follows:

● sapbackspace● sapbackspacemodifiers● sapbottom● sapcollapse● sapcollapseall● sapcollapsemodifiers● sapdecrease● sapdecreasemodifiers● sapdelayeddoubleclick● sapdelete● sapdeletemodifiers● sapdown



● sapdownmodifiers● sapend● sapendmodifiers● sapenter● sapentermodifiers● sapescape● sapexpand● sapexpandmodifiers● saphide● saphome● saphomemodifiers● sapincrease● sapincreasemodifiers● sapleft● sapleftmodifiers● sapnext● sapnextmodifiers● sappagedown● sappagedownmodifiers● sappageup● sappageupmodifiers● sapprevious● sappreviousmodifiers● sapright● saprightmodifiers● sapselect● sapselectmodifiers● sapshow● sapskipback● sapskipforward● sapspace● sapspacemodifiers● saptabnext● saptabprevious● saptop● sapup● sapupmodifiers

1.4.17.3 Writing a Control RendererFor control rendering purposes, the following three classes are relevant:

● The control class - the control that is to be rendered● The RenderManager class - responsible for injecting the generated markup into the DOM and offering helper

functionality



● The renderer class - the base class of all control renderers

Control Class sap.ui.core.Control

In general, a control is made up of its properties, events, aggregations, associations, and methods. Together, these parts define the behavior of a Control. The following information is relevant for the appearance and data of the control: properties, associations, and aggregations. This information can be accessed directly with get and set methods of the control during the render() method.

Property Access:

// var oValue = oControl.get<Property>();// for example for the 'text'-propertyvar oValue = oControl.getText();

1..1 Aggregation Access:

// var oAggregation = oControl.get<Aggregation>();// for example for content-aggregationvar oAggregation = oControl.getContent();

1..n Aggregration Access:

// var aAggregations = oControl.get<Aggregation>s();// for example for rows-aggregationvar aAggregations = oControl.getRows();

Association Access:

// var sAssociatedControlId = oControl.get<Association>();// for example labelFor-associationvar sAssociatedControlId = oControl.getLabelFor();

RenderManager Class sap.ui.core.RenderManager

The RenderManager is responsible for injecting the generated markup into the DOM. It takes a control, determines and loads the corresponding renderer, and finally delegates the rendering of the control to the renderer. It also offers helper functionality for rendering purposes as follows:

Method Description

write() Writes string information to the HTML

writeControlData() Writes the ID and the recognition data of the control to the HTML

renderControl() Converts the specified control into HTML representation and adds it to the HTML. Use this for rendering child controls.

For further details, see the JSDoc of the RenderManager.



Renderer Class sap.ui.core.Renderer

The Renderer implements the static render method that is called when a control is added to the DOM. The RenderManager executes the render method on the corresponding Renderer for the control to be rendered, and passes the reference to itself and the control.

The following code snippet shows the implementation of a simple renderer:

/** * This module provides the renderer for the MyControl control */

jQuery.sap.declare("sap.ui.myuilib.MyControlRenderer");

/** * @class MyControl renderer. * * @author SAP - TD Core UI&AM UI Infra * @version @version@ * @static */

sap.ui.myuilib.MyControlRenderer = {};

/** * Renders the HTML for the given control, using the provided {@link sap.ui.core.RenderManager}. * * @param {sap.ui.core.RenderManager} oRenderManager The RenderManager that can be used for writing to the RenderOutputBuffer. * @param {sap.ui.core.Control} oControl An object representation of the control that should be rendered */

sap.ui.myuilib.MyControlRenderer.render = function(oRenderManager, oControl) {

// write the HTML into the render manager oRenderManager.write("<span "); oRenderManager.writeControlData(oControl); oRenderManager.write(" class=\"sap-ui-myuilib-MyControlRenderer\" "); oRenderManager.write("></span>");

};

Prevention of Cross-Site Scripting (XSS)

You can find some basic facts about Cross-Site Scripting (XSS).

XSS in SAPUI5 Controls

You must ensure that an attacker cannot inject script code into an application page as it runs in a user's browser. From a controls perspective, this means prohibiting controls from writing any scripts to the page that comes from the application, or might have come from business data saved by a different user. This is achieved by a combination of two measures:



● ValidationThe validation of typed control properties means that as soon as a control property has a type other than string, the Core validates the value against this type when the application sets it. In this way, an int is always guaranteed to be an int, and a sap.ui.core/CSSSize is a string representing a CSS size (and not containing a script tag). This is also the case for enumerations and control IDs. The control renderer can rely on this check when writing the HTML.

● EscapingEscaping of string control properties and any other values coming from the application. This is the responsibility of the control developer when creating the renderer. The RenderManager and the Core offer helper methods for this (see below).

Avoiding XSS for your New Renderer

To ensure maximum security for your new renderer, follow the steps described below:

● Use the type sap.ui.core/CSSSize instead of string (or sap.ui.core/string) for control properties that refer to a CSS size.The more general rule is to use the most specific type for control properties that is available.

● If the value of a string property is written to the HTML, it must be escaped using one of the helper methods:

○ For writing plainly to the HTML, use writeEscaped(oControl.getSomeStringProperty()) instead of just write(...).

○ For writing attributes, use writeAttributeEscaped("someHtmlProperty", oControl.getSomeStringProperty()) instead of just writeAttribute(...).

○ For any usages of string properties where the above is not possible, use jQuery.sap.escapeHTML(oControl.getSomeStringProperty()) to escape the string and then process it further.

● Carefully check the HTML coding you are writing and consider whether any application value might make its way to the HTML.

○ Check where the variable values come from (can the application set its value directly, or only decide which of certain hardcoded values are used?).

○ Parameters in method calls of controls are (currently) not validated by the Core, so values given there are candidates for extra escaping.

○ Always keep in mind that XSS can happen anywhere and anytime in CSS classes, or in styles, for example.

1.4.17.4 Focus Handling

Each of the controls provided by the SAPUI5 framework has its own behavior for focus handling, depending on the functionality that is provided by the control. The highest level of complexity is reached in the case of complex controls and their embedded content.

For custom development of controls, the core of the framework provides mechanisms for observing the moving focus in an application page and preserves this information for refocusing elements after (re-)rendering. Furthermore, the focus triggers event firing. Due to the high degree of flexibility in control rendering, it may be necessary to implement functionality tailored to the control's inner workings. The following sections provide some insights into how to tailor this functionality.



The framework provides helper functions for implementating focus handling.

Implementing Focus Handling When Developing Controls

The base class for all elements (Element.js) provides four methods to help you implement focus handling:

● Element.getFocusDomRef()● Element.focus()● Element.getFocusInfo()● Element.applyFocusInfo(oFocusInfo)

Element.getFocusDomRef()

Once a visible element is rendered, it has a Document Object Model (DOM) representation. The root DOM node can be accessed by using the method getDomRef() on the element. The root DOM node is the default focused DOM node. After rendering, the framework asks the control for its focus DOM node by using the getFocusDomRef() method. If the root DOM node does NOT represent the element that should have the focus, you have to return another DOM node by overriding the getFocusDomRef() method.

Element.focus()

The focus() method sets the focus on the element. This is done using the focus DOM node.

Element.getFocusInfo()

With some controls, it is even more difficult to apply the focus once the control has been re-rendered. Controls such as lists have their own internal focus handling, which sets the focus on the different items. A data table moves the focus over a matrix of cells. The requirement is that a control can apply the focus to its exact previous position after re-rendering. To provide this functionality, you override the getFocusInfo() method, and serialize the focus state into a JSON object and return it. Before rendering, the render manager calls this method for the element instance and stores this information for future use. After rendering, it calls the method applyFocusInfo() (see next method) and passes back this serialized object. The cursor position of a TextField control, for example, can also be stored in such an object.



Element.applyFocusInfo(oFocusInfo)

The applyFocusInfo() method applies the focus to the element after re-rendering. You use this method if different behavior is expected for the element. Note that the default implementation sets the focus as it is implemented in the focus() method (see above).

Example

In our example, a control usually sets the focus on the second child node of its root node. In this case, you would simply override the getFocusDomRef() method.

sap.ui.commons.<SampleControl>.getFocusDomRef = function() { return this.getDomRef().firstChild.nextSibling;}

Another control generally sets the focus back to the element that previously had the focus. Therefore, it overrides the methods getFocusInfo and applyFocusInfo.

sap.ui.commons.<SampleControl>.getFocusInfo = function() { return {id:this.getId(),idx:this.<myFocusElementIndex>};}

sap.ui.commons.<SampleControl>.applyFocusInfo = function(oFocusInfo) { var oDomRef = this.getDomRef(); if (oDomRef) { this.<myFocusElementIndex> = oFocusInfo.idx; this.focus(); }}

Convenience Functionality

In addition to the automatic focus handling provided by the interaction between the render manager and the element instance, further focus-related functionality is available in sap.ui.util.Dom:

Dom.focus(oDomRef)

focus(oDomRef) can be used to focus a particular DOM element. This could be useful in the abovementioned custom focus handing scenario, for controls that cannot be handled by the default behavior of the focus() method or delegates such as ItemNavigation.



Dom.hasFocus(oDomRef)

hasFocus(oDomRef) focuses a particular DOM element. It returns true if focusing could be performed and false if not, for example, because the element status was invisible.

NoteMethod naming may change in the future.

Dom.refocus(oDomRef)

refocus(oDomRef) refocuses a particular DOM element. This might be necessary for screen readers, for example, if the element is not read correctly.

Dom.getActiveElement()

getActiveElement() returns the active element (the currently focused element) of the document, if there is one. This information is also used by automatic focus handling during the re-rendering as described above.

1.4.17.5 Item Navigation - Supporting Keyboard Handling in List-like Controls

One common pattern for keyboard navigation is the item navigation in lists. The UI development toolkit for HTML5 therefore provides a helper class sap.ui.core.delegate.ItemNavigation that implements this functionality. It is intended to be used as a delegate for the keyboard events occurring inside the using control.

Each control that needs the ability to navigate with arrow keys over a one dimensional list of DOM nodes can use this delegate.

The delegate hooks into the browser events for arrow up/down/left/right, page up/down and home/end keys. With a list of DOM nodes provided by the control it sets the focus to the right DOM node in the list while handling the events.

In order to use this item navigation handling, the control needs to provide a DOM node that surrounds all DOM nodes of the items as well as a list of all the DOM nodes of the items themselves. The surrounding DOM node should initially get the focus when the control is entered to ensure the ItemNavigation delegate can do proper focus handling.

Via the methods setCycling the developer can choose whether the focus automatically moves to the top after the end of the list was reached. The page up/down keys will only work if the control developer sets a page size via setPageSize method on the delegate.



Some controls also have one currently selected item in the list that initially should get the focus when the control is entered (again). With the setSelectedIndex method the control can specify such a preselected item for the delegate. If no selected index is given the first item will get the focus when entering the control.

If the control needs to be triggered before it will be focused by the item navigation, it can handle the events BeforeFocus respectively AfterFocus, to do e.g. preparation tasks for the controls visibility etc.

Using this delegate will save your control about 100 lines of JavaScript code for keyboard handling.

If you like you can still react on the events handled by the delegate in your control.

Integrating the ItemNavigation in your Control

A delegate should be applied in the onAfterRendering hook of a control and besides that should be applied only once:

sap.ui.commons.ListBox.prototype.onAfterRendering = function () { //Collect the dom references of the items var oFocusRef = this.getDomRef(), aRows = oFocusRef.getElementsByTagName("TR"), aDomRefs = []; for (var i=0;i<aRows.length;i++) { aDomRefs.push(aRows[i].firstChild); } //initialize the delegate add apply it to the control (only once) if (!this.oItemNavigation) { this.oItemNavigation = new sap.ui.core.delegate.ItemNavigation(); this.addDelegate(this.oItemNavigation); }

// After each rendering the delegate needs to be initialized as well.

//set the root dom node that surrounds the items this.oItemNavigation.setRootDomRef(oFocusRef);

//set the array of dom nodes representing the items. this.oItemNavigation.setItemDomRefs(aDomRefs);

//turn of the cycling this.oItemNavigation.setCycling(false);

//set the selected index this.oItemNavigation.setSelectedIndex(this.getSelectedIndex());

//set the page size this.oItemNavigation.setPageSize(this.getVisibleItems()); };

Ensure that the delegate is also correctly removed after the control is destroyed. Otherwise memory will leak because DOM nodes are still referenced by the delegate.

sap.ui.commons.ListBox.prototype.destroy = function() { if (this.oItemNavigation) { this.removeDelegate(this.oItemNavigation); this.oItemNavigation.destroy(); } };



1.4.17.6 Right-to-Left Support in Controls

Right-to-left support is defined as follows:

● Unicode defines the directionality of characters which the browser must take into account when arranging characters as words.

● The HTML "dir" attribute overrides the overall directionality of blocks (and influences the text alignment if not explicitly set). In detail there are many more effects, e.g. parentheses are mirrored and viewed as a "word" on their own, which changes their position.

● The HTML "lang" attribute does NOT influence text directionality.● document.dir can be used (browser support is there, it can be set in the bootstrap already, but webkit seems

to reset this to LTR, if set too early).● There is a <BDO> HTML tag which turns off the bidirectional algorithm, i.e. the character order is not reversed

if RTL and LTR words are mixed.● CSS 2.1 has also a "direction" property.

This means in a nutshell:

● Each character inherently belongs to a RTL or LTR script (defined by Unicode). Some characters like parentheses and dots have no inherent directionality. Browsers know all of this.

● For single "words" (characters sequences with same directionality) the browser knows the text direction, and does it "right" automatically, handling them as sort of blocks that get their internal text direction only from the used characters.

● These words/sequences/"runs" are separated by the direction-neutral characters like parentheses and dots - and obviously when character directionality changes.

● The direction in which these blocks are put next to each other depends on the base direction.● The default base direction of HTML is left-to-right, but can be inverted by setting the attribute "dir='rtl'", either

on the <html> tag or on any subregion which should have a different base direction.● This base direction also determines the default text alignment, the order of columns in tables and the

presentation of some direction-neutral characters: opening parentheses are still opening parentheses when RTL mode is switched! This means they render horizontally flipped.

● The algorithm for ordering words/runs/blocks according to the base direction only covers one level of mixed directionality. To achieve deeper nesting, spans with dir attribute can be used o define a subcontext with different base direction.

● While (as said above) words/runs internally always have the text direction implied by the used characters, this behavior can also be overridden (using the <bdo> tag or via CSS unicode-bidi:bidi-override) when the order of characters must follow the base direction regardless of the inherent character direction. E.g. because the characters do not form a word but are really just a list of characters, such as in a part number.

● The "lang" attribute defining the document language does not have any influence on directionality.

SAPUI5 Theming Concept - Right-to-Left Support

The UI development toolkit for HTML5 (SAPUI5) theming concept defines RTL support to be achieved as follows:

● All controls are styled for the LTR case in their "normal" CSS files● Images are put into/below the "img" subfolder



● The CSS generator includes an RTL flipping algorithm (inherited from previous SAP UI technologies, proven over many years, similarly also used in the Open Source community, see CSSJanus):

○ border-left: is converted to border-right:, padding: 1px 2px 3px 4px; is converted to padding: 1px 4px 3px 2px;, float:left; is converted to float:right; etc. The assumption and experience is that this automated conversion does almost the whole job.

○ Most CSS properties, including CSS3 ones are supported● CSS generation also mirrors all images inside the "img" folder, as this has been found to be the right thing in

most casesSome images should not be mirrored for RTL. The RTL version of those images must then be put into the "img-RTL" folder with the same location and name. In this case the image reference in the CSS is modified to point to this image.

● A control should NOT write any special CSS classes to "notify" the CSS that RTL is turned onIn CSS the <HTML> tag's dir attribute can be checked to provide specific RTL style.

NoteThe written style is still mirrored in the actual RTL case.

Example:

html[dir=rtl] .sapUiBtn { color: red; }

However, this should only be required in rare cases. If you find yourself writing this kind of style more than 1-3% of the time, you should have another look at what SAPUI5's automatic CSS mirroring offers.

Programmatic Access to RTL

Some controls need to provide specific coding in case of RTL mode, e.g. because they are positioning or animating elements programmatically, not via CSS.

The SAPUI5 RTL configuration can be read by calling

var bRtl = sap.ui.getCore().getConfiguration().getRTL();

Impact on Applications

The text direction is LTR by default, but can be set using the various known configuration switches:

● URL parameter sap-ui-rtl=true● Configuration object: window["sap-ui-config"].rtl = true;● Script tag configuration: data-sap-ui-rtl="true"

SAPUI5 takes care of setting the overall page direction to "RTL". All UI5 content will then be displayed in RTL mode. For self-written controls and content you need to test. If manual style adoptions are required, you need to provide style specifically for the RTL case by using html[dir=rtl].



Steps

If SAPUI5 is configured to RTL mode, the core:

1. sets dir="rtl" on the HTML tag

○ The W3C officially recommends using the HTML attribute instead of the CSS properties, for example, directionality is a matter of content, not of presentation, and because the CSS properties may even be ignored.

○ Using the <HTML> tag (not the BODY tag) is recommended as well2. loads the respective library-RTL.css files

1.4.18 Building Mobile Applications with SAPUI5

Related Information

Best Practice for Building Mobile Applications [page 206]These best practice provides recommendations how to achieve a clear structure and architecture for SAPUI5 applications.

Using MVC in Mobile Apps [page 214]

Handling Navigation and Lifecycle Events [page 222]Mobile apps are often composed of several pages and the user can drill-down to detail pages and go back up again. This is often visualized by horizontal slide animations. SAPUI5 supports this pattern by providing the sap.m.App and sap.m.NavContainer controls, which handles the navigation between the pages.

Adapting to Platform and Form Factors [page 225]The SAPUI5 Mobile library target devices run different operating systems and have very different screen sizes and pixel densities. SAPUI5 does some adaptations automatically. In addition to that, the application can further adapt to the current device.

Working with Lists [page 238]

Triggering Phone, SMS and E-Mail [page 244]With SAPUI5 for Mobile you can easily trigger native mobile phone applications such as e-mail, telephone, and text messages.

Scrolling in SAPUI5 Mobile [page 247]

Running SAPUI5 Mobile Apps in Hybrid Web Containers [page 250]

Using Images in Mobile Applications [page 252]

Message Handling [page 256]



Navigation Using Browser History [page 259]

Mobile Events [page 261]

Styling and Theming Mobile Controls [page 264]

Building Charts with MAKit [page 264]

1.4.18.1 Best Practice for Building Mobile Applications

These best practice provides recommendations how to achieve a clear structure and architecture for SAPUI5 applications.

NoteThe concepts described in the following sections are applied to the Shopping Cart demo app, see Shopping

Cart . You can use its source code to understand the concepts described in the best practice.

Caveats

Technically, you can code the whole application in one single HTML file. The simple "Hello World" application is built like this to make the basic functionality easy to understand. But when you create more complex applications, a clear architecture is the key for efficient development and maintainability.

If several possible options exist, for example with regard to the file structure, the granularity of views, or the use of the MVC concept, and the Best Practices use a specific option, this does not mean that the other options are wrong. In fact, other options may suit specific applications even better and some decisions may depend on project experience or team setup.

Nevertheless, this document intends to provide valuable suggestions for a good application structure. Keep in mind, though, that it does not represent the only possible or correct way to build SAPUI5 applications.

The Best Practices contains sections that refer to concepts or controls which are only available in the sap.m mobile library, but most suggestions also apply to desktop applications, or are at least similar for desktop applications.

Overview

The figure below shows the components and dependencies based on the Shopping Cart demo application. The Shopping Cart demo application is a SAPUI5 Mobile application consisting of six pages. The pages are created by using one view and a controller each.



http://help.sap.com/disclaimer?site=https://sapui5.hana.ondemand.com/sdk/#test-resources/sap/m/demokit/demokit-home/index.html


The pages are complemented by an application view and a controller for handling the navigation between views, including the handling of back/forward buttons in the browser. The view content construction in the views and the functionality, navigation, and eventing in the controllers are separated.

For loosely-coupled communication the EventBus is used. There are no direct dependencies between the views, and the EventBus events are only used for navigation and parameter handover between pages.

Two data models exist:

● "Product", containing the available goods● "Cart", containing the items put into the shopping cart

In addition to these two models, two additional models contain the resources used by the application: one for images and one for translated texts, see Localization and Image Model.

The application is launched from within Application.js (the “App Bootstrap”), which creates the data models and the root/app view. The Formatter utility class is used, but the example does not contain custom controls.

The index.html page itself only contains minimal code for configuring locations and loading the Application.js, see index.html.

As the architecture of an application depends on the size, nature, and structure of the respective application, the example will not fit all applications, but should at least give a rough idea.

1.4.18.1.1 File Structure

The following assumptions are made with regard to the file structure:

● As no resource folder is used, the SAPUI5 core/libs can be stored anywhere, that is in a local resource folder or somewhere else.



● As the app is not reused in other apps, it is not necessary to model namespaces in the views/controller paths.

The suggested application structure looks as follows:

The <webapp_root_folder> contains the following namespaces:

● Application.js● css folder: Contains all CSS files and the related images, that is style.css and more stylesheets, if required● ext folder: Contains all reused third party java script● i18n folder: Contains all property files for localization, for example:

○ i18n.properties○ i18n_de.properties○ i18n_en.properties

● model folder● util folder: Contains all helper classes● view folder: Contains all view and controller files go here; all file names shall start with an upper case letter● img folder: Contains all image files (png, jpg, gif, …)● <someNamespace>: Contains all on-the-fly controls defined in the application, for example,

<controlName>.js● index.html

Depending on the application, not all resources may be required.

“someNamespace” is, for example, salesorders or a nested namespace, for example sap/hcm/hiring. This namespace is reflected in the package names of the controls, for example var btn = new salesorders.MyButton(); or new sap.hcm.hiring.CustomButton();.

You can use these namespaces also for views, controllers and helper classes, but this depends on the application. The localResources or registerModulePath statements need to be adapted accordingly, see index.html.

1.4.18.1.1.1 index.html

The index.html entry page for an application should have the following structure and content:

● HTML5 DOCTYPE● Meta tag instructing Internet Explorer (IE) to use the newest rendering mode; for SAPUI5 Mobile this is done

in preparation for future IE support, for SAPUI5 desktop application this information is required to make sure IE does not use a compatibility mode

● Charset settings; usually UTF-8, but may need to be adapted to the actual charset● Application <title>● SAPUI5 bootstrap script tag for loading SAPUI5 and the required control libraries and theme● Any application CSS stylesheet links; the SAPUI5 theme stylesheets are inserted directly after the bootstrap

tag, so loading the application stylesheets here guarantees that they can more easily override SAPUI5 styles● Script tag starting the application● HTML body where the SAPUI5 content will be rendered

Of course, specific applications may require additional script tags to load external files or some HTML structure within the body or a script tag before loading UI5 to configure the UI5 runtime. This suggestion here does not say such extensions are not allowed.



Example index.html file

<!DOCTYPE html><html> <head> <meta http-equiv="X-UA-Compatible" content="IE=edge"/> <meta charset="UTF-8">

<title>XYZ</title>

<script id="sap-ui-bootstrap" src="XYZ" data-sap-ui-theme="XYZ" data-sap-ui-libs="XYZ"> </script>

<link rel="stylesheet" type="text/css" href="css/style.css">

<script> // Tell UI5 where to find application content sap.ui.localResources("util"); // paths starting with "util" will be resolved relative to the index.html location sap.ui.localResources("view"); jQuery.sap.registerModulePath('ApplicationBase', 'ApplicationBase'); // this file will be loaded directly from the same directory jQuery.sap.registerModulePath('Application', 'Application');

// Launch application jQuery.sap.require("Application"); var oApp = new Application({root : "content"}); // instantiate your application and mark the HTML element with id "content" as location for the UI </script>

</head> <body class="sapUiBody" id="content"> </body></html>

1.4.18.1.1.2 Application.js

The first code to be executed at runtime is the Application.js. The init function is executed right away and triggers tasks that can be executed without having the DOM available, for example loading JSON files from the server. The main function is only called after the DOM is ready. This is the point in time when you instantiate the app view and controller and place the view in the DOM.

Example for Application.js

jQuery.sap.declare("Application");jQuery.sap.require("ApplicationBase");

ApplicationBase.extend("Application", {

init : function() { // set global models



onBeforeShow : function(evt) { this.getController().onBeforeShow(evt); }, ...

Handling the event in the target's view controller

sap.ui.controller("view.Product", { ... onBeforeShow : function(evt) { if (evt.data.context) { this.getView().setBindingContext(evt.data.context); } }, ...

1.4.18.1.3 History Handling

History handling is one of the most difficult topics in implementing a mobile application. Android and Blackberry devices have a physical back button which triggers for both web and hybrid apps a back navigation in the browser history

NoteRunning Demo

The Navigation app illustrates the usage of the jQuery.sap.history for integrating the Android back button into application navigation.

To launch it, see Navigation

In the architecture example in this Best Practices, the code for history handling is contained in the app controller, including the subscription to history changes:

sap.ui.controller("view.App", { onInit : function() { // init history mgmt jQuery.sap.require("jquery.sap.history"); jQuery.sap.history({ routes: [{ path : "page", handler : jQuery.proxy(this.historyPageHandler, this) }], defaultHandler: jQuery.proxy(this.historyDefaultHandler, this) }); ...

The app controller sets the history for forward navigation:

sap.ui.controller("view.App", { ... navTo : function(id, writeHistory, navType, data) { ... // write history if (writeHistory === undefined || writeHistory) { jQuery.sap.history.addHistory("page", {id: id}, false);}



http://help.sap.com/disclaimer?site=https://sapui5.hana.ondemand.com/sdk/#test-resources/sap/m/demokit/navigation/index.html

On opening a dialog, a virtual history has to be added. This is not handled in the app controller, but in the related view or controller:

jQuery.sap.history.addVirtualHistory();sap.m.MessageToast.show("Product added to your shopping cart");

1.4.18.1.4 Instance Manager

When you open dialogs and popovers, they automatically register themselves in the instance manager. This allows you to easily check for open dialogs or popovers when navigating back, and to close them without maintaining references yourself. The following code shows the navTo function of the app controller:

navTo : function(id, writeHistory, navType, data) { ... // navigate on app var app = this.getView().app; if (navType === jQuery.sap.history.NavType.Back) { if (sap.m.InstanceManager.hasOpenDialog()) { sap.m.InstanceManager.closeAllDialogs(); } else { app.backToPage(id); } } ...

1.4.18.1.5 Localization

We recommend to use data binding and the sap.ui.model.resource.ResourceModel as a named model for localization. This facilitates the use of translation keys instead of actual texts.

You can also use ResourceBundles, but they require code execution for every translated text set to a control.

For more information, see Use of Localized Texts in Applications.

The following guidelines apply:

● Use i18n as model name● Use only one global property file that contains all texts used in the views.● Group view-specific texts with a prefix; to avoid redundancies, do not apply a prefix to texts which are reused

across view boundaries

Example:

var oModel = new sap.ui.model.resource.ResourceModel({bundleName:"i18n", bundleLocale:"en"});

// set the resource model as global model with the name "i18n" sap.ui.getCore().setModel(oModel, "i18n");

var oControl = new sap.ui.commons.Button({ text : "{i18n>MY_BUTTON_TEXT}"});



1.4.18.1.6 Image Model

When referencing images in an application it is more convenient to collect all access paths in one central place instead of having them everywhere in the code. To achieve this, you store them in a JSON file, make this file available with a global JSON model named "img", and bind the controls against this model.

The following code snippet shows how image access paths are stored in a JSON file:

{ "icon" : { "ui5" : "img/SAPUI5Icon.png", "cart" : "img/cart_TabButtonItem.png" }}

The following code snippet shows how images are made available with a global JSON model:

ApplicationBase.extend("Application", { init : function() { var imgModel = new sap.ui.model.json.JSONModel("model/img.json"); sap.ui.getCore().setModel(imgModel, "img"); ...

The following code snippets show how the controls are bound against img model:

this.page = new sap.m.Page({ title : "Shopping Cart", icon : "{img>/icon/ui5}", ...

This approach even allows to switch all images to a different set at runtime with one line of code, for example, to provide differently colored image sets for different SAPUI5 themes.

1.4.18.1.7 Utilities

When developing an application, you need to reuse JavaScript coding in multiple views and controllers. You can reuse code by putting the code into separate files which are stored in the util folder. To dynamically load this code at runtime, the SAPUI5 modularization concept is used, see Modularization and Dependency Management.

An example for this is the reuse of a formatter in multiple data bindings. The formatter code is defined in util/Formatter.js as follows:

jQuery.sap.declare("util.Formatter");

util.Formatter = { price : function(value) { jQuery.sap.require("sap.ui.core.format.NumberFormat"); var numberFormat = sap.ui.core.format.NumberFormat.getFloatInstance({ maxFractionDigits: 2, groupingEnabled: true, groupingSeparator: ".", decimalSeparator: "," }); return numberFormat.format(value) + "\u20AC"; }



};}

This is a view using the formatter in a data binding:

jQuery.sap.require("util.Formatter");

sap.ui.jsview("view.Home", {

createContent : function(oCon) { ... this.productList = new sap.m.List({}); this.productList.bindAggregation("items", { path : "/products", template : new sap.m.StandardListItem({ title : "{name}", info : { path : "price", formatter : util.Formatter.price } }) ...

1.4.18.2 Using MVC in Mobile Apps

For SAPUI5 mobile applications, you can use the same Model View Controller concept as for desktop apps, see Model View Controller (MVC) Approach.

You can choose the granularity of views freely, for example, one view per page. The following sections illustrate the use of the MVC concept in mobile applications to decouple the different application parts. The following sections are not intended as a best practice document, but rather to illustrate the interaction of views.

For a more complex example, see Best Practice for Building Mobile Applications.

1.4.18.2.1 An MVC Demo Application

To illustrate the MVC use, we build a simple Mobile application consisting of two pages.

NoteRunning Demo

To launch and inspect the MVC demo app, see Model View Controller

The following three views are used:

● One XML view for the app control which forms the root level of the application● One XML view for the home page● One JSView for the detail page

The home page displays a list of countries. By tapping any of the countries, you navigate to the detail page with more information about the selected country.



http://help.sap.com/disclaimer?site=https://sapui5.hana.ondemand.com/sdk/#test-resources/sap/m/demokit/mvc/App_with_rootView.html

NoteThe app control holds its child controls in the pages aggregation. This does not mean that only sap.m.Page controls can be aggregated: The demo application puts the views into the aggregation. Therefore, calling app.getPages() returns the directly aggregated views and not an sap.m.Page control.

The following figure depicts the overall structure of the application. The homePageView is displayed initially and the detailPageView is displayed when drilling down to details. The appView only holds the sap.m.App control for page navigation. It has no visible user interface, but is always rendered as a sort of invisible frame containing the application.



1.4.18.2.1.1 The HTML Page

The App_with_rootView.html page launches the application:

● It loads SAPUI5.● It ensures that all resources starting with sap.m.mvc, that is, the views and controllers are loaded from

locations relative to the HTML page.● It instantiates the root view and places it into the content div element.

Example for the HTML page:

<script id="sap-ui-bootstrap" src="../../../../resources/sap-ui-core.js" data-sap-ui-theme="sap_mvi" data-sap-ui-libs="sap.m" ></script>

<script> // let UI5 know that certain package (the one containing the Views/Controllers) is available locally (next to the HTML file) sap.ui.localResources("sap.m.mvc");

// define View and place it onto the HTML page sap.ui.xmlview("appView", "sap.m.mvc.App").placeAt("content"); // all other initialization will be done by the App controller

</script>

1.4.18.2.1.2 The Root (App-) View

Although the root view and controller could be omitted by putting some code into the HTML file, this example shows how view are embedded into others to use MVC as much as possible.

The concept is simple: One sap.m.App control aggregates two sap.m.Pages. The first page is displayed initially:

<core:View controllerName="sap.m.mvc.App" xmlns="sap.m" xmlns:core="sap.ui.core" xmlns:mvc="sap.ui.core.mvc" xmlns:html="http://www.w3.org/1999/xhtml">

<App id="theApp"> <mvc:XMLView id="homePageView" viewName="sap.m.mvc.HomePage"></mvc:XMLView> <mvc:JSView id="detailPageView" viewName="sap.m.mvc.DetailPage"></mvc:JSView> </App>

</core:View>

The viewName elements define the view type and the location, from which the respective view is loaded. The AppView also defines a controllerName, so a controller is loaded and attached as well.



1.4.18.2.1.3 The Root (App-) Controller

The root controller handles the following actions:

● It loads the data from a JSON file by using an AJAX call and initializes the overall JSONModel.● It handles the page navigation by listening to events published by the views and triggers the appropriate

navigation on the app control by using the EventBus.

When the user taps a list item on the homePageView, it publishes a to event in the nav channel. The root controller then executes the navToHandler method. After loading the view, if necessary, the root controller calls this.app.to(data.id, data.data.context) to trigger the navigation to the second page and to hand over the bindingContext, which contains information about the item the user selected on the initial page.

This leads to a horizontal slide animation. This is the default setting, but other animations can be chosen as well.

The back navigation is handled similarily, but is more simple, as no data needs to be passed. The app control keeps track of the page stack and automatically navigates back to the homePageView, using an inverse animation.

sap.ui.controller("sap.m.mvc.App", {

onInit : function() { var view = this.getView();

// Data is fetched here jQuery.ajax("Data.json", { // load the data from a relative URL (the Data.json file in the same directory) dataType: "json", success: function(data){ var oModel = new sap.ui.model.json.JSONModel(data); view.setModel(oModel); } });

// remember the App Control this.app = view.byId("theApp");

// subscribe to event bus var bus = sap.ui.getCore().getEventBus(); bus.subscribe("nav", "to", this.navToHandler, this); bus.subscribe("nav", "back", this.navBackHandler, this); },

navToHandler : function(channelId, eventId, data) { if (data && data.id) { // lazy load view if (this.app.getPage(data.id) === null) { jQuery.sap.log.info("now loading page '" + data.id + "'"); this.app.addPage(sap.ui.jsview(data.id, "sap.m.mvc." + data.id)); } // Navigate to given page (include bindingContext) this.app.to(data.id, data.data.context); } else { jQuery.sap.log.error("nav-to event cannot be processed. Invalid data: " + data); } },



navBackHandler : function() { this.app.back(); }});

1.4.18.2.1.4 The HomePage Controller

The HomePage controller handles the tap on a list item by publishing the event to the nav channel and hands over the relevant view (DetailPage) and the context of the tapped list item.

sap.ui.controller("sap.m.mvc.HomePage", {

listItemTriggered: function(evt) { // Option 1: using custom data attached to the ListItem // The ID (abbreviation) of the country is available as a custom data object and... // ...we could use it to fetch detail data // ...or we could hand it over to the detail page with .to("detailPage", {id: id}); var id = evt.oSource.data("id"); // this id remains unused in this example, though!

// Option 2: // In case of data binding we can get the binding context (a sort of pointer to the data object to which the clicked ListItem is bound) var bindingContext = evt.oSource.getBindingContext(); // evt.oSource is the ListItem

// The EventBus is used to let the Root Controller know that a navigation should take place. // The bindingContext is attached to the data object here to be used in the Root Controller's event handler. var bus = sap.ui.getCore().getEventBus(); bus.publish("nav", "to", { id : "DetailPage", data : { context : bindingContext } }); }});

1.4.18.2.1.5 The HomePage View

The HomePage view contains the content, which is displayed initially. It contains a full screen page control which displays a list of countries. The list is made from a StandardListItem template using SAPUI5 data binding. For each country in the data, one list item is created and displayed.

When you tap a list item, the attribute tap="listItemTriggered" calls the listItemTriggered method of the HomePage controller.

<core:View controllerName="sap.m.mvc.HomePage" xmlns="sap.m" xmlns:core="sap.ui.core" xmlns:mvc="sap.ui.core.mvc"



xmlns:html="http://www.w3.org/1999/xhtml">

<Page id="homePage" title="Countries"> <List items="{/countries}"> <StandardListItem title="{name}" description="{short}" type="Navigation" tap="listItemTriggered"> <customData>  <core:CustomData key="id" value="{short}" /> </customData> </StandardListItem> </List> </Page>

</core:View>

1.4.18.2.1.6 The DetailPage View

To give an example for other view types as well, the detail page of this example is build as a JSView. As usual for JSViews, the createContent method constructs the user interface of the view which contains one sap.m.Page control containing a List and a VBox layout. The List displays the details for the selected country. By using data binding it is ensured that the correct country data is displayed without actively fetching this data.

Triggering Back Navigation

While the semantics of the button on the left hand side of the page header is different between platforms ("back" button on iOS, "up" button on Android), the sap.m.Page only offers a navigation button and it is up to the application whether there is a difference between "up" and "back" on the respective page or whether it follows the platform guidelines and respects the difference.

In our example, "up" is the same as "back" and we only display this button with the label Countries (appears only on iOS). When the button is tapped, the method backTriggered of the view controller is called. The second array entry is the context of this method: When the method is executed, "this" is the controller.

var oPage = new sap.m.Page({ title:"Details", showNavButton:true, navButtonText: "Countries", navButtonTap:[oController.backTriggered,oController]});

An application can also take shortcuts, for example, by directly calling app.back() if the "app" object is known inside the view. This demo application, however, wants to demonstrate maximum decoupling.

Handling the Navigation Event

Pages, or rather children of NavContainer/App controls such as this detail view, are informed about navigation activities. You can attach delegates to these pages for preparation and cleanup work. These delegates are also

informed about the navigation activities. For more information, see Navigation and Lifecycle Events in the App and the NavContainer.

To updates the data binding every time before it is displayed, the detail view registers for beforeShow and sets the binding context which has been passed by the root controller as payload data of the to(…) call, which triggered the detail page navigation.

this.addEventDelegate({ onBeforeShow: function(evt) { this.setBindingContext(evt.data); // evt.to is actually this View (the navigation target). This should be "this" in the future to be more intuitive... }}, this); // give this (= the View) as additional parameter to make it available inside the delegate's functions as "this" object

The beforeFirstShow event can be used in a similar way by the application to lazily construct the UI only when it is actually required due to the user navigating to this page. Currently, the view UI creation in createContent is executed on application startup.

The Entire View Code

sap.ui.jsview("sap.m.mvc.DetailPage", {

getControllerName: function() { return "sap.m.mvc.DetailPage"; },

/** * Creates the UI of this View * * @returns {sap.ui.core.Control} */ createContent: function(oController) {

var oPage = new sap.m.Page({ title:"Details", showNavButton:true, navButtonText: "Countries", navButtonTap:[oController.backTriggered,oController] });

// create the page content structure jQuery.sap.require("sap.ui.core.format.NumberFormat"); var oList = new sap.m.List({headerText: "Country Details", items: [ new sap.m.DisplayListItem({label:"Capital:",value:"{detailInfo/capital}"}), new sap.m.DisplayListItem({label:"Population:",value:{ path:"detailInfo/population", formatter:function(iValue){ var oFormatter = sap.ui.core.format.NumberFormat.getIntegerInstance({ // format the population count groupingEnabled: true, groupingSeparator: "." }); return oFormatter.format(iValue); } }}),



new sap.m.DisplayListItem({label:"Currency:",value:"{detailInfo/currency}"}), new sap.m.DisplayListItem({label:"Area:",value:{ path:"detailInfo/area", formatter:function(iValue){ var oFormatter = sap.ui.core.format.NumberFormat.getIntegerInstance({ // format the area groupingEnabled: true, groupingSeparator: "." }); var formattedNumber = oFormatter.format(iValue); return formattedNumber + " sq km"; } }}) ]}); oPage.addContent(oList); var oFlagArea = new sap.m.VBox({ alignItems: sap.m.FlexAlignItems.Center, items: [ new sap.m.Label({text:"Flag:"}), new sap.m.Image({src:"{detailInfo/flagUrl}",decorative:true,densityAware:false}) ] }); oPage.addContent(oFlagArea);

this.addEventDelegate({ onBeforeShow: function(evt) { this.setBindingContext(evt.data); // give this (= the View) as additional parameter to make it available inside the delegate's functions as "this" object } }, this);

return oPage; }

});

1.4.18.2.1.7 The DetailPage Controller

The DetailPage controller only contains the method for publishing the back event to the nav channel of the EventBus. The root controller listens to this event and triggers back navigation.

sap.ui.controller("sap.m.mvc.DetailPage", {

backTriggered: function() { var bus = sap.ui.getCore().getEventBus(); bus.publish("nav", "back"); }

});



1.4.18.3 Handling Navigation and Lifecycle Events

Mobile apps are often composed of several pages and the user can drill-down to detail pages and go back up again. This is often visualized by horizontal slide animations. SAPUI5 supports this pattern by providing the sap.m.App and sap.m.NavContainer controls, which handles the navigation between the pages.

sap.m.App inherits the navigation capabilities from the sap.m.NavContainer control. Thus, both controls are equal with regard to navigation and navigation events. The following sections refer to the sap.m.NavContainer, but the same also applies to the sap.m.App control.

A mobile application can control the navigation flow centrally and directly trigger the initialization or refresh of the pages. To support modularization of the app, however, it may also be beneficial to control the navigation flow non-centrally. In this case, code which constructs a page is also the code that handles, for example, the data load in this page.

To support this, SAPUI5 provides two types of events:

● Events fired by the App or by the NavContainer whenever it navigates.● Events fired on the pages when they get shown or hidden by navigation.

API References

● sap.m.App

● sap.m.NavContainer

Related Information

Events Fired Centrally by the App or the NavContainer [page 223]When NavContainer.to(…) or NavContainer.back(…) are called, the NavContainer triggers events and the application can register for this events. The navigate event is fired before the transition animation starts, and the afterNavigate event is fired when the animation has been completed.

Events fired on the Pages [page 223]

Passing Data when Navigating [page 224]When you use the to(…) and back(…) methods of the NavContainer to trigger navigation, you can also give an optional payload data object.



http://help.sap.com/disclaimer?site=https://sapui5.hana.ondemand.com/sdk/#docs/api/symbols/sap.m.App.html

http://help.sap.com/disclaimer?site=https://sapui5.hana.ondemand.com/sdk/#docs/api/symbols/sap.m.NavContainer.html

1.4.18.3.1 Events Fired Centrally by the App or the NavContainer

When NavContainer.to(…) or NavContainer.back(…) are called, the NavContainer triggers events and the application can register for this events. The navigate event is fired before the transition animation starts, and the afterNavigate event is fired when the animation has been completed.

The events contain a lot of information about the page that is left and the target page of the navigation, as well as what kind of navigation is happening.

Example:

app.attachNavigate(function(evt) { var isBack = !evt.getParameter("isTo"); // there are several types of back animation, but we want the general direction only alert("Navigating " + (isBack ? "back " : "") + " to page " + evt.getParameter("toId"));});

API References

● event:afterNavigate

● event:navigate

1.4.18.3.2 Events fired on the Pages

Events fired on the pages allows a decentral reaction to navigation. The NavContainer fires events to its child controls regardless of whether they are displayed or hidden.

NoteAlthough this documentation calls them "pages" and a sap.m.Page control may be the typical child of a NavContainer, any full screen control can be used, for example, a sap.m.Carousel control or a custom control. Thus, the event is not fired by the child control, but by the NavContainer on the child control (whatever type it is). This causes the different registration compared to normal control events.

Before the navigation animation starts, the NavContainer fires the following events:

● beforeHide on the page which is about to be left● beforeFirstShow on the page which is about to be shown; this event is only fired if the respective page has

not been opened before● beforeShow on the page which is about to be shown

These events can be used to create or update the user interface of the new page and to stop any activity, such as animations or repeated data polling, on the page which is left.



http://help.sap.com/disclaimer?site=https://sapui5.hana.ondemand.com/sdk/%23docs/api/symbols/sap.m.NavContainer.html#event:afterNavigate

http://help.sap.com/disclaimer?site=https://sapui5.hana.ondemand.com/sdk/%23docs/api/symbols/sap.m.NavContainer.html#event:navigate

After the navigation has been completed and the new page has covered the whole sccreen, the following events are fired:

● afterShow on the page which is now shown● afterHide on the page which has been left

You can destroy the hidden page, and the now active page can start its activity.

You can use the addEventDelegate function to register to these events. This function is available on every control.

page1.addEventDelegate({ onBeforeShow: function(evt) { // page1 is about to be shown; act accordingly - //if required you can read event information from the evt object }, onAfterHide: function(evt) { }});

API Reference

sap.m.NavContainerChild

1.4.18.3.3 Passing Data when Navigating

When you use the to(…) and back(…) methods of the NavContainer to trigger navigation, you can also give an optional payload data object.

This object is then available in the page events, for example beforeShow and afterShow. You can also use this mechanism to decouple page implementations.

Example:

app.to("detailPage", {id:"42"}); // trigger navigation and hand over a data object// this data object could also be a binding context when dealing with data binding// and where the detail page is implemented:myDetailPage.addEventDelegate({ onBeforeShow: function(evt) { var idToRetrieve = evt.data.id; // ...now retrieve the data element with the given ID and update the page UI }});

When you navigate back to a page, it receives the original data object which has been given when you first navigated to the page, but you can also give an additional data object with the back navigation.



http://help.sap.com/disclaimer?site=https://sapui5.hana.ondemand.com/sdk/#docs/api/symbols/sap.m.NavContainerChild.html

API References

●

● sap.m.NavContainer

● sap.m.NavContainerChild

1.4.18.4 Adapting to Platform and Form Factors

The SAPUI5 Mobile library target devices run different operating systems and have very different screen sizes and pixel densities. SAPUI5 does some adaptations automatically. In addition to that, the application can further adapt to the current device.

The following sections give an overview of the adaptations done by SAPUI5 and which adaptations you can implement in addition.

Related Information

Built-in Adaptation of SAPUI5 Mobile [page 225]

Adapting Automatically to Different Screen Sizes using SplitApp [page 227]Using SplitApp you can ensure that your UI automatically adapts to the size available on the respective device.

Checking the Operating System your Application is Running on [page 234]A platform attribute is added to the HTML tag when running on mobile devices.

Options for further Adaptation [page 235]

1.4.18.4.1 Built-in Adaptation of SAPUI5 Mobile

Platform-dependent Styling

The sap_mvi ("Mobile Visual Identity") theme delivered with the SAPUI5 Mobile library provides three different visual styles which closely mimic the native look of the Apple iOS, the Android, and the Windows Phone platform. Compared to the native visuals they are adapted to match the SAP color scheme with black and golden color accents.

NoteThe mobile visual identity (sap_mvi) theme is not supported for iOS7 and higher.



http://help.sap.com/disclaimer?site=https://sapui5.hana.ondemand.com/sdk/#docs/api/symbols/sap.m.NavContainer.html

http://help.sap.com/disclaimer?site=https://sapui5.hana.ondemand.com/sdk/#docs/api/symbols/sap.m.NavContainerChild.html

● The iOS design has the typical Apple gradients and rounded corners, but is tinted in black and grey with golden accents.

● The Android design is using the Android 4.0 ("Ice Cream Sandwich") design with rather flat elements with no gradients or rounded corners. While the ICS design already uses black color, the MVI theme adds golden accents while maintaining Google's original blue style in the interactive controls

● The Windows Phone design mimics the typical chrome-less visuals, but does not adapt the entire interaction to feel 100% native.

The controls look very much like the native UI controls on these platforms, so the user immediately recognizes them.

NoteFor BlackBerry 10 the Android look and feel is currently used.

Other Platform-dependent Adaptations

In addition to the visual design, the SAPUI5 Mobile library provides further platform adaptations. To a certain degree, controls automatically adapt to the native UI concepts and user experience without any effort on application side.

The following list gives examples:

● The sap.m.Page control by default creates a header which looks different on both platforms even though there is only one single Page API:

○ On iOS, the navigation button is the typical Apple back button with a label and an arrow shape on the left hand side and the header title is positioned in the center.

○ On Android, the navigation button appears as an arrow with no label; an optional icon is displayed next to it and the header title is displayed left-aligned.

○ On Windows Phone, no back navigation button is available. Instead, the phone's hardware button is used for back navigation.

● When used in a bar on Android, the sap.m.SegmentedButton looks like a tab.● The sap.m.Dialog appearance not only differs between operating systems, but also between form factors:

○ On Android, it is a bright popup with buttons filling the whole popup footer.○ On iPad, it is a popup with dark header and buttons in the left and right side of the header.○ On iPhone, it looks like on iPad, but covers the full screen and is sliding in from the bottom.

The SplitApp Control - Adapting Automatically to Different Form Factors

You can use the sap.m.!SplitApp control to implement multi-page scenarios that automatically adapt to the available screen size: On phones, only one page is displayed, and on tablets, especially in landscape orientation, two pages are displayed simultaneously.

For more information, see SplitApp - Hello World.



1.4.18.4.2 Adapting Automatically to Different Screen Sizes using SplitApp

Using SplitApp you can ensure that your UI automatically adapts to the size available on the respective device.

As tablets such as iPad or Google Nexus7 provide more space compared to smartphones, porting existing mobile apps to tablets leads to a lot of unused space.

A common pattern to address this is called master-detail, and is often used in native iOS and Android development. Good examples are the native Settings and E-Mail applications of iOS and Android tablets. This pattern can be used with the SplitApp control.

The figure shows the basic idea of the pattern. The app is divided into two views, the master and the detail view. The master view presents a list of items and is used as the main navigation within the application. The detail view shows detail information for the selected item.

Whereas the selection of an item on a mobile devices navigates the user to the detail page, the user can see the list of items and the detail view at the same time on a tablet device.

If the tablet device is used in protrait mode it has less available width space. For this, the SplitApp control provides three different modes for displaying the master and detail view in portrait mode:

● ShowHideModeThis is the default mode. This mode hides the master view automatically when the user turns the device into portrait mode. To display the master view, the user swipes right on the detail view or uses the button which is be placed on the header of the detail view.The Master view slides in from the right hand side. The user can choose another list item which will update the detail view and automatically hides the master view again.

● PopoverModeThis mode places the master view inside a popover which can be opened via the button in the header of the detail view.



● StretchCompressModeThis mode displays the master view in both, the portrait and the landscape mode. In portrait mode, the detail view has less space available.

In landscape mode, all three modes described above display the master view.

If you run a SplitApp on a mobile device, it automatically behaves like a standard mobile application. The following figure shows the difference:

As only one page per screen can be displayed, the master and detail view are automatically displayed on separate pages and the standard page navigation is applied.

The following section explains how a SplitApp application is build, see The First SplitApp.

1.4.18.4.2.1 The First SplitApp

To develop a SplitApp application, use the sap.m.SplitApp control instead of the sap.m.App control which is used for smartphone applications only.

NoteRunning Demo

This demo app shows how you can automatically adapt your user interface to the available space by using the SplitApp control.

On a mobile phone, pages are stacked on top of each other and linked via navigation. On a tablet PC with landscape orientation, the pages are shown next to each other in a split view layout whereas in portrait orientation the application can choose whether to always display the master view, to display it in a popover, or to display it when the user swipes from the left. In this Demo App, you can try all three modes. Just open the iPad or Android tablet version in a new window, size it to portrait mode and choose the display mode on the bottom left.



To launch it, choose SplitApp from here: Demo Apps .

var oSplitApp = new sap.m.SplitApp("mySplitApp", {});

You can add pages to the SplitApp control, but you have to decide to which view you want to add them:

oSplitApp.addDetail() or oSplitApp.addMaster();

Before you can do this, you need some basic pages, two for the Master and two for the Detail view:

var oDetailPage1 = new sap.m.Page("detail1", { title : "Detail 1", content : [ new sap.m.Label({ text : "this is Detail 1" }) ]});var oDetailPage2 = new sap.m.Page("detail2", { title : "Detail 2", content : [ new sap.m.Label({ text : "this is Detail 2" }) ]});

To implement a basic navigation for selection of the Detail view, the two Master view pages need a list. As we only need to navigate or drill down inside the Master view, a simple StandardListItem with type Navigation is sufficient.

If the user taps on a list item, we navigate to Master view page 2. To do this, call the toMaster() method with the page you want to navigate to. In the example this is master2.

var oMasterPage1 = new sap.m.Page("master1",{ title : "Master", content : [ new sap.m.List({ items : [ new sap.m.StandardListItem({ title : "To Master 2", type : "Navigation", tap : function() { oSplitApp.toMaster("master2"); } })] }) ]});

The second Master view page is the leaving point of the master navigation: Depending on the item the user selects, the Detail view is updated. An example for this is an e-mail application with a list e-mails in the Master view and the content of the e-mail in the Detail view.

As we do not want to further navigate within the Master view, the list mode is set to SingleSelectMaster.

To update the Detail view, we have to listen to the list's select events, so we can decide on which detail page to show. Depending on the selected list item, either the detail1 page or the detail2 page is displayed. The method is called toDetail.

var oMasterPage2 = new sap.m.Page("master2",{ title : "Master2", navButtonTap : function() {oSplitApp.backMaster();}, content : [ new sap.m.List({ mode:"SingleSelectMaster", select: function(oEv) {




if(oEv.getParameter("listItem").getId() == "listDetail2") { oSplitApp.toDetail("detail2"); } else { oSplitApp.toDetail("detail1"); } }, items : [ new sap.m.StandardListItem("listDetail2",{ title : "To Detail 2" }), new sap.m.StandardListItem("listDetail",{ title : "To Detail 1" }) ]}) ]});

To enable the SplitApp to run on mobile devices, some additional information needs to be added to the pages. Also, the navigation back to the Master view page has to be available from both Detail view pages.

In the next step, the pages are put into the SplitApp control:

//add the master pages to the splitapp controloSplitApp.addMasterPage(oMasterPage1).addMasterPage(oMasterPage2);//add the detail pages to the splitapp controloSplitApp.addDetailPage(oDetailPage1).addDetailPage(oDetailPage2);

Then set the initial Master view and Detail view page:

oSplitApp.setInitialDetail("detail1");oSplitApp.setInitialMaster("master1");

Define the page transition type you want to use, see Navigation and Lifecycle Events in the App and the NavContainer.oSplitApp.setDefaultTransitionNameDetail("fade");Finally, place the SplitApp control in the HTML body tag:

oSplitApp.placeAt("body");

To test the other two SplitApp modes, use the setMode method to set them:

oSplitApp.setMode("PopoverMode");//oroSplitApp.setMode("StretchCompressMode");

1.4.18.4.3 Layouting with FlexBox

User interfaces often have to adapt to different screen sizes. Therefore, building user interfaces in a way that a single layout reliably fits the available screen real estate is challenging. The FlexBox control allows to develop layouts which adjust to the available space and avoid unused space or overflow. FlexBox controls can be nested to create more complex layouts.

The two main uses of a FlexBox control are:

● Two-dimensional layouting



● Flexible layouts

1.4.18.4.3.1 Getting Started With FlexBox

To use a flexible box layout, create a FlexBox control and add any kind of controls to it, either by using the addItem method (see option 1), or the items aggregration of a configuration object (see option 2).

Option 1

var oMyFlexbox = new sap.m.FlexBox();oMyFlexbox.addItem( new sap.m.Button({text: "Button 1"}) );oMyFlexbox.addItem( new sap.m.Button({text: "Button 2"}) );

Option 2

var oMyFlexbox = new sap.m.FlexBox({ items: [ new sap.m.Button({text: "Button 1"}), new sap.m.Button({text: "Button 2"}) ]});

The following figure gives an example how the result looks like if used inside a mobile app page. The necessary code is not shown here.

Layout properties

Some properties that affect the layout need to be set in the FlexBox control. Other properties can be attached to the controls which are placed inside the FlexBox by means of the layoutData aggregation. The layout direction, for example is set in the FlexBox as follows:

var oMyFlexbox = new sap.m.FlexBox({ items: [ new sap.m.Button({text: "Button 1"}), new sap.m.Button({text: "Button 2"}) ], direction: "Column"});



The order is attached to the button inside a FlexItemData object as follows:

var oMyFlexbox = new sap.m.FlexBox({ items: [ new sap.m.Button({ text: "Button 1", layoutData: new FlexItemData({order: 2}) }), new sap.m.Button({text: "Button 2"}) ]});

NoteThe FlexBox control is a wrapper for the flexible box layout properties in CSS. The control renderer sets the CSS properties (including prefixed versions where necessary) on the appropriate HTML elements. The actual layouting is done by the browser.

The controls that you place in the FlexBox control are each wrapped in a DIV or LI element, depending on the renderType property. All elements are placed inside another DIV or UL container, again depending on the renderType. The outermost element represents the so-called flex container while its child elements are flex items. The HTML structure resulting from all of the examples above looks as follows:

<div class="sapMFlexBox">

<div class="sapMFlexItem">

<button id="__button1">Button 1</button>

</div>

<div class="sapMFlexItem"> <button id="__button2">Button 2</button>

</div></div>



NoteThe layoutData properties that you can attach to a control are applied to its wrapper element with sapMFlexItem class. This is because browsers currently only support these properties on some elements, for example DIV.

The two additional controls HBox and VBox are FlexBoxes that are fixed to horizontally or vertically layout their children.

1.4.18.4.3.2 Important FlexBox Layout Concepts

The following sections contain information about important concepts for FlexBox layouts.

Main Axis and Cross Axis

A FlexBox layout has a direction in which child elements are laid out. The default direction is Row and rows are laid out horizontally in reading direction. This defines the main axis. The cross axis in this case is vertical.

You can change the layout direction property to Column, which results in a vertical main axis and a horizontal cross axis. This is important for the align properties.

NoteIf browsers support vertical text flows, the direction of a row can also be vertical. For now this is not an issue and can be ignored.

In addition to Row and Column, the flex direction can be set to RowReverse and ColumnReverse which will reverse the layout direction.

Two-Dimensional Alignment

You can determine where the flex items are aligned in a FlexBox layout. For the alignment you use the following two properties: justifyContent and alignItems. The justifyContent property sets the alignment along the main axis while alignItems acts on the cross axis.

Both properties accept the values Start, Center and End. This results in nine possible combinations, for example

● justifyContent = End and alignItems: Start places the items in the upper right corner of a horizonzal FlexBox● If you set the direction property to Column, the main axis would be vertical. Combined with justifyContent =

End and alignItems: Start, the items are placed in the lower left corner.● By reversing the main axis with direction = ColumnReverse the layout starts from the bottom. In this case,

justifyContent = End refers to the top of the FlexBox.● justifyContent has the additional value SpaceBetween?. This setting places the first and the last item at the

extremes of the main axis. Any other items will be distributed evenly between these two.



For alignItems two additional values exist: Baseline and Stretch. Baseline takes the first line of text of each flex item and aligns their baselines. This can be useful if different font sizes are used. Stretch makes the flex items take up the whole space along the cross axis of the FlexBox. This is useful if all items should have the same size regardless of the amount of content.

Flexibility

You can let the browser handle the distribution of elements. This ensures that they always fill the available space along the main axis. To do this, set a flexibility factor on the flex items.

The property to control the flexibility is called growFactor. It is set on a flex item object by means of FlexItemData on the layoutData aggregation. The flex layout algorithm determines the "natural" width of the flex items. If there is space left, this space is distributed among the flex items according to their relative growFactor. If, for example, a horizonzal flex container is 300px wide and contains two elements of 100px each, 100px would remain. If the growFactor for both flex items is set to 1, both get 50px extra, thus making them 150px wide. If the growFactor is set to 3 for one item and to 1 for the other item, the first item gets additional 75px (¾ of 100px) of the remaining space and the second item 25px (¼ of 100px). If the growFactor is set to its default value of 0, the item is inflexible and both items would keep their width of 100px.

NoteThe the flex algorithm distributes the remaining space, and not the whole space in the FlexBox. Therefore, the resulting widths of the items are not necessarily proportional to the growFactor.

To achieve a proportional width according to the growFactor, set the width of all items to 0 via CSS. The sum of the "natural" widths of all items is then also 0. The remaining space, however, now equals the full space of the FlexBox. This space is then distributed based on the growFactor. For the example above with growFactor set to 3 and 1, setting the the width of the flex items to 0 via CSS results in a width of 225px (¾ of 300px) for the first item and 75px (¼ of 300px) for the second item.

CautionOnce you set a growFactor for any item, the flex layout algorithm ignores the justifyContent property of the FlexBox because the items take up all available space anyway. There would be no difference between the different values.

1.4.18.4.4 Checking the Operating System your Application is Running on

A platform attribute is added to the HTML tag when running on mobile devices.

This attribute provides information about the current platform and version. For an application running on an iPad3, for example, the attribute value is iOS5.1.



NoteSAPUI5 Mobile currently only supports iOS, Android, Windows Phone 8 and Blackberry 10.

In addition to that, SAPUI5 adds a platform-dependent CSS class to the HTML tag of the page. This enables control or application developers to create platform-dependent styling for their controls or applications.

Technical Details

When the SAPUI5 bootstrap script file is loaded, a check is performed to see if the application is running on a mobile platform. If this is the case, the attribute and CSS classes are added to the HTML tag. The platform attribute value has the following connotation: Operating system + version, for example iOS6.0, Android4.1.1, bb10.0.9.2372, winphone8.0. Operating system can have the following values:

● iOS (Apple devices)● Android (Android devices)● bb (BlackBerry)● winphone (Windows Phone)

The version numbers are separated by dots. The possible values for the CSS class are:

● sap-ios (Apple devices)● sap-android (Android devices)● sap-bb (BlackBerry)● sap-winphone (Windows Phone)

The platform attribute or CSS class is used as follows:

● To provide a different font on Android devices, you specify your font by directly using the CSS class sap-android.

.sap-android{ font-family: Roboto;}

● Example for providing a different font when running on Android 2.x:

html[data-sap-ui-os^='Android2'] .sap-android{ font-family: "Droid Sans";}

1.4.18.4.5 Options for further Adaptation

In addition to the adaptations done automatically by SAPUI5, the application can apply further platform adaptations. To facilitate these adaptations, SAPUI5 provides a variety of detection mechanisms.



Mobile vs Desktop

It is getting more and more difficult to detect for the application whether it runs on a desktop or on a mobile device: Some Desktop computers support touch operations, keyboards can be attached to tablets, and you can detach laptop screens to use them as tablets.

Depending on your own definition of the distinction between desktop and mobile, you can detect touch capabilities, for example, by checking the following:var isTouchDevice = jQuery.support.touch;Based on this check, SAPUI5 provides also the following flag:var runningOnDesktop = jQuery.device.is.desktop;Other possibilities include checking the screen size or whether certain APIs or features are available.

Phone vs Tablet

The distinction between phone and tablet is also becoming more and more difficult as the phone sizes are growing and almost approach tablet sizes.

The current definition is that a device is a phone rather than a tablet as long as size of the screen is smaller than 600 pixels. This definition is used by the jQuery.device.is.tablet flag.

var runningInTablet = jQuery.device.is.tablet;The flag also contains additional information, such as:

● iphone, ipad: Flags whether the application runs on either of them● Desktop, phone: Alternatives to "tablet" (the distinction between desktop and tablet is made by checking

touch capabilities)


In the CSS, you can use CSS media queries to check screen sizes.

iOS vs Android and Version Information (as JavaScript API)

The jQuery.os object contains information about the operating system:

● os: Operating system as string ("ios", "android", "winphone", or "blackberry")● ios, android, winphone, blackberry: Boolean flags for the respective platform● version: Operating system version as string● fVersion: Operating system version as float




iOS vs Android vs Windows Phone vs BlackBerry - and Version Information (for CSS styling)

SAPUI5 also adds platform and browser version information to the root element (the <html> element of the page). There are different three information packages:

● The CSS class "sap-ios", "sap-android", "sap-winphone", or "sap-bb" (for BlackBerry) is added for easy platform-dependent styling.

● The attribute "data-sap-ui-browser" is added, providing more information about browser and version.● The attribute "data-sap-ui-os" is added, providing more information about operating system and version.

You can use the CSS class directly in cascades, the other two need attribute selectors which can also be used to match substrings:

.sap-ios .myControl { color: red; /* make my control red on Apple devices only */}

html[data-sap-ui-browser*=msf] .myControl { background-color: blue; /* Control should have a blue background whenever Mobile Safari is running... */}

html[data-sap-ui-os="iOS5.0"] .myControl { background-color: green; /* ...but when running on an Apple device with version 5.0 of the operating system, it should rather be green */}

For more information, see Platform Attribute for Mobile.

Orientation and Change of Orientation

The jQuery.device.is object contains information about the page orientation:

● landscape: Flag indicating whether the current orientation is landscape● portrait: Flag indicating whether the current orientation is portrait


If the orientation is changed, because the user rotates the device, the browser fires the orientationchange event. In some cases, this event seems to be delayed, and, therefore, the sap.m.App control fires its own orientationChange event based on the browser's window resize event:

myApp.attachOrientationChange(function(evt) { if (evt.getParameters().landscape) { // do something... }});

In CSS, you can use CSS media queries to check this.



1.4.18.5 Working with Lists

List

List can have the following properties:

● modeThis property defines in which way the left area of a list item will appear. You can show a single selection, multi selection, delete buttons, or none of these.The mode property can have the following values:

○ None (default)○ SingleSelect (on the right side)○ SingleSelectLeft (on the left side)○ SingleSelectMaster (without select control for use cases like the split app, by default the !

includeItemInSelection = true)○ MultiSelect○ Delete

● includeItemInSelection (default: false)This property defines the tap handling of a list item. By default, you can select an item by tapping the radio button or check box. To use the whole list item tap for selecting an item, change the property value to 'true'. This property is only relevant in selection mode.

● showUnread (default: false)This property decides whether an 'unread' indicator is added to each list item. When active, it shows a blue bubble for unread list items.

● showNoData (default: true)If set to 'true', a text is shown to the user if a list has no content . The default text is 'No data'. You can use the noDataText property to change the default text.

● noDataText (default: 'No data')

Swipe For Action

A user can swipe left on a list item to bring in a control, for example a button, and initiate an action for this item. This control is defined through the swipeContent aggregation of the list and will be displayed on the right or center of the list item. For more information, see Swipe List for Action.

List Events

For selection, deletion and swiping in lists, events are needed. The selection mode fires a 'select' event and the deletion mode a 'delete' event. A swipe left fires a 'swipe' event. These events contain information about the list item that caused the event.

● select (listItem)● delete (listItem)● swipe (listItem), see Events

Rerendering



A list including all its list items is rerendered when the data of a bound model is changed. Due to the limited hardware resources of mobile devices this can cause delays for lists with many list items. Therefore, we do not recomment the use of a list for these use cases.

ListItemBase

All SAPUI5 list items inherit from ListItemBase. It contains the navigation, selection and event features.

Five different types are available, which determine the way a list item is interacting. A list item has a content area (main area) which may fire a tap event and a navigation area on the right hand side, which may fire a tap or a detailTap event. The "type" property for each list item defines the events which are fired. This needs to be configured because it also decides the visual feedback a list item gives when touched.

NoteBy default, a list item does not fire an event unless it is configured with a type that defines how events are fired. An exception to this ActionListItem.

The following table shows the different combinations of list item types and events:

type tap event detailTap event icon active feedback

Inactive (default) -- -- -- --

Active yes -- -- yes

Navigation yes -- > yes

Detail -- yes (>) --

DetailAndActive yes yes (>) yes (only content)

ListItemBase has a 'unread' indicator property (default: false), which shows a blue bubble. This has to be enabled in the showUnread property. For the selections on each list item a selected property (default: false) exists. Another feature is the counter property (default: null), which shows integer numbers except zero. If the number is zero, the counter will be hidden.

● unread (default: false)● selected (default: false)● counter (default: undefined)

ActionListItem

The ActionListItem inherits all features from the ListItemBase and provides the following additional feature:

A text can be set, which will be center aligned.

text

this is a simple list item for triggering actions.



CustomListItem

This is a simple list item for triggering actions.

The CustomListItem inherits all features from the ListItemBase and provides following additional feature:

content can be aggregated.

The CustomListItem can be used for all list items SAPUI5 does not provide. You can build your own content and aggregate it.

Custom HTML

An easy way to cover simple CustomListItems is to add an HTML control, in which you can write your HTML either directly, or if you use a model and data binding, you can use a formatter to integrate it between the HTML.

Example: We have a model with first name, last name, age, and city properties. We create a CustomListItem, add a HTML control to the list item content and than write a formatter with our HTML code:

var myCustomListItem = new sap.m.CustomListItem({ content: new sap.ui.core.HTML({ content: { parts: [ {path: "firstName"}, {path: "lastName"}, {path: "age"}, {path: "city"} ], formatter: function(firstName, lastName, age, city) { return "<div><div class='myStyleClass'>Name: " + firstName + " " + lastName + "</div><div>Age: " + age +"</div><div>City: " + city +"</div></div>"; } }}), type : 'Navigation' //({type} if provided by the model) tap : myTapEvent});

CautionThis approach only works when you use JavaScript for the UI. When using a declarative model, such as XML Views, use an on-the-fly control, see Developing UI5 Controls in JavaScript.

DisplayListItem

The DisplayListItem inherits all features from the ListItemBase and provides the following additional features:

● label - for setting a label● value - for setting a value

InputListItem

The InputListItem inherits all features from the ListItemBase and provides following additional features:



● label - for setting a label● content - for content aggregation; you can set one of the following controls: Input button, radio button,

checkbox, slider, select, search

StandardListItem

The StandardListItem inherits all features from the ListItemBase and provides following additional features:

● title - for setting a title● descripton - for adding a description● icon - for adding an icon on the left hand side, which can be showen with or without an inset; the property

contains the icon source path to the location where all images for all device resolutions are stored● activeIcon - the property contains the icon source path for images that are shown while the list item is tapped● iconInset - default is 'false': Image takes the whole list item height; when set to 'true', the icon is rendered as

an inset● iconDensityAware - when set to 'false', no checks for other resolutions are made; use this option if you do not

want to provide icons with a specific resolution

1. An icon on the left side which can be shown with or without an inset.

2. A title can be set.

3. A description can be set.

● title● description● icon (Icon source path where all the images for each device resolution can be found.)● activeIcon (Icon source path for images which should be shown while the list item is tapped.)● iconInset (Default: false images takes the whole list item height, true for an inset.)● iconDensityAware (If you won't provide specific device resolution icons, set it to false. Therefore no checks fpr

other resolutions are made.)

1.4.18.5.1 Swipe for Action in Lists

If a user swipes left on a list item, you can bring in a control, for example a button, to initiate an action for this item. The button is displayed on the right hand side on center of the list item. An example is shown in the following figure.



1.4.18.5.1.1 Aggregation

This control is defined by the swipeContent aggregation of the list. You can add any control as swipeContent, but keep in mind that your content cannot be higher than a list item, see the following examples:

● Button swipeContent

var list1 = new sap.m.List({ swipeContent : new sap.m.Button({ text : "Approve", type : "Accept", tap : function() { /* ...approving code goes here... */

// we are done hide the swipeContent from screen list1.swipeOut(); } }) }), ...

● Control combination as swipeContent

new sap.m.List({ swipeContent : new sap.m.HBox({ items : [ new sap.m.Image({ src : "images/edit.png", tap : ... }), new sap.m.Image({ src : "images/delete.png", tap : ... }) ] }), ...

1.4.18.5.1.2 Events

List provides a swipe event when a user swipes left to bring in a control on the right hand side of the list item. This event is fired before the swipeContent is shown and contains the following three important parameters:

● listItem : List item that fired the swipe event● swipeContent: Specifies the swipeContent control to show on the right hand side of a list item● srcControl: Specifies the control that fired the swipe event

This means that you can dynamically change the swipe content according to the respective list item. If a list item, for example, has not yet been approved, the Approve button is shown. After approval or if it is already approved, the Disapprove button is shown. See the following example:

var list1 = new sap.m.List({ swipeContent : new sap.m.Button({ text : "Approve", type : "Accept", tap : function() {



/* ...approving code goes here... */

// we are done hide the swipeContent from screen list1.swipeOut(); } }) }), swipe : function(e) { // register swipe event var oSwipeListItem = e.getParameter("listItem"), // get swiped list item from event oSwipeContent = e.getParameter("swipeContent"); // get swiped content from event

// Check swiped list item if it is already approved or not if (oSwipeListItem.data("approved")) { // List item is approved, change swipeContent(button) text to Disapprove and type to Reject oSwipeContent.setText("Disapprove").setType("Reject"); } else { // List item is not approved, change swipeContent(button) text to Approve and type to Accept oSwipeContent.setText("Approve").setType("Accept"); } }, ...

Swipe events can be cancelled. The built-in controls which are working with swipe left events like Switch or Slider cancel a swipe event by default. If you also want to disable swipe events for your custom use case, you can call the preventDefault method of the event object. This is shown in the following example:

new sap.m.List({ swipe : function(e) { // get which control inside the list item fired swipe event var oSrcControl = e.getParameter("srcControl");

// check if the event is coming from Input if (oSrcControl instanceof sap.m.Input) { e.preventDefault(); // cancel swipe } }, ...

1.4.18.5.1.3 Methods

List provides the following two swipe methods:

● swipeOut( [callback] ): After swipeContent is shown, the user can interact with the control, for example tap it. After this interaction, for example on tap event, you can use this method to hide swipeContent from the screen. Per default, swipe for action works on auto hide mode. This means that if a user tries to tap inside the list but outside the swipeContent, then the swipeContent hides automatically. After you call this method, swipeContent hides with animation and if you need to run code after the animation you can simply add a callback function to this method as a first parameter.

● getSwipedItem(): This method returns the currently swiped list item. When no item is swiped, null is returned. The swipeContent events, for example tap, are a good place to use this method to get information for which list item swipeContent is shown.



The following example shows a delete scenario:

var list3 = new sap.m.List({ swipeContent : new sap.m.Button({ text : "Delete", type : "Reject", tap : function() { var oSwipedItem = list3.getSwipedItem(); // Get which list item is swiped to delete list3.removeAggregation("items", oSwipedItem); // Remove this aggregation to delete list item from list list3.swipeOut(); // we are done, hide the swipeContent from screen } }), ....

1.4.18.5.1.4 Properties

The swipeDirection property for lists is used to configure the direction of the swipe event. This property accepts an enumeration from sap.m.SwipeDirection? with the following values.

● LeftToRight?: Swipe from left to right● RightToLeft?: Swipe from right to left● Both: Both directions (left to right or right to left)

The default value is Both, but in some use cases we recommend to change this property, for example to prevent swipe conflicts.

1.4.18.6 Triggering Phone, SMS and E-Mail

With SAPUI5 for Mobile you can easily trigger native mobile phone applications such as e-mail, telephone, and text messages.

You can set predefined values for the application so that a user does not need to enter this information themselves. When personal information is displayed, for example phone numbers and e-mail addresses, you can initiate a phone call or e-mail with just one tap.

The URLHelper API contains the following triggers for telephone, texts, and e-mail applications:

● Trigger telephone application

sap.m.URLHelper.triggerTel( [Telephone Number] ); //Telephone number is optional

● Trigger text messaging application

sap.m.URLHelper.triggerSms( [Telephone Number] ); //Telephone number is optional

● Trigger e-mail application

sap.m.URLHelper.triggerEmail( [Destination Email], [Subject], [Default Message Text], [CC], [BCC] ); // All parameters are optional



● Redirect To custom URL

sap.m.URLHelper.redirect( URL ); //URL is required and can be used for custom protocols (e.g http, ftp, ...)

API Reference

● sap.m.URLHelper

1.4.18.6.1 Examples for Triggering Telephone, Text and E-Mail Applications

Sample data used in the examples:

var person = { name : "John Smith", tel : "+49 62227 747474", sms : "+49 173 123456", email : "[email protected]", website : "http://www.sap.com"};

You can trigger an external application at any time, but it is usually triggered as a reaction to a UI control throwing an event. The next sections illustrate some of the most typical use cases.

Click Button To Trigger Phone Call

The following button can be used to place a call. The figure shows, how the button looks like.

new sap.m.Button({ text : person.tel, icon : "images/action.png", /* Depends where your images are located */ tap : function() { sap.m.URLHelper.triggerTel(person.tel); }});



http://help.sap.com/disclaimer?site=https://sapui5.hana.ondemand.com/sdk/#docs/api/symbols/sap.m.URLHelper.html

Click Image To Trigger E-mail

The following code snippet gives an example for triggering an e-mail application. You can also set the subject and message of the e-mail application:

new sap.m.Image({ src : "images/website.png", /* Depends where your images are located */ tap : function() { sap.m.URLHelper.triggerEmail(person.website, "Info", "Dear " + person.name + ","); }});

Inside List

DisplayListItem with active feedback is the most popular use case for the following example.

new sap.m.DisplayListItem({ label : "Sms", value : "( " + person.sms + " )", type : "Active", tap : function() { sap.m.URLHelper.triggerSms(person.sms); }});

To use any other control inside the list, use InputListItem?:

new sap.m.InputListItem({ label : "Website", content : new sap.m.Button({ text : person.website, tap : function() { sap.m.URLHelper.redirect(person.website); } })});

1.4.18.6.2 Notes

● iOS does not trigger a phone call if the phone number contains "*" or "#".● You can add multiple recipients for a text message in Android phones by separating recipient numbers with

";".



● According to RFC 2368 you can set multiple subscribers for the e-mail application by separating each with ","; however, this still depends on the application. Outlook, for example, uses ";" as separator.

● You can use the sap.m.URLHelper.redirect method to use custom URL schemes:

○ For iOS: http://developer.apple.com/library/safari/#featuredarticles/iPhoneURLScheme_Reference/

Introduction/Introduction.html

○ For Android: http://developer.android.com/guide/appendix/g-app-intents.html

○ URI schemes: http://en.wikipedia.org/wiki/URI_scheme● If you just want to get a URI back without a redirect, you can use normalize methods which have the same

parameter as trigger methods, for example:

/* * These methods do not redirect but return URI scheme back as string. * All parameters are optional */sap.m.URLHelper.normalizeTel( [Telephone Number] );sap.m.URLHelper.normalizeSms( [Telephone Number] );sap.m.URLHelper.normalizeEmail( [Destination Email], [Subject], [Default Message Text], [CC], [BCC] );

1.4.18.7 Scrolling in SAPUI5 Mobile

Because of limited size of mobile devices, scrolling is an essential topic in mobile user experience. Smooth and easy scrolling is important for user acceptance of mobile applications.

In general, application programmers do not need to take care of scrolling when using the sap.m control library. Scrolling is provided automatically by the following controls:

● sap.m.Page● sap.m.Dialog● sap.m.Popover● sap.m.ScrollContainer

However, if you create a custom scrollable control, read the following sections.

1.4.18.7.1 Scrolling: Implementation Details

Unfortunately, scrolling support in mobile browsers is very weak and inconsistent. Only the newest platforms and browsers start to support partially usable scrolling functionality.

Hence, SAPUI5 embeds the open source livrary iScroll4 that takes care of scrolling in the application. Though the library is globally available in a SAPUI5 application, programmers should not call it directly. The sap.ui.core.delegate.ScrollEnablement delegate provides all functionality and smooth integration of iScroll4 into the SAPUI5 library.




http://help.sap.com/disclaimer?site=http://developer.apple.com/library/safari/#featuredarticles/iPhoneURLScheme_Reference/Introduction/Introduction.html

http://help.sap.com/disclaimer?site=http://developer.apple.com/library/safari/#featuredarticles/iPhoneURLScheme_Reference/Introduction/Introduction.html

http://help.sap.com/disclaimer?site=http://developer.android.com/guide/appendix/g-app-intents.html

http://help.sap.com/disclaimer?site=http://en.wikipedia.org/wiki/URI_scheme

Do not use nested scrolling

We do not recommend to use nested levels of scrolling, for example, when a page with enabled vertical scrolling contains a scroll container that has vertical scrolling too. Such combinations may lead to behavior that is unexpected both for programmers and users.

Implement a custom scroll container

A custom control that needs to provide a scrollable area for its content should implement the following steps:

1. Instantiate a sap.ui.core.delegate.ScrollEnablement delegate, at best in the .onAfterRendering callback.

2. Implement a .getScrollDelegate method that returns the current instance of the delegate to other controls.

3. Destroy the ScrollEnablement delegate on exit.

Example:

myCustomScroller.prototype.onAfterRendering = function() { if(!this._oScroller){ jQuery.sap.require("sap.ui.core.delegate.ScrollEnablement"); // attach a scroller to the scrollable container DOM element this._oScroller = new sap.ui.core.delegate.ScrollEnablement(this, this._scrollContainerId, { horizontal: false, vertical: true }); }};

myCustomScroller.prototype.getScrollDelegate = function() { return this._oScroller;};

myCustomScroller.prototype.exit = function() { if(this._oScroller){ this._oScroller.destroy(); this._oScroller = null; }};

NoteThough the SAPUI5 library includes also a Zynga scroller, it is an experimental alternative to iScroll4 that is not supported in SAPUI5 and may be used for testing only. The configuration parameter oConfig.zynga=true of the scrolling delegate should therefore not be used.

Interaction with the scroll containers

There are cases, when an embedded control controls scrolling of the parent container, if required. These are



● a sap.m.ScrollContainer inside a sap.m.Page may block parent scrolling, if it scrolls in the same direction itself;

● a sap.m.TextArea control in edit mode blocks parent scrolling, so that the user can scroll text contents during input;

● a sap.m.GrowingList control scrolls parent container to update positions of visible items after the new items have been loaded from the server.

When using a sap.m.FlexBox with fitContainer set to true inside of a page, the enableScrolling property of the page needs to be set to false for the FlexBox to fit the viewport.

1.4.18.7.2 Scrolling: Pull to Refresh

The SAPUI5 mobile library supports the "pull down to refresh" functionality that allows users to refresh lists or page content with fresh data from server.

To implement it, create a PullToRefresh control and put it as the first control into a page or a scroll container that contains the list that needs to be refreshed.

Example:var pullToRefresh = new sap.m.PullToRefresh({ description: getLastUpdatedTime(), refresh: function(){ pullToRefresh.setDescription("loading from server..."); //request new data from server getNewData({ // when data comes from server onSuccess: { pullToRefresh.hide(); pullToRefresh.setDescription(getLastUpdatedTime()); redrawList(); } }); }; The application should request new data on the refresh event and call the hide method when the data is received and the list is refreshed. You can provide a URL to a custom logo image with customIcon or switch display of logo of by setting showIcon to false. The first line of text "Pull to refresh" is standard and cannot be changed. However, you may set an optional description text to display, for example, the last update time.

NotePullToRefresh control is part of the scroll area and therefore its height is reflected in the scroll bar calculation and display. The user can see that the page can be scrolled down to reveal the pull-down area.

Carousel

Pull to Refresh does not work with a Carousel if both are contained in a page: in order to make Pull to Refresh work, the page has to enable scrolling which leads to problems with the Carousel (Carousel not visible). Suggested Workaround: Add a sap.m.PullToRefresh instance to each page that you add to your Carousel.



API References

sap.m.PullToRefresh

1.4.18.8 Running SAPUI5 Mobile Apps in Hybrid Web Containers

SAPUI5 provides the following two options for building mobile apps:

● Building the app as a web application loaded from a URL● Building the app as an hybrid app consisting of a native app wrapper, for example PhoneGap, and an HTML

viewer to display the SAPUI5 content on the user interface.

Hybrid apps have the advantage that you can publish them in app stores. Also, by embedding hybrid apps in the application code and the SAPUI5 library files in the hybrid container, you need to install the files only once and do not need to download them every time you start the application. But then the library size becomes important, because every user has to install the files, whereas in web applications the library is deployed on a server and you only need to download the required parts of the library at runtime.

To include the SAPUI5 resources you need in your hybrid app, use one of the following static packages for SAPUI5 mobile: sapui5-mobile-opt-static.zip or sapui5-mobile-static.zip. The library size of these packages is rather small because all unnecessary content has been removed, for example test pages. The packages contain the debug version as well as the optimized and minimized versions of all JavaScript files. Thus, you can use the packages for productive use as well as for debugging purposes. To use this package in an app wrapper, such as PhoneGap, unzip the package in the respective resource location of the app development project. The app wrapper build then includes the files and makes them available at runtime.

Optimization of the Package Size

Although the static SAPUI5 package is small enough to be included in hybrid apps, you can reduce the size further and optimize the content for a specific application by deleting additional files. The following list gives some examples:

● You can delete one of the following files from the /resources folder depending on your setup: sap-ui-core-nojQuery.js if you reference SAPUI5 normally or sap-ui-core.js if you reference the nojQuery and jQuery versions separately, for example if you run in a Sybase hybrid container.

● If you do not use makit charts, you can delete the complete makit folder in /resources/sap. The same applies to the sap.me control library.

● If you use the sap-ui-core.js file for bootstrap, you can delete the jquery and jqueryui folders in /resources/sap/ui/thirdparty. These files may be needed when you use the sap-ui-core-nojQuery.js script, but if you have another copy of jQuery available you can still delete the folder.

● Depending on the theme you use, you can delete the base and either the sap_bluecrystal or the sap_mvi folders in each of the /resources/sap/* ... */themes folders.



http://help.sap.com/disclaimer?site=https://sapui5.hana.ondemand.com/sdk/#docs/api/symbols/sap.m.PullToRefresh.html

NoteFor all JavaScript files, an optimized version and a debug (dbg) version exists. If you delete the files, make sure that you always delete both versions. If you can do without easy debugging and want to achieve a minimum installation size instead, you can delete all *-dbg.js files.

You can delete further files, but the size reduction is limited and to find out the files that are not required gets increasingly difficult.

You can also add additional control libraries such as the sap.viz chart library by copying the respective folder from the sapui5-static.zip file.

Device Ready Event

The hybrid web container needs some time for initialization. During this time, the sending of AJAX requests is blocked, meaning that JavaScript code stops once an AJAX request is sent and the code execution stops as well. This leads to a UI freeze effect.

The oData model in SAPUI5 uses AJAX requests internally and the oData model initialization must therefore be done after the hybrid container is ready to avoid a user interface freeze. After initialization, the hybrid web containers fires an event, which is called deviceready in PhoneGap. To fix this issue, move the code where the oData model is created and set the core object or any other controls' model property to the deviceready event listener.

Example:

<script>function appReady(){ sap.ui.getCore().setModel(new sap.ui.model.odata.ODataModel(<ODATA_URL>, false));}document.addEventListener("deviceready", appReady, false);</script>

Cross Domain Restrictions

If you load data from an external server or service using AJAX, the external domain has to be configured inside the hybrid web container to make the AJAX request go through the cross domain restriction. The following findings result from an integration of the SAPUI5 demo applications into PhoneGap:

● AndroidIf the AJAX code runs inside the webview in Android, no cross domain restriction exists. This means that you can load data using AJAX from everywhere. The PhoneGap documentation, however, still says that the domain needs to be configured in one XML file.

● iOS

The restriction in webview in iOS still exists and you need to add the domain that is visited using AJAX to a white list file to bypass the restriction. For detailed information about the white list file, see the PhoneGap documentation on the PhoneGap website.

1.4.18.9 Using Images in Mobile Applications

When using images in mobile applications, note the following.

Supporting Different Pixel Densities

Some mobile devices, starting with iPhone4 and iPad3, have a display with a very high density of pixels (four pixels where older models would only have one pixel). They are called "retina displays" by Apple to suggest they are as crispand clear as the eye can see. They use four physical pixels to display one logical CSS pixel, so images can be displayed much sharper when given twice as large as usually required because internally the device can use much more pixels to display all details of the image. Browsers on those displays do this automatically when images are scaled down.

So some devices support higher resolution images while others do not. We therefore recommend that SAPUI5 application developers provide image resources for all relevant densities to provide a very crisp and clear display of images on devices with "retina display".

The sap.m.Image control automatically chooses the right density, depending on the device on which it is displayed. If an image of a certain density is not available, the image control falls back to a default image, which should be provided as well.

NoteThe image control is also used implicitly by other mobile controls, for example

● Button● Segmented Button● Standard List Item

CautionIf you do not have higher resolution images you should set the densityAware property to false to avoid unnecessary roundtrips.



Example

Assume the following controls are displayed on a device with high-density screen (window.devicePixelRatio is 2):

new sap.m.Image({ densityAware: false, // tell the image control that there are no different optimized image variants src : "first.png" // therefore Image control will directly load first.png })

new sap.m.Image({ src : "second.png" // Image control will first look for [email protected], then fall back to second.png})

The first image control has been told that there are no image files for the different densities, so it will directly load "first.png". This image looks as good as other images on retina displays.

The second image control will first attempt to load [email protected] which should be twice as large as the normal image and would be scaled down for display, so it looks absolutely crisp on retina displays. If this file does not exist, it will fall back to "second.png", but this fallback will cause an additional server request.

Naming Conventions

Density related images are loaded if you provide an image name with density awareness in following format is provided:

[imageName]@[densityValue].[extension]

Currently, we support the densities 1.5 and 2. The follwing example shows a set of images with different densities:

● detail.png (default)● [email protected]● [email protected]

[email protected] (not supported any more, will use the standard image for such low density device)

1.4.18.9.1 Using Icon Font in SAPUI5

The sap-icon:// protocol supports the use of icons in your application based on the icon font concept, which an embedded font instead of a pixel image. Compared to image-based icons, icon font is easily scalable and you can change the color and apply various effects via CSS. SAPUI5 provides the sap.ui.core.icon control and a set of predefined icons is available in sap.ui.core.IconPool.



Using Custom Icons

To use your own icon font files in the sap.ui.core.Icon control, the font file needs to be declared with font-face tag in the CSS styles and the icon font file needs to be registered in sap.ui.core.IconPool. The required icon font file depends on the browser supported by your application. For Internet Explorer (IE) versions below IE9, the font files need the following extensions: .eot and .ttf. For other browser versions, only the .ttf extension is required.

To add custom icons, proceed as follows:

1. Declare the font-face tag in your CSS.Example for IE versions below IE9:

<style>font-face { font-family: 'SAP-icons'; /*Please replace 'SAP-icons' with your font name which will be used when register in sap.ui.core.IconPool*/ src: url('_PATH_TO_EOT_FILE_'); src: url('_PATH_TO_EOT_FILE_?#iefix') format('embedded-opentype'), /*?#iefix is required to be added to the end of the path of eot file here*/ url('_PATH_TO_TTF_FILE_') format('truetype'); font-weight: normal; font-style: normal;};</style>

Example for IE versions as of IE9:

<style>@font-face { font-family: 'SAP-icons'; /*Please replace 'SAP-icons' with your font name which will be used when register in sap.ui.core.IconPool*/ src: url('_PATH_TO_TTF_FILE_') format('truetype'); font-weight: normal; font-style: normal;};</style>

2. Call sap.ui.core.IconPool.addIcon with the following parameters for each character your icon supports:

○ iconName: This parameter defines the name of the current icon. The icon name is used together with the collection name as an identifier for the icon to address the icon via URI and must, thus, be unique within the collection.

○ collectionName: This parameter defines the name of an icon collection. Together with the icon name it is used to uniquely identify an icon in a URI.

○ fontFamily: This parameter matches the string you have used in the @font-face tag in CSS for the font-family property ('SAP-icons' in the code snippet in step 1).

○ content: This parameter defines the special character that represents this icon; use a format like 'e000' without escape character.

Referencing Icons

To reference icons, you assign the icon URI to a control by setting sURI for the control's corresponding property. To get the icon URI, the following two options exist:



● Call sap.ui.core.IconPool.getIconURI with the iconName property:

jQuery.sap.require("sap.ui.core.IconPool");var sURI = sap.ui.core.IconPool.getIconURI("accidental-leave");//please change the parameter to the name of your desired icon

● If you know the collection name and the icon name, write the icon URI directly in the following format:

sap-icon://[collection-name]/[icon-name]

NoteYou need the collection name only for custom icons. The URI for predefined icons does not need the collection name.

Using Icons in Controls

The following code snippet shows how the sap.m.Dialog control that already supported image URI has been adapted to also support icon URI. sap.ui.core.IconPool.createControlByURI returns an instance of sap.ui.core.Icon if sURI is an icon URI. Otherwise, the second parameter is called as a constructor method to create an instance. The sURI is set for the src property of the instance.

sap.m.Dialog.prototype.setIcon = function(sURI){ this.setProperty("icon", sURI, true); if(!jQuery.os.ios){ //icon is only shown in non iOS platform if(this._iconImage){ this._iconImage.setSrc(sURI); }else{ this._iconImage = sap.ui.core.IconPool.createControlByURI({ src: sURI //src is mandatory /* other properties can be put here, such as id, ...*/ }, sap.m.Image); } } return this;};

If the img tag is rendered directly in the control, and not by creating an image control, use the writeIcon method on sap.ui.core.RenderManager. The writeIcon method accepts an URI as the first parameter. Depending on this parameter, it renders either an img or a span tag. The classes and attributes defined in the second and third parameter are also added to the rendered tag.

Font face is inserted into the style sheet dynamically when Icon or writeIcon are used for the first time. If the special character needs to be written into the CSS to show the icon in a control, call the sap.ui.core.IconPool.insertFontFaceStyle function to insert the built in font face in your CSS. This is shown in the following code snippet:

jQuery.sap.require("sap.ui.core.IconPool");sap.ui.core.IconPool.insertFontFaceStyle();



Styling the Icon Control

If you render the icon span directly in your control, or use icon font in your CSS, you have the maximal freedom to style the Icon control.

If you use the icon by creating an instance of sap.ui.core.Icon within your control, however, use the CSS class sapUiIcon to add a new style to the icon. To avoid influencing the style of icons used elsewhere, wrap the icon CSS class with your control's root DOM class.

1.4.18.10 Message Handling

The following guidelines for message handling are recommended. We recommend to invest care and energy in good message content:

● Provide short and crisp error messages to the user.● A message should always contain a 'Call for Action'.● To achieve the above you need to map error messages from a backend system.● Focus on the most common error situations and improve the messages there.● For the rest simply state that a 'Backend' or 'Database' error has occurred. The user cannot handle this

anyway and no further details are required. If technically feasible, ease the process of receiving support from IT, for example submit the issue and related information to support or at least provide contact information.

● It is a must to detect all problems related to network connectivity and indicate them as such.

Messages Related to a Page

For showing messages to the user that are related to the currrent page you have two options depending on the importance of the message.

Message Dialog:

● A message dialog interrupts the user's workflow by blocking the current page and needs to be closed by the user.

● Use a message dialog if the message is important and must be acknowledged by the user.● The easiest way of showing a message dialog is to use the sap.m.MessageBox.● If you want full control of the content you can also use sap.m.Dialog control and set the type to

sap.m.DialogType.Message.● On iOS, a special visual design is applied to the dialog. On Android and Blackberry, the message dialog has the

same design as the standard dialog.



Message Toast:

● A message toast is an overlay that disappears after some time or if the user taps somewhere else. It does not block the user.

● Use this pattern if the message is less important and the user should not be blocked in his work.● You can open a message toast easily with sap.m.MessageToast.



Messages Related to Elements of a Page

For showing messages to the user that are related to a specific element of a page there is no dedicated UI control available in sap.m in this version. We recommend to use the sap.ui.core.HTML control to show these error messages 'somewhere close to the input' or use some kind of overlay. Consider that the user will have the on screen keyboard open which might hide messages. Putting the message above an input field could help.

You can set the ValueState of the sap.m.Input control to 'Error' to indicate that the content is not correct.

Multiple Messages

SAPUI5 Mobile does not support multiple messages at the same time. Mobile Designs recommend to be 'more sparse' with messages, that is, only show one message at a time. This can also be achieved by combining and reducing multiple messages.



1.4.18.11 Navigation Using Browser History

HTML 5 offers features, such as HTML pages that fetch data asynchronously and update the UI dynamically without reloading the page. However, the browser history back/forward buttons do not work any more because the URL of the application always stays the same.

This may be acceptable as a back button can be provided directly in the App which can be used instead of browser's back button. For some mobile platforms, however, such as Android, the user is used to using the physical back button to do back navigation inside an application. Thus, the back in the application is no option of choice for SAPUI5 Mobile.

1.4.18.11.1 What does the physical back button do?

If an application runs on a mobile device with a physical back button, tapping on the back button has the same effect as tapping on the browser back button. If no history state in browser history exists, it quits the browser application. This is also valid when application runs in a WebView using a hybrid container as long as the container does not interfere with the default behavior of the back button.

1.4.18.11.2 How should we support the physical back button?

An applications built with SAPUI5 Mobile runs through pages. After navigating to a new page, the user expects to go back to the previous page when tapping on the physical back button. This behavior assumption requires the following:

● Forward navigation to a new page must add a browser history state.● Back navigation to a previous page must ne triggered using the browser history.

With tje jQuery plugin jQuery.sap.history.js, a new history state can be added by changing the hash of the current URL with serialized state data which is sufficient to restore the current state when doing back navigation. jQuery.sap.history.js also provides an API for navigating back one or several steps through the browser history states.

For forward navigation (also called "to" navigation) and backward navigation (also called "back" navigation), two ways of triggering exist:

● "TO" navigation

○ triggered by controls, for example, tapping on a button to navigate to a new page○ triggered by browser history, that is, tapping on the browser forward button

● "Back" navigation

○ triggered by controls, for example, tapping on the back button in a page's header to go back to previous page

○ triggered by browser history, that is, tapping on the browser back button or the physical back button

The image below illustrates how the four options for trigger handling:



The following sections describe the four options:

"TO" triggered by controls

When "TO" navigation is triggered by controls, a new history state needs to be added to the browser history with the new page information. Later, when doing a back navigation, a history state is popped out from browser history and we can decide which page we go back to by checking the information saved with the history state.

"TO" triggered by browser history

"TO" navigation can also be triggered by tapping on the browser forward button. We don't need to add a new history state because the history state has been added to browser history already. By checking the saved information with this history state, we know which page we go forward to.

"BACK" triggered by controls

In order to support the physical back button, we are required to do every back navigation through the browser history. Thus when back navigation is triggered by a control, we ask the browser history to go back one or several steps by calling the provided API in jQuery.sap.history.js. The following behaviors are the same as Back triggered by browser history.



"BACK" triggered by browser history

When back navigation is triggered by browser history either the browser back button or the physical back button on mobile device is tapped, a history state is popped out from browser history. By checking the saved information with history state, we can navigate to the specified page.

1.4.18.12 Mobile Events

The following is the same for mobile events and Desktop events:

● When running on mobile or touch devices, the application has still the possibility to access to all native browser events, including the touch-related ones.

● Handling of control events fired by SAPUI5 is also the same as on desktop PCs.● When implementing SAPUI5 controls, some browser events can be handled very easily by implementing a

method named on<eventName>, so all the bind/unbind effort is avoided. This is equally possible on mobile.

Basically the whole concept of events is identical.

1.4.18.12.1 Additional Events for Mobile Applications

The difference between mobile and desktop events is that on mobile devices additional events are available within control implementations. They are introduced in the following sections.

Additional Mobile Browser Events

On touch-enabled platforms the following events are also provided within UI5 controls to be handled in on<eventName> methods:

● touchstart● touchend● touchmove● touchcancel

Additional Mobile Pseudo Events

jQuery mobile event handling is used in SAPUI5 when running on touch-enabled devices. From the basic browser events it creates semantically richer events. Some of them are also provided automatically in SAPUI5 controls:

● swipe



● tap● swipeleft● swiperight● scrollstart● scrollstop

For more information, see the jQuery mobile documentation.

Simulation of touch events on non-touch platforms

For testing or demonstration purposes, the events listed above can also be simulated on non-touch devices. When this simulation is enabled, the touch events will also be triggered by mouse interaction.

NoteDue to technical constraints the simulation cannot be perfect, so it may not be used in productive code.

To enable the simulation mode, set the SAPUI5 configuration parameter xx-test-mobile to 'true', for example by appending the URL parameter sap-ui-xx-test-mobile=true.

1.4.18.12.2 Events also available in Desktop Apps

This section lists all events that are available in control implementations in all SAPUI5 applications:

Browser Events

● click● dblclick● focusin● focusout● keydown● keypress● keyup● mousedown● mouseout● mouseover● mouseup● select● selectstart● dragstart



● dragenter● dragover● dragleave● dragend● drop● paste

Pseudo Events

The "pseudo events" can be used in on<eventName> methods inside controls like browser events, but are created by SAPUI5 and typically have enriched semantics:

For the detailed meaning of each event, see

● sapdown● sapdownmodifiers● sapshow● sapup● sapupmodifiers● saphide● sapleft● sapleftmodifiers● sapright● saprightmodifiers● saphome● saphomemodifiers● saptop● sapend● sapendmodifiers● sapbottom● sappageup● sappageupmodifiers● sappagedown● sappagedownmodifiers● sapselect● sapselectmodifiers● sapspace● sapspacemodifiers● sapenter● sapentermodifiers● sapexpand● sapbackspace● sapbackspacemodifiers● sapdelete



● sapdeletemodifiers● sapexpandmodifiers● sapcollapse● sapcollapsemodifiers● sapcollapseall● sapescape● saptabnext● saptabprevious● sapskipforward● sapskipback● sapprevious● sappreviousmodifiers● sapnext● sapnextmodifiers● sapdecrease● sapdecreasemodifiers● sapincrease● sapincreasemodifiers● sapdelayeddoubleclick

1.4.18.13 Styling and Theming Mobile Controls

CSS is used in mobile applications to provide the visuals of controls, just like for Desktop controls. The main differences are:

● The mobile browsers supported by SAPUI5 are all based on Webkit. This allows using advanced CSS3 features which are not available in all supported desktop browsers.

● "em" and "rem" should be used for dimensions.

Using LESS Features like Theme Parameters

When controls are created with Eclipse tool support, the CSS files are processed by the "LESS" Open Source CSS preprocessor. Just like in desktop control CSS files, LESS features, in particular variables or "theme parameters", can be used.

1.4.18.14 Building Charts with MAKit

The MAKit Chart is a SAPUI5 control that provides charting features. MAKit chart is designed for mobile and tablet use. It has unique features such as Value Bubble and Range Selector that make chart report much more rich and interactive.



MAKit chart supports the following touch interactions on mobile devices:

● tap to highlight certain part of the chart● double tap● two finger pince to zoom in or out● one finger drag to move chart's Value Bubble highlight● two finger swipe to scroll the chart when zoomed in

Currently, it supports the following chart types:

● Column● Horizontal Bar (Table Bar)● Line● Bubble● Pie● Donut

The value bubble provides an interactive way of showing details of the chart. It provides detailed information, that is, the value of the highlighted chart region. A user can hide or show specific series of the chart by toggling the legends on the value bubble.

The range selector provides an overview of the whole chart to the user and also allows to zoom in or out to a specific part of the chart.

The following controls and elements are provided in the sap.makit library:

● sap.makit/Chart – SAPUI5 chart control (type: sap.ui.core/Control)● sap.makit/Axis – Base type for the chart’s axis (type: sap.ui.core/Element)



● sap.makit/CategoryAxis – Properties of the chart’s category axis (type: sap.makit/Axis)● sap.makit/ValueAxis – Properties of the chart’s category axis (type: sap.makit/Axis)● sap.makit/Category– Properties of the chart’s category axis (type: sap.makit/Element)● sap.makit/Value – Properties of the chart’s value axis (type: sap.makit/ Element)● sap.makit/Series – Properties of the chart’s series (type: sap.ui.core/Element)● sap.makit/Row – Row collection for data binding (type: sap.ui.core/Element)● sap.makit/Column – Column mapping for data binding (type: sap.ui.core/Element)● sap.makit/ValueBubble – Properties for the chart’s value bubble (type: sap.ui.core/Element)

Simple Types:

● sap.makit/ChartType – Enumeration for chart type (type: string)● sap.makit/SortOrder – Enumeration for category’s sortOrder (type: string)● sap.makit/LegendPosition – Enumeration for legendPosition (type: string)● sap.makit/ValueBubbleStyle – Enumeration for the value bubble’s positioning style (type: string) for

non-Pie/donut/HBar chart● sap.makit/ValueBubblePosition – Enumeration for the value bubble’s position on pie/donut Chart

(type: string)

1.4.19 Testing SAPUI5 Applications in Eclipse

You have different options to test your applications locally in Eclipse.

Prerequisites

You have created a SAPUI5 application using the SAPUI5 application development tools, see Developing Applications Using SAPUI5 Tools.

Procedure

1. To use SAPUI5 application preview, see Test in SAPUI5 Application Preview2. To use a Java Web Server, see Test Your SAPUI5 Application on a Java Web Server [page 268]

Next Steps

If you have created a SAPUI5 application for a mobile target device, the application can only run in a WebKit-based browser. You can, however, use the mentioned options for testing your application locally in Eclipse and copy and paste the URL into a WebKit-based browser.



If your application has to access resources on a back-end system (OData), you must enable the back-end access for local testing.

1.4.19.1 Test in SAPUI5 Application Preview

You access the SAPUI5 application preview using the Web App Preview, provided with the embedded Jetty server. You can quickly check on your application and open it in the default browser.

Prerequisites

NoteJetty provides an internal web preview used in the SAPUI5 application preview. As of the Juno release of Eclipse, this features needs to be installed explicitely.

Procedure

1. To test the new application with the application preview in an embedded Jetty server, right-click the HTML file or the project node and choose Run As Web App Preview . Everything is configured automatically.

2. To refresh after having changed a file of your SAPUI5 application, choose Refresh on the left hand side of the preview editor to refresh the SAPUI5 preview.

3. To check the files of your SAPUI5 application project in an external browser, choose Open in external browser on the right hand side of the preview editor. This function opens the external browser which is specified in the Eclipse preferences under General Web Browser . This is usually the default browser of your PC. For other external browsers, you can also copy the URL from the text field of the editor to the external browser.

Open in External Browser



1.4.19.2 Test Your SAPUI5 Application on a Java Web Server

Prerequisites

To test the application in a Java Web Server environment, ensure that the corresponding Server Adapter Eclipse Plugin is installed.

Procedure

To test the new application, right click the new project and choose Run As ... Run on Server . Select a server (for example, Apache Tomcat), and choose Finish.

Related Information

Set up Tomcat to test SAPUI5 applications [page 268]To test on a Java web server, you can install an Apache Tomcat.

Use a SimpleProxyServlet for Testing to Avoid Cross-domain Requests [page 269]If you are testing locally in your Java Eclipse environment and you want to access an OData service in the ABAP system, a proxy is needed to ensure the same origin policy. In an SAPUI5 application project you can use a SimpleProxyServlet for local testing.

1.4.19.2.1 Set up Tomcat to test SAPUI5 applications

To test on a Java web server, you can install an Apache Tomcat.

Prerequisites

The recommended versions of Tomcat are 6.0 or higher.

Procedure

1. Download Tomcat from the respective web site. You can either install the Windows Service Installer, or download and unzip the zip file (you can find the startup script in the bin folder).



2. To deploy your application, choose one of the following options:

○ Without EclipseTo deploy SAPUI5 on Tomcat without Eclipse, you can set up a Tomcat user with manager privileges (see the Tomcat documentation) and use the tomcat manager application for deployment. We recommend, however, to just move your war file into the webapps folder inside the tomcat directory. Tomcat takes care of the deployment, but a restart may be necessary.If you run Tomcat without Eclipse, set the environment variable JAVA_HOME to JDK6

○ In EclipseTo run web applications in Eclipse, you need to register the Tomcat web server.

1. Open the Java EE perspective in Eclipse.2. Open the Servers view, for example by pressing CTRL + 3 and then entering Servers.

3. To open the New Server wizard, choose New Server from the context menu.

4. Choose Apache Tomcat 7.0 and add a new server runtime by pointing to the folder in which you have unzipped the Tomcat installation files. Finish the wizard. You should now see Tomcat v7.0 server in the Servers view.

5. Open the configuration overview by double clicking the Tomcat v7.0 server in the Servers view. Select the Serve modules without publishing server option.

1.4.19.2.2 Use a SimpleProxyServlet for Testing to Avoid Cross-domain Requests

If you are testing locally in your Java Eclipse environment and you want to access an OData service in the ABAP system, a proxy is needed to ensure the same origin policy. In an SAPUI5 application project you can use a SimpleProxyServlet for local testing.

CautionBe aware that due to security reasons the SimpleProxyServlet is restricted to local testing purposes only. It can only be used for local host scenarios (accessing Gateway services to avoid cross-domain issues) and will not work when deployed on an application server. For productive use, refer to a mature proxy servlet.

NoteIf you have issues with accessing HTTPS systems via the ResourceServlet or the SimpleProxyServlet it may be necessary to import the root certificate into the Java keystore.

.

Ideally, all OData service URLs should be in one file to make the exchange easier - either in the index.html, or in one separate .js file which needs to be included. The application is responsible for exchanging the URLs before checking in and after checking out to SAPUI5 Repository. You can also use the helper function getServiceUrl for which also the application is responsible. See the following example:

#!java<script>//var serviceUrl = "/mypath/myservice"; //url when running on the ABAP system//var serviceUrl = "proxy/mypath/myservice"; //url when running locally in Eclipse



As the SimpleProxyServlet automatically uses the proxy settings from your Eclipse this can be configured in Eclipse under Window Preferences , and select General Network Connections . Here you can specify the proxy entries and the proxy bypass.

For example, set Active Provider to Manual, Schema=HTTP, Host=proxy, Port=8080 under proxy entries and localhost, *.sap.corp as Host under proxy bypass.

Simple Proxy Servlet - Restriction Regarding DELETE Requests

The simple proxy servlet currently does not support the sending of HTTP DELETE requests with content. This is due to restrictions of the Java SE functionality that is used. If an HTTP DELETE request with content is sent, an HTTP 500 result status is sent with the description: "The HttpUrlConnection used by the SimpleProxyServlet doesn't allow to send content with the HTTP method DELETE. Due to spec having content for DELETE methods is possible but the default implementation of the HttpUrlConnection doesn't allow this!"

For practical purposes, this restriction should have only minor effects. This is because:

● When applying a REST-like programming style, an HTTP DELETE request would use the URL to transmit which objects should be deleted, but not the content.

● When building your own protocol that uses the content of the HTTP request, you typically use HTTP POST.

1.4.20 UI development toolkit for HTML5 Test Suite

The test suite is an integral part of the UI development toolkit for HTML5 (SAPUI5) core library and is, thus, automatically available for applications using SAPUI5. To start the test suite, add the URL path 'resources/testsuite' to your application URL, for instance http://localhost:8080/demokit/resources/testsuite for the 'demokit' application.

Content of the Test Suite

The test suite provides functionality related to inspecting and trying all aspects of SAPUI5 controls. It consists of the following screen areas:

● Test pages tree on the left top screen area: Different test pages for controls etc. can be selected here.● Preview area on the center top screen area: The page selected in the test pages tree is rendered here and can

be used and tested.● Control tree on the right top screen area: The hierarchy of the development toolkit controls is displayed here;

you can select controls in the tree, which will then be highlighted in the preview area.● Property sheet on the right bottom screen area: Once you have selected a control in the test pages tree, its

properties are displayed on the property sheet and can also be modified. Choose Apply Changes after modifying.

● Event log on the center bottom screen area: Trace output as well as all control events are displayed here.● Settings preview on the left bottom screen area: Here you can adjust how the page is rendered. You can, for

example, select one of the themes delivered with SAPUI5, or enter the name of a theme, which you created.



1.4.20.1 Using the SAPUI5 DiscoveryServlet to Automatically Find Test Cases

SAPUI5 automatically detects test cases for controls by means of the DiscoveryServlet. To use this service, the application must configure the servlet in its web.xml as follows:

#!xml





<servlet> <display-name>DiscoveryServlet</display-name> <servlet-name>DiscoveryServlet</servlet-name> <servlet-class>com.sap.ui5.discovery.DiscoveryServlet</servlet-class> <load-on-startup>1</load-on-startup></servlet>

<servlet-mapping> <servlet-name>DiscoveryServlet</servlet-name> <url-pattern>/discovery/*</url-pattern></servlet-mapping>

The servlet discovers all HTML files located inside the test-resources/<ui-library-name> folder of the web application and all resources inside the modules (JAR files) where the location is META-INF/test-resources/<ui-library-name>.

1.4.21 Localized Texts

The framework concepts for text localization in SAPUI5 are aligned with the general concepts of the Java platform. The main components of the concept are:

● Identifying languages/locales, see Identifying the Language Code/Locale● Storing and accessing texts in multiple languages (resource bundles), see Resource Bundles● Using localized texts in the application, see Use of Localized Texts in Applications

1.4.21.1 Identifying the Language Code / Locale

For the identification of languages, the framework uses a language code of type string. Currently, SAPUI5 accepts the following two syntax forms:

● The Java Locale syntax that combines a lower case ISO 639 alpha-2 or alpha-3 language code with an ISO 3166 alpha-2 country code. Both codes are combined with an underscore. An arbitrary sequence of variant identifiers (also separated by underscores) can be appended as a third component.Example: en_US, zh_TN_Traditional

● Language codes according to the defacto standard BCP 47 (see IETF BCP-47). Most modern browsers use these codes for language identification. As of JDK 1.7 the Java locale class supports them as well.Example: bs-Cyrl-BA, i-klingon

Current Language Code / Locale

SAPUI5 has the notion of a current language. It is determined from the following sources of information. The sources are ordered increasingly by priority and the last available user language/locale wins:

1. Hard-coded UI5 default locale ('en')2. Potentially configured user language (window.navigator.userLanguage)3. Potentially configured browser language (window.navigator.browserLanguage)4. General language information from the browser (window.navigator.language)5. Locale configured in the application coding (jsdoc:symbols/sap.ui.core.Configuration)6. Locale configured via URL parameters

You use the configuration API to retrieve the resulting current language as follows:

var sCurrentLocale = sap.ui.getCore().getConfiguration().getLanguage();

NoteThe syntax of the returned value depends on the syntax used for configuration. If the information source is one of the browser language properties, the returned language most likely is in BCP-47 format. If it is configured as a URL parameter, the user might have choosen the JDK Locale syntax.



NoteIn the Internet Explorer (IE), none of the window.navigator.* properties reflects the settings of the Language Preference dialog in IE. Instead, IE returns the language of the OS installation as browserLanguage and the language from the OS regional settings as userLanguage. As a result, the settings in the Language Preference dialog cannot be taken into account for the current language of SAPUI5. This is often confusing for developers and a known shortcoming in IE. The only way to circumvent this is an additional server request where IE provides the corresponding setting in theAccept-Language header. As this technique requires a backend component and SAPUI5 must be able to run without any server component, such a request is not implemented yet.

1.4.21.2 Resource Bundles

Resource bundles are a collection of *.properties files. All files are named with the same base name (prefix identifying the resource bundle), an optional suffix that identifies the language contained in each file, and the fixed .properties extension. The language suffixes are formed according to the older JDK locale syntax. By convention, a file without a language suffix should exist and contain the raw untranslated texts in the developer's language. This file is used if no more suitable language can be found.

A resource bundle file is a Java properties file (as described in the Javadoc of class java.util.Properties). It contains key/value pairs where the values are the language-dependent texts and the keys are language independent and used by the application to identify and access the corresponding values.

When a localized text is needed, the application uses the SAPUI5 APIs to load the properties file that matches the current language best. The same applies to any other localized data that can be represented as a string, for example, a date formatter string. To retrieve a text from the properties file, the application uses the (language-independent) key. If no text can be found for this key, the next best matching file is loaded and checked for the text. Finally, if no file matches, the raw file is loaded and checked.

The resource bundle sap.ui.commons.message_bundle consists of the following individual files:

● sap.ui.commons.message_bundle.properties: Contains the raw texts form the developer, determines the set of keys

● sap.ui.commons.message_bundle_en.properties: Contains English texts (without a specifc country)● sap.ui.commons.message_bundle_en_US.properties: Contains texts in American English● sap.ui.commons.message_bundle_en_UK.properties: Contains texts in British English

1.4.21.3 Use of Localized Texts in Applications

SAPUI5 provides the following options to use localized texts in applications:

● Using the jQuery.sap.resources module● Using data binding



Using jQuery.sap.resources

You can use the JavaScript module jQuery.sap.resources to access localized texts. The module contains APIs to load a resource bundle file from a given URL and for a given locale.

To make sure that the jQuery.sap.resources module is loaded, you have to require it as follows:

jQuery.sap.require("jquery.sap.resources");

You can then use the jQuery.sap.resources function to load the resource bundle from the given URL, that is, the bundle name, and for a given locale. When no locale is specified, a default locale (en) is used. The following code snippet shows the use of the jQuery.sap.resources function to return a jQuery.sap.util.ResourceBundle:

var oBundle = jQuery.sap.resources({url : sUrl, locale: sLocale});

For more information, see jQuery.sap.resources in the API Reference.

The resource bundle jQuery.sap.util.ResourceBundle provides access to the localized texts that are contained in the resource bundle. You can use the getText method to access the texts in the loaded bundle by means of their key. This is shown in the following code snippet:

var sText = oBundle.getText(sKey);

Localization Test Page

The test suite provides a test page that shows how to use localized texts. This section only provides a short overview how the jQuery.sap.resources module is used there.

For a localized Web page you need the .html page itself and the .properties files of the required languages, in this example English and German.

The resource bundle i18n.properties is the English fallback version, which is the default version.

welcome=Welcome {0}. Please enter a new contact:lastname=Last Name:firstname=First Name:street=Street:zip=ZIP:city=City:

The resource bundle i18n_de.properties contains the texts in German. The following code snippet shows the content of this file:

welcome=Willkommen {0}. Bitte geben Sie einen neuen Kontakt ein:lastname=Nachname:firstname=Vorname:street=StraÃŸe:zip=PLZ:city=Ort:



The localization test page uses these texts to display a welcome message and a form to enter the address of a person. The coding of the test page looks as follows:

jQuery.sap.require("jquery.sap.resources");var sLocale = sap.ui.getCore().getConfiguration().getLanguage();var oBundle = jQuery.sap.resources({url : "res/i18n.properties", locale: sLocale});var oMatrixLayout = new sap.ui.commons.layout.MatrixLayout();oMatrixLayout.setLayoutFixed(false);oMatrixLayout.createRow( new sap.ui.commons.TextView({text: oBundle.getText("welcome", ["Administrator"])}) );oMatrixLayout.getRows()[0].getCells()[0].setColSpan(2);oMatrixLayout.createRow( new sap.ui.commons.Label({text: oBundle.getText("lastname")}), new sap.ui.commons.TextField());oMatrixLayout.createRow( new sap.ui.commons.Label({text: oBundle.getText("firstname")}), new sap.ui.commons.TextField());oMatrixLayout.createRow( new sap.ui.commons.Label({text: oBundle.getText("street")}), );oMatrixLayout.createRow( new sap.ui.commons.Label({text: oBundle.getText("zip")}), new sap.ui.commons.TextField());oMatrixLayout.createRow( new sap.ui.commons.Label({text: oBundle.getText("city")}), new sap.ui.commons.TextField());oMatrixLayout.placeAt("userForm");

With regard to localization, the code above defines the following procedure:

1. Require the jQuery.sap.resources module2. Determine the language3. Load the resource bundle4. Access the text using the welcome key and pass the value for the placeholder ({0}) via an array5. Access the text using the lastname key and set it as text for the Label

Data Binding

You can also use data binding to access localized texts. The ResourceModel is a wrapper for resource bundles that exposes the localized texts as a model for data binding. You use the ResourceModel to bind texts for control properties to language dependent resource bundle properties. You can instantiate the ResourceModel either with bundleName (name of a resource bundle that equals a SAPUI5 module name within the require/declare concept), or a bundleUrl, which points to a resource bundle. When you use the bundle name, make sure that the file has a .properties suffix. If no locale is defined, the current language is used.

var oModel = new sap.ui.model.resource.ResourceModel({bundleName:"myBundle",bundleLocale:"en"});var oControl = new sap.ui.commons.Button( { id : "myButton", text : "{i18n>MY_BUTTON_TEXT}"});



// attach the resource model with the symbolic name "i18n"oControl.setModel(oModel, "i18n");

NoteThe current data binding implementation does not allow to pass parameters to your texts in the resource bundle. If you have to pass parameters, you must do this on your own. You can, however, access the resource bundle directly from the model instead of loading it:

var myBundle = oModel.getResourceBundle()

After the instance has been created, you have a model containing the resource bundle texts as data.

For a complete overview of available methods and parameters, see the API Reference: ResourceModel

1.5 References

1.5.1 Compatibility Rules

SAPUI5 plans to be a so-called Release Independent Component (RIC). An important constraint for this is that it must be as simple as possible to upgrade to a newer version. This makes compatibility rules so important.

The following sections explain the meaning of compatibility with regard to the SAPUI5 application and control development. A version flag for the bootstrap indicates to the core to which previous SAPUI5 version the current functionality should be compatible to.

Versioning Scheme

SAPUI5 uses a 3 digit version identifier, for example 1.4.3. The digits have the following meaning:

● The first digit (1) specifies the major version number.● The second digit (4) specifies the minor version number.● The third digit (3) specifies the patch version number.

New releases of SAPUI5 are described by the major and minor version number. The patch version number is only used to identify patches within a release.

API Evolution

If not mentioned differently, in the following paragraphs "API" refers to "public API", meaning functions, classes, namespaces, controls with their declared properties, aggregrations, and so on. The sole definition of the public



http://help.sap.com/disclaimer?site=https://sapui5.hana.ondemand.com/sdk/#docs/api/symbols/sap.ui.model.resource.ResourceModel.html

API is the SAPUI5 Library - Core & Standard Controls (API Reference Documentation, JSDoc), which is available in the Demo Kit. Features that are not mentioned in the SAPUI5 library are not part of the API.

The following rules apply for introducing new APIs or making incompatible changes to existing APIs:

A major release, that is, a release with a new major version can introduce new APIs or make incompatible changes to existing APIs. If this is the case, the incompatibilities are described in the Release Notes.

A minor release, that is, a release with a new minor version can introduce new APIs, but does not contain incompatible changes to APIs, which have been introduced in the same major release.

A patch release, that is, a release with a new patch version, only contain fixes to the existing implementation, but do not introduce new features or incompatible API changes.

NoteExceptions to these rules are possible, but only in very urgent cases, such as security issues. The exceptions are documented in the Release Notes.

Compatible Changes

The following changes to existing APIs are compatible changes:

● Adding new libraries, controls, classes, properties, functions, namespaces to the API● Generalizing properties, that is, moving properties up in the inheritance hierarchy● Changing the logging behavior, that is, adding or removing log output, modifying the content of existing log

output; logging is not part of the API● Adding new values to enumeration types; this means that when dealing with enum properties, always be

prepared to accept new values, for example, by implementing a "default" or "otherwise" path when reacing on enum values

● Modifications to the markup or style (HTML, CSS) of controls

Incompatible Changes

The following changes to existing APIs are incompatible and are only implemented in major releases:

● Removing an API (library, namespace, function, property, control, events, and so on)● Renaming an API (library, namespace, function, property, control, events, and so on)● Removing support for parameters● Removing support for configuration entries● Reducing the visibility of an API; this does not break JavaScript applications, but changes the contract● Removing or reordering parameters in an API signature● Reducing the accepted value range, for example, parameter of a function● Broadening the value range of a return value (or property); exception: Enumerations● Moving JavaScript artifacts (namespaces, functions, classes) between modules● Replacing asserts by precondition checks



● Moving properties, etc., down in the inheritance hierarchy● Changing the name of enum values● Changing defaults (properties, function parameters)● Renaming or removing files

If possible, SAPUI5 marks old artifacts as deprecated and creates new artifacts, if applicable, instead of incompatible changes. A deprecation documentation in the SAPUI5 library and maybe a log entry in the implementation explain why and when an artifact has been deprecated and provide hints how to achieve the same results without deprecated functionality.

CautionSome of the new functionality or controls are in an experimental development state and documented as such. These features are still under development and changes to their API are very likely; inthese cases, even incompatible changes in minor releases may occur. They are included in public releases to collect feedback from early adopters. Consumers of such APIs must understand that their respective code might be broken (repeatedly) when upgrading to new SAPUI5 releases and they must be willing to adapt to such changes.

1.5.1.1 Third Party Open Source Libraries

SAPUI5 contains and uses several third party open source libraries, for example, jQuery. These libraries can also be used by applications and/or custom control libraries, but the SAPUI5 compatibility policy described within this document does not apply to these third party libraries.

If you want to use the contained third party open source libraries, note the following restrictions:

● SAP decides which version(s) and modules of the used libraries are provided.● SAP can upgrade to higher version(s) of the used libraries even within a micro release.● For important reasons such as security SAPUI5 can stop providing a library.● The third party libraries are provided "as is". Extensions, adaptations, and support are not done by SAP.

NoteFor closed source libraries, a use beyond the use of the corresponding SAPUI5 controls is not allowed.

For a list of the third party open source software used in SAPUI5, see Third Party Open Source Libraries .

1.5.1.2 Exceptions: Important to Know

Not part of the public API are all functions, and so on, which are not declared as public in the SAPUI5 library. Also not part of the API is the rendered HTML and the CSS of the controls. This means in particular that the below mentioned scenarios can cause problems, also when switching minor or micro versions. The support for these problems provided by SAP can only be limited, and an adaptation of non-SAPUI5 coding may be necessary. JavaScript facilitates the modification of code that belongs to someone else, for example, enriching prototypes of



http://help.sap.com/disclaimer?site=https://sapui5.hana.ondemand.com/sdk/#resources/sap/ui/thirdparty/readme.html

foreign classes, adding properties or functions to existing objects. This should not be forbidden, but the consequences, meaning the risk of conflicts when SAPUI5 is enhanced, must be clear.

Scenarios:

● Manipulation of HTML/CSS, for example via jQuery, control.addStyleClass, or directly via CSS● Using or overriding non-public functions, etc.● Creation of new controls, for example "Notepad-Controls" based on existing controls (inheritance) or

subclassing in general; new classes also depend on private functionality of the super classes, collision of generated functions for properties, aggregations are possible

● Pixel-perfect compatibility is not guaranteed for SAPUI5 owned controls and, thus, also not guaranteed for controls inheriting from SAPUI5 controls.

1.5.2 Naming Conventions for Control and Application Development

The following sections introduce the naming conventions for control and application development for SAPUI5.

1.5.2.1 Naming Conventions for Control Artifacts

We recommend to use following naming conventions for control artifacts:

● Start control names with an upper case letter and use camel case for concatenated words, for example MatrixLayout.

● Start control property names with a lower case letter and use camel case for concatenated words, for example colSpan.

● Start control event names with a lower case letter and use camel case for concatenated words, for example: press.

● Start control method names with a lower case letter and use camel case for concatenated words, for example doSometing.

● Start control aggregation names with a lower case letter and use camel case for concatenated words.● Start control association names with a lower case letter and use camel case for concatenated words.● For control, property, event, and relation names use unique names to avoid name clashes in generated

classes.● Start parameters of control events with a lower case letter.

NoteSAPUI5 tools check and enforce some of these rules.

The generated setter/getter methods for properties as well as the generated methods for events for the aggregations and associations use camel case notation, for example attach<EventName>.

SAPUI5 controls have constructors, which accept a set of properties and events as JSON string. The framework expects that the names used as keys in a JSON string exactly match the case of the defined control properties and events.



If SAPUI5 controls are exposed as tags, the tag name and its attributes should fit the following naming conventions:

● Start tag names with a lower case letter and use camel case for concatenated words. Except for the lower case of the first character, tag names should match the name of the control to create a relation between the tag and the respective control, for example matrixLayout.

● Start tag attributes with a lower case letter and use camel case for concatenated words, for example colSpan● Name tag attributes for event handlers in lower case letters as follows: on<event-name>; for example onpress

1.5.2.2 Reserved Characters for Control IDs

The SAPUI5 framework regards the dash '-' as a forbidden character for control IDs. Applications must not use this character in their control IDs.

Control renderers, however, should use the dash to derive synthetic IDs from control IdDs, for example, by appending a suffix like "-mysuffix" to the control ID. By this, naming conflicts with the application can be avoided.

Character Description

- Reserved for separators for synthetic IDs

1.5.2.3 Reserved IDs for DOM Nodes and Elements

The following table contains a list of IDs reserved for SAPUI5 core.

ID Description

sap-ui-bootstrap ID of the bootstrap script tag

sap.ui.core-script ID of the bootstrap script tag (deprecated)

sap-ui-* Prefix of the IDs created SAPUI5-internal

*-r Suffix for former UR LightSpeed root areas (similar to UIArea of SAPUI5)

The following table contains a list of IDs currently used in the sap-ui- namespace.

ID Description

sap-ui-library-* Prefix for UI libraries script tags

sap-ui-theme-* Prefix for theme stylesheets link tags

sap-ui-highlightrect ID of the highlight rect for controls in TestSuite

sap-ui-blindlayer-* ID for BlockLayer

sap-ui-static ID of the static area of SAPUI5

sap-ui-TraceWindowRoot ID of the TraceWindowRoot



ID Description

sap-ui-xmldata ID of the XML Data Island

1.5.2.4 Reserved DOM Attributes

The following table contains a list of reserved DOM element attributes names.

Attribute Description

data-sap-ui-* Namespace for custom attributes of SAPUI5

NoteIn general, all custom attibutes should be prefixed with data-.

1.5.2.5 Reserved URL Parameters

The following table contains a list of reserved URL parameter names that should be avoided by applications, meaning that an application can use these parameters, but should not introduce its own parameters with these names.

Attribute Description

sap-* Namespace for URL parameters introduced by SAP AG

sap-ui-* Namespace for URL parameters introduced by SAPUI5

1.5.2.6 Control CSS

To avoid collisions, all CSS classes written to the HTML must start with "sap" if developed inside SAP, and with "sapUi" or "sapM" if developed within the SAPUI5 development teams. Outside the respective groups these prefixes should not be used.

For CSS classes for a specific control, add the control name or an abbreviation of the control name to the above mentioned prefix. For controls outside the commons library you may also add the library name between the prefix and the control name, especially if developed outside the core UI5 development teams.

The HTML root element of controls should contain the CSS class name, and all inner HTML elements requiring a class name should use this class name and add a suffix.

All CSS selectors written by SAPUI5 control developers must refer to at least one CSS class. Pure HTML elements should not be styled to avoid affecting non-owned HTML.

Inline CSS should only be used for control instance specific style, such as the button width.



Styling Contexts

If the visuals of controls are different depending on the context or container in which they are used we recommend to use CSS cascades:

● The area or container writes a marker CSS class to the HTML and documents this CSS class in its JSDoc. The documentation should mention the purpose and contract or meaning of this class, for example, that it modifys the appearance of children in a way that better fits table cells, toolbars, or headers.

● The CSS class may have no CSS styles attached. It is a pure marker. This is because such styles would also need to stay stable and might cause trouble for other containers where these styles are not desired.

● The naming convention for these classes is as follows: Suffix -CTX, for example, sapUiTable-CTX or sapMList-CTX or sapUiBorderless-CTX. This makes them easily discernible from "normal" CSS class names.

● Controls that are used to modify their appearance in such an area shall have CSS where this marker class is used in a cascade and provides the suitable style, for example, .sapUiTable-CTX .myCompanyInputField { border: none; }.

1.5.3 Typed Views and Controllers

For more complex use cases, a more formal and, thus, more complex way to define views and controllers may be necessary.

The following section describes how you create new classes by using prototype inheritance and how to declare their API.

Typed Controllers

To create a controller that is a new type of its own, you need to write a boilerplate code and declare the functions of the new prototype:

/* boilerplate code for typed Controller */jQuery.sap.declare({modName:"sap.hcm.AddressController", type:"controller"}); // declaring a special type of module sap.hcm.AddressController = function () { // the constructor sap.ui.core.mvc.Controller.apply(this, arguments);};jQuery.sap.require("sap.ui.core.mvc.Controller"); // this is currently required, as the Controller is not loaded by defaultsap.hcm.AddressController.prototype = jQuery.sap.newObject(sap.ui.core.mvc.Controller.prototype); // chain the prototypes/* end of boilerplate code for typed Controller */

// to avoid the above we could in the future offer it behind a simple call to:// sap.ui.defineController("sap.hcm.Address");

sap.hcm.AddressController.prototype.onInit = function() { // modify control tree - this is the regular lifecycle hook

};



// implement an event handler in the Controllersap.hcm.AddressController.prototype.doSomething = function() { alert("Hello World");};

1.5.3.1 Support for Unique IDs

Each view and its content usually defines static IDs. You use these IDs to identify and modify the controls within your controller during runtime. If you reuse or nest these views, the IDs are no longer unique. To avoid ambiguity, each view adds its own ID as prefix to all its child controls. This only happens if a static ID is provided. If the ID is created during instantiation of the control, it is unique per default.

If you create further controls during runtime, the controller creates a unique ID by calling the oController.createId("ID") method. These methods add the necessary prefix to the ID.

If you want to modify the control with the ID <ID>, you can call the byId(<ID>) method on your view to get the correct control directly. You do not have to handle all the prefix stuff on your own. The following view defines a button with the static ID abutton (ButtonView):

<core:View viewName="sap.hcm.ButtonView" controllerName="sap.hcm.myController" xmlns="sap.ui.commons" xmlns:core="sap.ui.core" xmlns:html="http://www.w3.org/1999/xhtml"> <Button id="aButton" text="Click me"/><core:View>

The following view defines a view embedding the same view several times (ContainerView):

<core:View viewName="sap.hcm.ContainerView" controllerName="sap.hcm.Address" xmlns="sap.ui.commons" xmlns:core="sap.ui.core" xmlns:html="http://www.w3.org/1999/xhtml"> <core:View id="ButtonView1" viewName="sap.hcm.ButtonView"/> <core:View id="ButtonView2" viewName="sap.hcm.ButtonView"/><core:View>

The view is created as follows:

... var oView = sap.ui.view({type:sap.ui.core.mvc.ViewType.XML, id:"myContainerView",viewName:"sap.hcm.ContainerView"});...

The container view has the following IDs:

Both child views IDs have the prefix myContainerView--:

myContainerView--ButtonView1

myContainerView--ButtonView2

To get one of the child views, use the following code:

... var oButtonView1 = oView.byId("ButtonView1");...



The button view has the following IDs:

ButtonView1--aButton

ButtonView2--aButton

To get the button control, use the following code:

... var oButtonView1 = oView.byId("ButtonView1"); oButtonView1.byId("aButton");...

1.5.3.2 View Cloning

Another important aspect of SAPUI5 views is their cloning behavior. As you might know, SAPUI5 aggregation bindings can use template control to create a series of similar controls based on a collection of data, for example, items in a RowRepeater for each entry in a model array. The data binding uses a ManagedObject.clone operation to create multiple controls out of a single template. For normal controls, the clone operation is based on the control settings that are decribed by SAPUI5 metadata: properties, aggregations, associations, event handlers and so on. The clone operation collects all these settings and creates a new instance out of it.

For views there is a conflict between this basic, generic approach and the way how views usually define their content: via hooks (JSView) or via persisted XML or JSON files. Furthermore, it is allowed and documented best practice to modify the view in the onInit hook of its controller. To avoid conflicts between the generic cloning and the MVC concepts, views implement a slightly modified clone operation: only a subset of the view settings are cloned, the remainder is re-created by calling the hook (JSView) or applying the external view description (XML or JSON file), depending on the view type.

Cloned in a generic way are the following settings:

● any models that have been set (setModel())● registered control event listeners (attachSomeEvent)● registered browser event listeners (attachBrowserEvent)● bindings (bindProperty, bindAggregation)

Not cloned, but recreated are all aggregations, namely the content.

In scenarios where the above clone approach still leads to undesirable behavior, factory functions can be used for the aggregation binding instead.

Related Information

Aggregation Binding [page 110]



1.5.4 File Names and Locations (View and Controller)

Controllers and views are defined and instantiated via a name that equals a SAPUI5 module name within the require/declare concept. This means that by default all files have to be located in a subfolder of the resources folder of the Web application. If this location is not appropriate, deviations can be configured as described in the following example:

The following example assumes that your views and controllers are located on your local machine where the SAPUI5 runtime is loaded from another machine. When you instantiate a view or a controller, SAPUI5 runtime loads them in relation to the resources folder of the machine where SAPUI5 runtime was loaded. To inform SAPUI5 runtime that your views and controllers are located on your local machine, use the following code:

jQuery.sap.registerModulePath(sModuleNamePrefix, sURL);

or

sap.ui.localResources(sModuleNamePrefix);

It is usually sufficient to use sap.ui.localResources which internally registers sModuleNamePrefix to the URL "./" + sTransformedModuleNamePrefix, where all dots are replaced by slashes in the transformed name. All files starting with sModuleNamePrefix will then be loaded in relation to the location of the HTML page that called sap.ui.localResources.

If your files are located at http://<localhost:8080>/<myapp>/, for example, you can use registerModulePath as follows:

jQuery.sap.registerModulePath("myapp", "http://<localhost:8080>/<myapp>/");

or

sap.ui.localResources("myapp");

All views and controllers with a name starting with myapp, for example myapp.MyView, will then be loaded from your local machine.

1.5.5 Troubleshooting

The followig sections give guidance on how to deal with issues that may come up when you develop SAPUI5 applications. It is mainly intended for issues on beginner level.

Browsers may behave differently not only with regard to rendering and event handling, but also with regard to the debugging tools they provide. You can start to develop your application in any browser, however, you should double check on a regular basis whether your development also works with other browsers. To start the development tools, for most browser youcan choose F12 on your keyboard. Or you start them from the browser menu.The following list gives you some information about different common browsers:

● Chrome provides excellent built-in debugging capabilities.● Firefox provides built-in developer tools, but we recommend to install the Firebug extension which offers

more functionality.



● Internet Explorer provides built-in developer tools. However, these tools are lacking functionality or make some steps a little more complicated then neccessary. For example, there is an extra button you need to explicitely hit in its developer tools to start debugging, whereas in other browsers you just have to open the tools. Visual Studio provides a description how to use Visual Studio for debugging applications for Internet Explorer with the title Debug Web Apps with Visual Studio.

● Safari provides a native set of developer tools. For remote debugging on mobile devices, see [Link].

1.5.5.1 Debugging

The first step in analyzing the issue is debugging. Therefore, you need to know how you can debug in your respective browser.

The development tools of the current browsers allow you to set JavaScript debugging breakpoints. In most browsers, setting the breakpoint is sufficient, but in Internet Explorer, script debugging needs to be turned on explicitely and the selection of the correct file can be tricky when it is loaded using Ajax requests because the file name is not listed. Once you have stopped the script execution, you can inspect and modify the variables. You can now execute the code step-by-step.

NoteChrome has some restrictions with regard to modifying variables.

We recommend to read the basic tutorials on debugging in the different browsers that are available online. For information on browser debugging for ABAP developers, see Browser Debugging for ABAP Developers.

Remote Debugging on Mobile Devices

If you want to make sure that your application is also running on a mobile devices, you can use a simulator, or, as they all have restrictions, we recommend that you debug your application remotely on the target device. This is the only way you can make a reliable statement about the performance of your application on, for example, an iPad. The process varies depending on whether you debug on an Android device or on an Apple device. For more information, see the respective documentation for remote debugging for Android or Apple devices on the respective vendor's websites.

Tips and Tricks for Debugging

The following list provides some useful toips and tricks for debugging SAPUI5:

● If you only see minified sources or scrambled code from SAPUI5 sources instead of the real code behind it, activate the Debug Sources option in your browser. You can enable this option as follows:

○ Add the sap-ui-debug=true parameter to your URL.○ Use the Support Tool to toggle Debug Sources on and off.



● List of useful URL parameters:

Parameter Description

sap-ui-debug Set this parameter to true to activate the Debug Sources option.

sap-ui-language Use this parameter to change the language.

sap-ui-theme Use this parameter to switch themes, for example sap-ui-theme=sap_goldreflectionor sap-ui-theme=sap_bluecrystal.

● Debugging with the support toolYou can use the support tool to get additional information about the SAPUI5 application. It provides a tree structure with all existing controls that can be used to edit properties at runtime, view binding information, and set breakpoints on instance level.For more information, see [Link aufs Support Tool]

1.5.5.2 Logging and Tracing

You can use the SAPUI5 logging for debugging purposes, but also use jQuery.sap.log.* or $.sap.log.* functions log in your application code with different security levels:

The following code line issues a log statement with severity level error. The browser highlights this statement in red color and displays it like a JavaScript error:

$.sap.log.error("This should never have happened!");

This code line issues a log statement with severity level information. The browser does not display this statement if your log console is set to filter for errors only:

$.sap.log.info("FYI: something has happened");

Locating the Logger Output

The developer tools of Internet Explorer, Chrome, and Safari, as well as Firefoxe's Firebug extension offer a console API that you can use for logging. The log output is additionally directed to the console.



Using the Network Trace

If content misses in your application, check the network trace of your page for occurrences of errors like 404 (Page/file not found) or 500 (Internal server errors). This also tells you if an OData request has failed or if resources are not being loaded because of a wrong URL.

To start a network trace, for example, in Chrome, open the developer tools and switch to the Network tab. In the button bar at the bottom of this tab you can start and stop tracing. To see the network requests that are sent from your application, you have to start the trace and then reload the page. Once the loading has finished, you see a list of all requests that were triggered, along with the request status (and highlighting to show errors). Click on a request to view you further details, for example headers that were sent or the response that was retrieved.

1.5.5.3 Troubleshooting: Common Issues

The following sections provide information on common issues.

An Empty Page Comes Up

An empty page is most likely caused by a JavaScript error. JavaScript errors stop all subsequent execution.

To solve the issue, check the browser's JavaScript console or the Firefox error console. If they do not indicate that an error has occurred, check if you added the UI controls to an existing element in the page by using placeAt(…). If this is not the cause, check in the browser's DOM inspector whether this "existing element" actually contains child HTML which resembles the controls you have added. Check if the HTML elements are set to be visible and check the dimensions. The height (or width) may have collapsed to zero, thus making the element invisible. This happens, for example, if an HTML element with no height set has a child element with a height set to 100%, as this height refers to the height of the parent element with an undefined height.

Content or Control is not Visible

If content or a control is not visible, check in the DOM inspector of your browser whether the respective HTML exists in the document, or not. You can either search for the control ID or drill down the control hierarchy. It is



often the case that the height has collapsed to zero, thus making the element invisible. A possible cause is if you have set no height for an HTML element, but set the height for a child element to 100%. The 100% refer to the height of the parent element with an undefined height, meaning that the child element wants to be as tall as its parent. You can also check whether the control and its parents are set to visible. Or, if you use data binding, check if the elements are properly bound. You can also use the support tool for this check.

Content or Control is set to 100% Height, but Setting Does not Work

Check the height settings of the parent elements. In CSS, a percentage height only works when the parent has a defined height. This issue is often caused by parent elemnt with no height setting or again a percentage height and one ancestor with no defined height. In CSS, this results in a height that is collapsed to the minimum height accomodating all content. Some typical controls, however, adapt their height to the content are the sap.ui.core.View (all types) and the sap.m.Page controls. By setting the View height to any fixed height or setting the View and all ancestors to 100% height, you can define its height and 100%-height children will work fine. And the Page control can be set to enableScrolling: false: when scrolling is allowed, the scroll container in the Page control grows with the content, but when you want to set the content to 100% height scrolling does not make sense because by definition there is no scrolling when the content is as tall as the available space.

Proportions of a Rendered Control Look Odd

Check if the doctype is set correctly in your page. Some controls are not rendered correctly if the doctype is missing or is not correct. Table headers, for example, become exceptionally high.

Style of an Application or a Control Looks Odd

Check if you have used custom styles in your application. If yes, they probably collide with styling in the theming libraries. One approach is to use the browser's debugging tools to inspect the element which has the wrong styling. You can usually see on the HTML tab which styles are applied to a DOM element. If you have styles in the list that your application adds, disable these styles in the debugger to see whether this solves the problem. Note that SAPUI5-specific CSS classes and IDs start with a sapUi prefix, for example, sapUiButton.

If this does not solve the issue, check for inline styles that are be applied to the element in the HTML code. You can also try to isolate the control from the application to see if there is an issue with the control instead of a collision of styles.

If none of the above solves the problem and the issue does not seem to be application specific, open a CSS message.



Console Shows an Error Indicating That Something is Wrong With SAP-UI-CORE.JS, Line 2

Although an issue in SAP-UI-CORE.JS is not impossible, the error often originates elsewhere. To find the actual issue, activate the SAPUI5 debugging sources. This enables you to see in more detail where the message is thrown and it gives you the opportunity to set a breakpoint at the corresponding line. From there, you can dig deeper into the problem and also have a look at the call stack to see where it has started.

1.5.5.4 Browser Debugging for ABAP Developers

When you debug code in SAPUI5, keep in mind that you can not debug SAPUI5 in your IDE. If you use Eclipse, for example, a breakpoint set in Eclipse does not stop your script when it is executed in your browser, unless you use the debugger; statement explicitely in your code. The browser does not know about your IDE and does not communicate directly with it. Thus, to debug in SAPUI5, use your browser's debugging tool.

ABAP Debugger vs. Browser Debugger

This section explains how you use the debugging tool of a Chrome browser. Keep in mind that you have to test your application on all browsers that are officially supported by SAP, because the implementation differs depending on the browser used, seeChoose your Browser. To start the debugger, use the browser menu or choose F12 (valid for most browsers).

The following explanations assume that your application is up and running on your web server, either a local Tomcat, or a remote server.

In a first step, locate the lines of code you would like to inspect and set breakpoints. The following figure shows an application that is opened in the Chrome debugger. The default tab Elements is opened, and a small bell icon with a number located at the right border of the footer indicates the number of messages from the console.



On the Elements tab, the HTML elements of the DOM are displayed in a tree structure. To see the JavaScript code within the application and to set a breakpoint there, open the Sources tab. From there, you can open any source files that is included. When you open the tools the first time, you ususally have to click the arrow icon on the left hand side of the Sources tab (as indicated in the following figure) to open the sources tree.



To see the actual content of the HTML page and to set a breakpoint, open the HTML page from the sources tree. This is similar to the ABAP debugger when you execute and debug an application from the workbench. The following figures show the ABAP workbench debugger and the Chrome debugger.

The following figure shows the ABAP workbench debugger. The bubbles indicate the opened application and its location (1), the call stack (2), and the tab where you enter the variables you want to watch (3).

The next figure shows the Chrome debugger. Here, the bubbles indicate the script you are looking at (1), the watch expressions where you can add the variables you want to watch (3), the call stack that indicates if the code execution stops on a breakpoint (2), and the breakpoint (4). The call stack is only visible when the code execution is on hold.



NoteJavaScript does not support a forward navigation, meaning that you can not jump to a method by double clicking. Instead, you either have to jump to the method during execution, or you open the file containing the method.

If you are not sure in which file exactly a piece of code is located, Firefox offers you an option to search through several files included in your page. Chrome, however, does not support this option.

Setting Breakpoints

The browser debugger supports several options for setting breakpoints. You can, for example, click once on the line number where you would like to break. To remove the breakpoint, click the respective line again. To temporarily disable or edit the breakpoint, right click on an existing breakpoint. To set a conditional breakpoint, right click on a line without breakpoint. You can also set breakpoints on a certain event or event listeners, see the option in the lower right screen area of the figure above. For more information, see the tutorials for your respective browser that are available in the internet.

NoteIn most cases after setting a breakpoint, you have to reload the page to execute the code again and to make it stop at the respective line. If you use Internet Explorer, choose Start Debugging in the developer tools to activate your breakpoint.

Adding Variables to Watch

To add a variable to the list of watched variables, open the context menu for the variable in the code line and choose Add to watch. Another option is to choose the + button at the top of the watch list to add a new line, in which you can then enter the name of the variable you want to watch.



Modifying Variables

If you want to modify a variable to find out if the code works correctly with a different value, open the console, for example by choosing ESC in the debugging tool and enter the new value manually directly in the JavaScript code. To confirm the change, choose ENTER in Chrome and Execute in Firefox.

Stepping Through Executed Code

In ABAP, a yellow arrow indicates the line of code that is currently being executed. In Chrome, the arrow is red and the code line is highlighted. The following table gives an overview of the function keys for the ABAP workbench and Java Script:

Function ABAP JavaScript

Step-by-step execution, also stepping into functions and loops

F5 F11

Step-by-step execution, stepping over functions

F6 F10

Skipping the rest of the current function and stepping out to the last cursor position

F7 SHIFT+F11

Resume execution F8 F8

(Internet Explorer: F5)

1.5.5.5 SAPUI5 Diagnostics

SAPUI5 provides a support tool that you can run within an existing SAPUI5 application. To call the support tool, use the following shortcut: CTRL+SHIFT+ALT+S. The following sections describe the functions SAPUI5 provides in the support tool.

Activating the Debug Sources

To use the debugging function, it is important to use the debg sources. For this, set the Debug Sources function to ON.



Control Tree

The control tree shows all controls that are contained in the application in a tree view. You can select controls either directly in the application by choosing CRTL+SHIFT+ALT and clicking on the control, or by selecting the control in the control tree.

The followig functions are available in the dialog:

● On the Properties tab you can change the defined properties of the selected control. In the example below, you can change the value, the text direction, and enable or disenable the control.

● The Binding Infos tab shows all existing bindings for the selected control together with additional information. To update the binding, choose Refresh.



You can also see the binding context for the selected control. To navigate to the respective controls, use the hyperlinks.

● On the Properties tab, you can add or remove breakpoints. Use the respective checkbox to add or remove a breakpoint for the get/set method of a control property.



● On the Breakpoints tab, you can add or remove breakpoints for methods. You can either select the method from the dropdown box, or use auto completion. To set the breakpoint, select the method and choose Add breakpoint. To remove a breakpoint, select the red x.

Debugging a Method

To debug a method, open and activate you browser's debugging tool. If you execute a method with an active breakpoint, the script stops at the debugger statement. To open the method, use the step-over/into function of your debugger.

Debugging View

The Debugging view allows you to set breakpoints for methods on class level. Select the class from the dropdown box or enter the name of the class. Choos Add to set the breakpoint. For each class, the system shows the number of active breakpoints and all methods.



1.5.6 Security Concepts

The following sections provide security-related information for specific topics, such as Cross-site srcipting.

For general information on Security concepts for SAPUI5, see the Security Guide for SAPUI5.

1.5.6.1 Cross-Site Scripting

Cross-site scripting (XSS) is a widely known vulnerability most web sites have. This page does not provide general information about cross-site scripting but focuses on what you as an application developer using SAPUI5 can do to avoid these security issues.

To give a short info on XSS: It is about injecting script code into a web page, which is then executed in the context of the page and therefore not only can access any information which currently displayed on the screen but can either access session information contained in cookies, or send new requests to the server within the current session, or even try to exploit browser vulnerabilities to get full access to the machine the browser is running on.

Cross-site Scripting in SAPUI5-based Web Applications

AJAX frameworks in general are an interesting target for XSS exploits, as not only the HTML which is initially sent to the browser may contain vulnerabilities, but also the code which is used to visualize content on the client side



may have bugs which can be exploited to get the JavaScript coding executed on the client side. In addition to that, once a script has injected an AJAX application, it will be alive for a long time, as usually navigation will not reload the whole page which would also clean up any running JavaScript code, but stays within the same HTML document and uses a delta update mechanism to show new content.

It is important to understand that SAPUI5 is not involved in creating the HTML page which is sent to the client, so there is no way SAPUI5 can prevent XSS vulnerabilities which are contained in the HTML page itself. The application which is using the SAPUI5 rendering has to take care, according to the documentation of their server-side rendering framework, to properly escape user data, in a way that no JavaScript can be injected.

The SAPUI5 framework will take care of proper escaping for all content which is created and displayed on the screen using the controls provided by SAPUI5. There is no need for the application to HTML-escape user data, but the control API expects all data to be unescaped, so that it can be escaped as needed for the context it will be visualized.

1.5.6.2 URL White List Filtering

The SAPUI5 framework provides a client-side API to manage a whitelist for URLs. This whitelist can be used to validate arbitrary URLs if they are permitted or not. Internally controls which accept arbitrary HTML content like the sap.ui.richttexteditor.RichTextEditor or the sap.ui.core.HTML use the URL white list to check (sanitize) the URLs of their content and value to not infringe against the allowed URLs. The option to sanitize the value can be enabled or disabled in the respective control properly via property: RichTextEditor.sanitizeValue or HTML.sanitizeContent. For the HTML control it is disabled by default whereas for the RichTextEditor the sanitize option is enabled.

Maintaining the URL White List

The white list can be maintained with the following API:

● jQuery.sap.addUrlWhitelist● jQuery.sap.clearUrlWhitelist● jQuery.sap.getUrlWhitelist● jQuery.sap.removeUrlWhitelist

Here is an example how valid URLs can be added to the whitelist:

#!js

// jQuery.sap.addUrlWhitelist(/* protocol */ undefined, /* host */ undefined, /* port */ undefined, /* path */ undefined);

jQuery.sap.addUrlWhitelist(undefined, "www.sap.com");

jQuery.sap.addUrlWhitelist("https", "sdn.sap.com");

jQuery.sap.addUrlWhitelist(undefined, "sap.de", "1080");



Validating a URL

A URL can be validated by using the following API: jQuerysapvalidateUrl.

Here is an example how a given URL is validated against the before maintained whitelist:

#!js

jQuery.sap.validateUrl("http://www.sap.com"); // => true

jQuery.sap.validateUrl("http://sdn.sap.com"); // => false (wrong protocol)

jQuery.sap.validateUrl("https://sdn.sap.com"); // => true

jQuery.sap.validateUrl("ftp://sap.de:1080/anyftpfolder"); // => true

If no whitelist is maintained the URL validity check also basically checks the URL for being defined in a valid format.

1.5.6.3 HTML5 Sanitizer

The HTML5 Sanitizer can be used to cleanup HTML5 code snippets by removing potentially executable javascript. For this approach the HTML4 Sanitizer by Google is reused and adapted for the usage of HTML5 coding. The Google Santizer also supports CSS3 coding. In addition the final Sanitizer makes use of the URL WhiteList which checks embedded URLs for correct formatting or against a given whitelist. For adapting the Sanitizer to support HTML5 the HTML attributes and elements were reorganized according to the actual HTML5 specification from the W3C. All types and flags were reviewed again as accurately as possible with HTML4 only elements removed, you can still see them as comments. All rules which are new or changed from the old HTML4 file are also marked "new" within the comment. The comments also state which attributes and elements are assigned to respective types and flags. All rules which were not 100% clear were analyzed in a way of similarity, so for example "audio" and "video" content behaves like images etc. URIEFFECTS state if a URL is loaded inplace within a tag where the actual document is in control of what type of content is loaded like "image" or if a new document is loaded like with "a href". LOADERTYPES state if content is loaded as sandboxed which means it is loaded within a specific surrounding player like with video content for example or if it is loaded freely without restrictions. Internally controls which accept arbitrary HTML content like the sap.ui.richttexteditor.RichTextEditor or the sap.ui.core.HTML use the HTML5 Sanitizer to sanitize the HTML code of their content and value to not infiltrate any dangerous coding. The option to sanitize the value can be enabled or disabled in the respective control properly via property: RichTextEditor.sanitizeValue or HTML.sanitizeContent. For the HTML control, it is disabled by default whereas for the RichTextEditor the sanitize option is enabled.



2 Important Disclaimers on Legal AspectsThis document is for informational purposes only. Its content is subject to change without notice, and SAP does not warrant that it is error-free. SAP MAKES NO WARRANTIES, EXPRESS OR IMPLIED, OR OF MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.

Coding Samples

Any software coding and/or code lines / strings ("Code") included in this documentation are only examples and are not intended to be used in a productive system environment. The Code is only intended to better explain and visualize the syntax and phrasing rules of certain coding. SAP does not warrant the correctness and completeness of the Code given herein, and SAP shall not be liable for errors or damages caused by the usage of the Code, unless damages were caused by SAP intentionally or by SAP's gross negligence.

Accessibility

The information contained in the SAP documentation represents SAP's current view of accessibility criteria as of the date of publication; it is in no way intended to be a binding guideline on how to ensure accessibility of software products. SAP specifically disclaims any liability with respect to this document and no contractual obligations or commitments are formed either directly or indirectly by this document.

Gender-Neutral Language

As far as possible, SAP documentation is gender neutral. Depending on the context, the reader is addressed directly with "you", or a gender-neutral noun (such as "sales person" or "working days") is used. If when referring to members of both sexes, however, the third-person singular cannot be avoided or a gender-neutral noun does not exist, SAP reserves the right to use the masculine form of the noun and pronoun. This is to ensure that the documentation remains comprehensible.

Internet Hyperlinks

The SAP documentation may contain hyperlinks to the Internet. These hyperlinks are intended to serve as a hint about where to find related information. SAP does not warrant the availability and correctness of this related information or the ability of this information to serve a particular purpose. SAP shall not be liable for any damages caused by the use of related information unless damages have been caused by SAP's gross negligence or willful misconduct. Regarding link classification, see: http://help.sap.com/disclaimer


SAPUI5 Reference for SAP HANAImportant Disclaimers on Legal Aspects

http://help.sap.com/disclaimer/

SAPUI5 Reference for SAP HANAImportant Disclaimers on Legal Aspects


www.sap.com/contactsap

© 2014 SAP AG or an SAP affiliate company. All rights reserved.No part of this publication may be reproduced or transmitted in any form or for any purpose without the express permission of SAP AG. The information contained herein may be changed without prior notice.Some software products marketed by SAP AG and its distributors contain proprietary software components of other software vendors. National product specifications may vary.These materials are provided by SAP AG and its affiliated companies ("SAP Group") for informational purposes only, without representation or warranty of any kind, and SAP Group shall not be liable for errors or omissions with respect to the materials. The only warranties for SAP Group products and services are those that are set forth in the express warranty statements accompanying such products and services, if any. Nothing herein should be construed as constituting an additional warranty.SAP and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP AG in Germany and other countries.Please see http://www.sap.com/corporate-en/legal/copyright/index.epx for additional trademark information and notices.

http://www.sap.com/contactsap

http://www.sap.com/corporate-en/legal/copyright/index.epx

http://www.sap.com/corporate-en/legal/copyright/index.epx

sap ui5 reference for sap hana en

Documents

sapui5 tools

html5 sapui5

configuration of sapui5

sapui5 runtime

sapui5 components1391

sapui5 application211

sapui5 application tools

adapting sapui5 applications