SAP Fiori Launchpad for Developers - Architecture Overview

1SAP Fiori Launchpad for DevelopersArchitecture Overview

Applies to:User Interface Add-On 1.0 SPS 06 and higher

SummaryOne of the key features introduced in user interface add-on 1.0 SPS 06 is the SAP Fiori launchpad. Incontrast to the launch page used in SPS 04, the launchpad acts as runtime shell environment for the SAPFiori apps in which the personalized home page is one feature among many other services.In this article, we will describe the major technical building blocks of the SAP Fiori launchpad and explainhow to embed SAPUI5 apps into the launchpad.

Authors: Steffen Hster, Olivier Keimel

Company: SAP SE

Created on: 04 August 2014

Author BioSteffen Hster, SAP SE

Steffen is working as a software architect in the UI Technology department, with a focus on UI integrationtopics.

Olivier Keimel, SAP SE

Olivier is working as a knowledge architect in the P&I Technology Engineering Services department, with afocus on UI integration topics.

.

2Table of Contents

Building blocks .............................................................................................................................................. 3

Embedding Apps into the SAP Fiori Launchpad ............................................................................................ 5Embedding SAPUI5 Applications into the SAP Fiori Launchpad ................................................................. 5File Structure ............................................................................................................................................. 5Component Configuration .......................................................................................................................... 5

Configuration Properties used by the SAP Fiori Launchpad .................................................................................... 6

Path resolution .......................................................................................................................................... 6Example ............................................................................................................................................................... 7

Best Practices for Launchpad Apps ............................................................................................................... 8

How to Reference Resources from an SAPUI5 Component ......................................................................... 10Referencing Resources Inside your own Component ............................................................................... 10

Referencing JavaScript Modules ......................................................................................................................... 10Including Style Sheets ......................................................................................................................................... 10Referencing other files ........................................................................................................................................ 10

Related Content .......................................................................................................................................... 11

Copyright .................................................................................................................................................... 12

3Building blocksThe graphic on the next page gives an overview of the building blocks described here.

The SAP Fiori launchpad is based on the so-called unified shell architecture. The guiding principle of theunified shell is to have a single, platform-independent, client-side runtime environment which can be hostedon different server platforms (for example SAP NetWeaver AS ABAP, SAP HANA XS, SAP HANA CloudPlatform). This means that the shell offers unified services with platform-independent interfaces (APIs) tothe hosted apps and shell components. The implementations of these services can utilize different serviceadapters for the respective platform if they need platform-specific behavior.

The visualization of the shell is independent of the shell services. This is achieved by using a shell rendererthat can be replaced by a different implementation.

The apps are embedded in a so-called application container. As this is an independent re-use component,the embedding aspect is decoupled from the renderer. The application container can host SAPUI5components, Web Dynpro ABAP applications and SAP GUI for HTML transactions.

The shell services and renderers are managed by the central shell container. It utilizes a runtimeconfiguration which defines the concrete implementations for services, adapters, and shell renderer, as wellas global settings like theme, language, system and user data.

The runtime configuration is fed by the following settings:

x Static configuration settings in the hosting HTML pagex Dynamic configuration data read from the front-end server during startupx Dynamic settings passed as query parameters in the URL

Finally, all described JavaScript components are embedded into a single HTML page. The SAP Fiorilaunchpad implementation of the SAP NetWeaver ABAP front-end server contains a standard page calledFioriLaunchpad.html. You can create custom start pages which utilize the shell with different staticconfigurations.

4The described building blocks are illustrated in the following diagram:

5Embedding Apps into the SAP Fiori LaunchpadWhen embedding applications into the SAP Fiori launchpad, we differentiate the following cases:

x Applications based on SAP GUI for HTML or Web Dynpro ABAP can be embedded using aniFrame. This can be done using configuration only. The configuration steps are the same asdescribed in the blog Extending a Fiori App Simple Use case Part 3.

x For applications based on SAPUI5, a tighter integration is possible. As these have beenimplemented using the same UI technology, these can be embedded directly into the launchpadusing DOM injection. This approach also allows smooth, animated UI transitions and the reuse ofshared components at runtime. Therefore, SAP Fiori applications have to be implemented as self-contained SAPUI5 components as described below.

Embedding SAPUI5 Applications into the SAP Fiori LaunchpadThe application container (described above) is configured with the following parameters:

x The URL (root path) of the applicationThis is the path where the component controller for the SAPUI5 app the Component.js file (seebelow) is located.

x The name of the SAPUI5 componentThe application container registers the component namespace as module path for the application URL. Formore information, see Modularization and Dependency Managemenent in the SAPUI5 documentation.

As this is a global setting, it is essential to use fully qualified names for the applications modules (forexample, component and views). For a comprehensive example, see Application Best Practices.

File StructureThe SAPUI5 component is defined in a file named Component.js, which should be located in the rootfolder of your application. In an Eclipse project, it is typically located under src/main/webapp orWebContent.For more detailed information, see SAPUI5 Components in the SAPUI5 documentation.

Component ConfigurationThe definition of an SAPUI5 component includes the component metadata. The component metadataincludes a config object containing additional information. Define the launchpad-specific configuration in thisconfig object. This configuration is used in several scenarios as described below.

6Configuration Properties used by the SAP Fiori LaunchpadThe SAP Fiori launchpad evaluates the following properties of the component configuration:

Properties Description

resourceBundle Path to the resource bundle that holds the translated app title. Example:i18n/i18n.properties

titleResource Key of the app title text in the resource bundle. The title is typicallydisplayed in the browser tab

favIcon Path to the "favicon" (*.ico) file for the app, which is typically displayed inthe address bar or next to the window title or tab title.

"homeScreenIconPhone","homeScreenIconPhone@2","homeScreenIconTablet","homeScreenIconTablet@2"

Paths to icons with different resolutions that are used when users add the(launchpad page containing the) app to their mobile devices homescreens. The properties with an @2 suffix allow you to refer to specialicons for high-resolution devices.

Use the following icon sizes:

x homeScreenIconPhone: 57 x 57 pixelsx homeScreenIconPhone@2: 114 x 114 pixelsx homeScreenIconTablet: 72 x 72 pixelsx homeScreenIconTablet@2: 144 x 144 pixels

Path resolutionFor all properties that reference files, there are several ways to define them:

x Absolute reference, typically starting with "/", so it's an absolute path on the same host.x Relative reference, pointing to a location outside of the app, starting with "../".x Relative reference, pointing to a location within the app, starting with any file or folder name below

the root folder of the app.

The launchpad ensures that relative references are relative to the location of the Component.js file (notrelative to the location of the HTML file displayed by the web browser). This is consistent with the behaviorfor other references in component metadata, for example the includes property.

7ExampleThe example below illustrates how the component.js file in an SAPUI5 app may look:

sap.ui.core.UIComponent.extend("mycompany.abc.Component", {metadata : {

name: "Sample Component",library : " mycompany.abc",includes : [

"css/style.css"],dependencies : {},config : {

"resourceBundle" : "i18n/i18n.properties","titleResource" : "shellTitle",// The following properties reference dedicated image files. Note// that relative links are always relative to the location of the// Component.js of the app, NOT to the location of the HTML file that// is displayed in the web browser (typically: FioriLaunchpad.html)."favIcon" : "img/favicon.ico","homeScreenIconPhone" : "img/57_iPhone_Desktop_Launch.png","homeScreenIconPhone@2" : "img/114_iPhone-Retina_Web_Clip.png ","homeScreenIconTablet" : "img/72_iPad_Desktop_Launch.png","homeScreenIconTablet@2" : "img/144_iPad_Retina_Web_Clip.png",

} }, (...)});

8Best Practices for Launchpad AppsThe following best practices will help you develop your SAPUI5 apps so that they run smoothly in the SAPFiori launchpad without any side effects that might be tricky to analyze:

x Build your apps as self-contained SAPUI5 components."Apps" in the SAP Fiori launchpad are effectively SAPUI5 components. The launchpad instantiatesyour application by loading the Component.js file.For more information, see SAPUI5 Components in the SAPUI5 Developer Guide.

Use an app-specific index.html file for standalone apps only. The application.js andindex.html files are not loaded by the unified shell.

x Declare configuration information, like the location of icons, and library dependencies in thecomponent.js configuration file.

x Do not use any global variables.If you cannot avoid using global variables, use qualified names to ensure uniqueness.

x If you need an event bus, use the event bus of the component(sap.ui.core.Component.getEventBus).This avoids conflicting event names and makes sure that your listeners are automatically removedwhen the component is unloaded. For more information, see the JSDocs.

Do not use the global event bus (sap.ui.getCore().getEventBus()).x Register models on the root component or on single views of your apps.

Example: this.getView().setModel("MyModel",aModel);Do not use sap.ui.getCore() to register models.For more information, see Model View Controller in the SAPUI5 Developer Guide.

x Let SAPUI5 generate IDs for global elements.Do not set explicit IDs for global elements in your code, as this may prevent you from running an appseveral times in the launchpad.

Do not rely on sap.ui.getCore().byId() for global location of elements. Always use localnames getView().byId() and let SAPUI5 generate the IDs of views and components.

x Use only the SAPUI5 APIs to manipulate the location hash.Do not read or write directly to window.location.hash or window.location.The SAP Fiori launchpad uses URL hashes for its own navigation. Direct manipulation of the locationhash would interfere with the lauchpad navigation.

For cross-app navigation, use the Cross-Application Navigation service. For more information on thisservice, see the JSDocs.

For inner-app navigation, use the SAPUI5 routing API. For more information, see Routing in UIComponents in the SAPUI5 documentation.

x Ensure that all controls created by your component are destroyed when the component is destroyed.All controls which are in the control tree (defined in an XML view in a static way or explicitly added toa parent control in a JavaScript view) of the component are destroyed automatically. But controlswhich are not part of a parent, for example dialog instances, are not automatically destroyed. Forexample, you can ensure proper destruction by adding such controls to the corresponding view withthe method addDependent of sap.ui.core.Element. For more information, see Using DialogsDefined as Fragments in the SAPUI5 documentation.

9x Avoid using sap.ui.localResources inside your Component.js file.sap.ui.localResources registers a path relative to the main page (FioriLaunchpad.html).Components must not make implicit assumptions on this location.

x Avoid using jQuery.sap.registerModulePath inside your Component.js, as it creates adependency to a specific platform.

10

How to Reference Resources from an SAPUI5ComponentReferencing Resources Inside your own Component

Referencing JavaScript ModulesTo reference JavaScript modules of your own component, always use the fully qualified module name.The unified shell registers a module path for the root of the component.

For example, on an AS ABAP front-end server, if the component name is"mycompany.samples.mysample", and it is deployed as BSP application"mycompany/my_sample_bsp", the module path "mycompany.samples.mysample" is mapped to thepath "/sap/bc/ui5_ui5/mycompany/my_sample_bsp".The unified shell then locates your elements as follows (mapped module names and paths in bold blue):

x Your component "mycompany.samples.mysample.Component" is retrieved from"/sap/bc/ui5_ui5/mycompany/my_sample_bsp/Component.js".

x Your view "sap.samples.mysample.view.S2" is retrieved from"/sap/bc/ui5_ui5/my_sample_bsp/view/S2.view.xml".

You can then reference all modules contained in the component with the fully qualified module name usingthe require mechanism. For more information, see Modularization and Dependency Management.For example, you can load a JavaScript file located in/sap/bc/ui5_ui5/my_sample_bsp/morejs/MyJSFile.js usingjQuery.sap.require("mycompany.samples.mysample.morejs.MyJsFile");

Including Style SheetsTo include custom style sheets, use the includes property of the component metadata as shown in theexample in Component Metadata in the SAPUI5 documentation.

Referencing other filesYou might need to build a URI for a resource, for example when creating a resource model. You can do thisby calculating the absolute path based on the relative module path of your own component.Example:

var effectiveUrl = jQuery.sap.getModulePath("mycompany.samples.mysample") + "/" +"i18n/i18n.properties"var resourceBundle = jQuery.sap.resources({

url : effectiveUrl});

11

Related ContentYou must include at least 3 references to SCN documents.

Extending a Fiori App Simple Use case Part 3

SAPUI5 Components

Application Best Practices

12

Copyright 2014 SAP SE SE or an SAP SE affiliate company. All rights reserved.No part of this publication may be reproduced or transmitted in anyform or for any purpose without the express permission of SAP SE.The information contained herein may be changed without prior notice.Some software products marketed by SAP SE and its distributors contain proprietary software componentsof other software vendors. National product specifications may vary.These materials are provided by SAP SE and its affiliated companies (SAP SE Group) for informationalpurposes only, without representation or warranty of any kind, and SAP SE Group shall not be liable forerrors or omissions with respect to the materials. The only warranties for SAP SE Group products andservices are those that are set forth in the express warranty statements accompanying such products andservices, if any. Nothing herein should be construed as constituting an additional warranty.SAP SE and other SAP SE products and services mentioned herein as well as their respective logos aretrademarks or registered trademarks of SAP SE in Germany and other countries.Please seehttp://www.sap.com/corporate-en/legal/copyright/index.epx#trademark

for additional trademark information and notices.

Building blocksEmbedding Apps into the SAP Fiori LaunchpadEmbedding SAPUI5 Applications into the SAP Fiori LaunchpadFile StructureComponent ConfigurationConfiguration Properties used by the SAP Fiori Launchpad

Path resolutionExample

Best Practices for Launchpad AppsHow to Reference Resources from an SAPUI5 ComponentReferencing Resources Inside your own ComponentReferencing JavaScript ModulesIncluding Style SheetsReferencing other files

Related ContentCopyright

Documents

SAP Fiori Launchpad for Developers - Architecture Overview