SAP Fiori L aun ch pad for Develop Develop ers Architec Archi tecture ture Ov Overvi erview ew Ap p l i es t o : User Interface Add-On 1.0 SPS 06 and higher
Summary One of the key features introduced in user interface add-on 1.0 SPS 06 is the SAP Fiori launchpad. In contrast to the launch page used in SPS 04, the launchpad acts as runtime shell environment for the SAP Fiori 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 explain how to embed SAPUI5 apps into the launchpad.
Aut Au t ho r s:
Steffen Hüster, Olivier Keimel
Company:
SAP SE
Created Created on :
04 August 2014
Au t h o r B i o Steffen Hüst er, SAP SE
Steffen is working as a software architect in the UI Technology department, with a focus on UI integration topics. Olivier Keimel, SAP SE
Olivier is working as a knowledge architect in the P&I Technology Engineering Services department, with a focus on UI integration topics. .
1
Table of Contents Building blocks.......................... ........................... ........................... .......................... ........................... ......... 3 Embedding Apps into the SAP Fiori Launchpad ........................................ ........................... ......................... 5 Embedding SAPUI5 Applications into the SAP Fiori Launchpad ....................... ........................... ............... 5 File Structure......................... ........................... ........................... .......................... ........................... ......... 5 Component Configuration ........................ ........................... ........................... .......................... .................. 5 Configuration Properties used by the SAP Fiori Launchpad ............ .............. ............. ............. ............. ............. ...... 6
Path resolution ....................... .......................... ........................... ........................... .......................... ......... 6 Example ............................................................................................................................................................... 7
Best Practices for Launchpad Apps ....................... ........................... ........................... .......................... ........ 8 How to Reference Resources from an SAPUI5 Component........................ ........................... ...................... 10 Referencing Resources Inside your own Component ......................... .......................... ........................... . 10 Referencing JavaScript Modules ......................................................................................................................... 10 Including Style Sheets ......................................................................................................................................... 10 Referencing other files ........................................................................................................................................ 10
Related Content ........................ .......................... ........................... ........................... .......................... ........ 11 Copyright .................................................................................................................................................... 12
2
Building blocks The 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 the unified shell is to have a single, platform-independent, client-side runtime environment which can be hosted on different server platforms (for example SAP NetWeaver AS ABAP, SAP HANA XS, SAP HANA Cloud Platform). This means that the shell offers unified services with platform-independent interfaces (APIs) to the hosted apps and shell components. The implementations of these services can utilize different service adapters 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 renderer that 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 SAPUI5 components, 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 runtime configuration which defines the concrete implementations for services, adapters, and shell renderer, as well as global settings like theme, language, system and user data. The runtime configuration is fed by the following settings:
Static configuration settings in the hosting HTML page
Dynamic configuration data read from the front-end server during startup
Dynamic settings passed as query parameters in the URL
Finally, all described JavaScript components are embedded into a single HTML page. The SAP Fiori launchpad implementation of the SAP NetWeaver ABAP front-end server contains a standard page called Fi or i Launchpad. ht ml . You can create custom start pages which utilize the shell with different static configurations.
3
The described building blocks are illustrated in the following diagram:
4
Embedding Apps into the SAP Fiori Launchpad When embedding applications into the SAP Fiori launchpad, we differentiate the following cases:
Applications based on SAP GUI for HTML or Web Dynpro ABAP can be embedded using an iFrame. This can be done using configuration only. The configuration steps are the same as described in the blog Extending a Fiori App – Simple Use case – Part 3 . For applications based on SAPUI5 , a tighter integration is possible. As these have been implemented using the same UI technology, these can be embedded directly into the launchpad using DOM injection. This approach also allows smooth, animated UI transitions and the reuse of shared components at runtime. Therefore, SAP Fiori applications have to be implemented as selfcont ained SAPUI5 comp onents as described below.
Embedding SAPUI5 Application s in to th e SAP Fiori Launch pad The application container (described above) is configured with the following parameters:
The URL (root path) of the application This is the path where the component controller for the SAPUI5 app – the Component . j s file (see below) – is located. The name of the SAPUI5 component
The application container registers the component namespace as module path for the application URL. For more information, see Modularization and Dependency Managemenent in the SAPUI5 documentation. As this is a global setting, it is essential to use fully q ualified names for the applications modules (for example, component and views). For a comprehensive example, see Application Best Practices.
File Structu re The SAPUI5 component is defined in a file named Component.js, which should be located in the root folder of your application . In an Eclipse project, it is typically located under sr c/ mai n/ webapp or WebCont ent . For more detailed information, see SAPUI5 Components in the SAPUI5 documentation.
Component Configuration The definition of an SAPUI5 component includes the component metadata. The component metadata includes a config object containing additional information. Define the launchpad-specific configuration in this config object. This configuration is used in several scenarios as described below.
5
Configuration Properties used by the SAP Fiori Launchpad The 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 typically displayed in the browser tab
favIcon
Path to the "favicon" (*.ico) file for the app, which is typically displayed in the 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’ home screens. The properties with an @2 suffix allow you to refer to special icons for high-resolution devices. Use the following icon sizes:
homeScreenIconPhone: 57 x 57 pixels
homeScreenIconPhone@2: 114 x 114 pixels
homeScreenIconTablet: 72 x 72 pixels
homeScreenIconTablet@2: 144 x 144 pixels
Path resoluti on For all properties that reference files, there are several ways to define them:
Absolute reference, typically starting with " / ", so it's an absolute path on the same host.
Relative reference, pointing to a location outside of the app, starting with " . . / ".
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 . j s file (not relative to the location of the HTML file displayed by the web browser). This is consistent with the behavior for other references in component metadata, for example the i ncl udes property.
6
Example The example below illustrates how the component . j s file in an SAPUI5 app may look: sap. ui . cor e. UI Component . ext end( " mycompany. abc. Component " , { met adat a : { name: " Sampl e Component " , l i br ar y : " mycompany. abc", i ncl udes : [ " c ss / s t y l e. c ss " ], dependenci es : { }, c onf i g : { "r esour ceBundl e" : "i 18n/ i 18n. pr oper t i es", " t i t l eRes our c e" : " s hel l Ti t l e" , / / The f ol l owi ng propert i es r eference dedi cat ed i mage f i l es. Note / / t hat r e l at i ve l i nks ar e al ways r e l at i ve t o t he l oc at i on of t he / / Component . j s of t he app, NOT t o t he l ocat i on of t he HTML f i l e t hat / / i s di spl ayed i n t he web browser ( t ypi cal l y: Fi or i Launchpad. ht ml ) . "f avI con" : "i mg/ f avi con. i co", " homeScr eenI conPhone" : " i mg/ 57_i Phone_Deskt op_ Launch. png", " homeScr eenI conPhone@2" : " i mg/ 114_i Phone- Ret i na_ Web_ Cl i p. png " , " homeScr eenI conTabl et " : " i mg/ 72_i Pad_Deskt op_L aunch. png" , " homeScr eenI conTabl et @2" : " i mg/ 144_i Pad_Ret i na_Web_Cl i p. png" , } }, (...) }) ;
7
Best Practices for Launchpad Apps The following best practices will help you develop your SAPUI5 apps so that they run smoothly in the SAP Fiori launchpad without any side effects that might be tricky to analyze:
Build your apps as self-contained SAPUI5 components. "Apps" in the SAP Fiori launchpad are effectively SAPUI5 components. The launchpad instantiates your application by loading the Component . j s file. For more information, see SAPUI5 Components in the SAPUI5 Developer Guide. Use an app-specific i ndex. ht ml file for standalone apps only. The appl i cat i on. j s and i ndex. ht ml files are no t loaded by the unified shell.
Declare configuration information, like the location of icons, and library dependencies in the component . j s configuration file. Do not use any global variables. If you cannot avoid using global variables, use qualified names to ensure uniqueness.
If you need an event bus, use the event bus of the component (sap. ui . cor e. Component . get Event Bus ). This avoids conflicting event names and makes sure that your listeners are automatically removed when the component is unloaded. For more information, see the JSDocs. Do no t use the global event bus ( sap. ui . get Cor e( ) . get Event Bus( ) ).
Register models on the root component or on single views of your apps. Example: t hi s. get Vi ew( ) . set Model ( " MyModel ", aModel ) ; Do no t use sap. ui . get Cor e( ) to register models. For more information, see Model View Controller in the SAPUI5 Developer Guide.
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 app several times in the launchpad. Do not rely on sap. ui . get Cor e( ) . byI d( ) for global location of elements. Always use local names get Vi ew( ) . byI d( ) and let SAPUI5 generate the IDs of views and components.
Use only the SAPUI5 APIs to manipulate the location hash. Do not read or write directly to wi ndow. l ocat i on. hash or wi ndow. l ocat i on . The SAP Fiori launchpad uses URL hashes for its own navigation. Direct manipulation of the location hash would interfere with the lauchpad navigation. For cross-app navigation, use the Cross-Application Navigation service. For more information on this service, see the JSDocs. For inner-app navigation, use the SAPUI5 routing API. For more information, see Routing in UI Components in the SAPUI5 documentation.
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 to a parent control in a JavaScript view) of the component are destroyed automatically. But controls which are not part of a parent, for example dialog instances, are not automatically destroyed. For example, you can ensure proper destruction by adding such controls to the corresponding view with the method addDependent of sap. ui . cor e. El ement . For more information, see Using Dialogs Defined as Fragments in the SAPUI5 documentation.
8
Avoid using sap. ui . l ocal Resour ces inside your Component . j s file. sap. ui . l ocal Resour ces registers a path relative to the main page ( Fi or i Launchpad. ht ml ). Components must not make implicit assumptions on this location. Avoid using j Quer y. sap. r egi st er Modul ePat h inside your Component . j s , as it creates a dependency to a specific platform.
9
How to Reference Resources from an SAPUI5 Component Referencing Resourc es Insid e your own Component Referencing JavaScript Modules To reference JavaScript modules of your own component, always use the full y 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. s ampl es . mysampl e ", and it is deployed as BSP application "myc ompany/ my_ sampl e_bsp", the module path " myc ompany. s ampl es . mysampl e " is mapped to the path "/ sap/ bc/ ui 5_ ui 5/ mycompany/ my_ sampl e_bsp ". The unified shell then locates your elements as follows (mapped module names and paths in bold blue):
Your component " mycompany.samples.mysample. Component " is retrieved from "/sap/bc/ui5_ui5/mycompany/my_sample_bsp/ Component . j s ". Your view "sap.samples.mysample. vi ew. S2" is retrieved from " /sap/bc/ui5_ui5/my_sample_bsp/ vi ew/ S2. vi ew. xml ".
You can then reference all modules contained in the component with the fully qualified module name using the r equi r e mechanism. For more information, see Modularization and Dependency Managemen t. For example, you can load a JavaScript file located in /sap/bc/ui5_ui5/my_sample_bsp/ mor ej s / MyJ SFi l e. j s using j Quer y. sap. r equi r e( " mycompany.samples.mysample. mor ej s. MyJ sFi l e" ) ;
Including Style Sheets To include custom style sheets, use the i ncl udes property of the component metadata as shown in the example in Component Metadata in the SAPUI5 documentation.
Referencing other f iles You might need to build a URI for a resource, for example when creating a resource model. You can do this by calculating the absolute path based on the relative module path of your own compon ent. Example: var ef f ect i veUr l = j Quer y. sap. getModul ePat h( " mycompany. sampl es. mys ampl e" ) + " / " + " i 18n/ i 18n. propert i es " var r esour ceBundl e = j Quer y. sap. r esour ces( { ur l : ef f ect i veUr l }) ;
10
Related Content You must include at least 3 references to SCN documents. Extending a Fiori App – Simple Use case – Part 3 SAPUI5 Components Application Best Practices
11
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 any form 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 components of other software vendors. National product specifications may vary. These materials are provided by SAP SE and its affiliated companies (“SAP SE Group”) for informational purposes only, without representation or warranty of any kind, and SAP SE Group shall not be liable for errors or omissions with respect to the materials. The only warranties for SAP SE 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 SE and other SAP SE products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP SE in Germany and other countries. Please see http://www.sap.com/corporate-en/legal/copyright/index.epx#trademar k
for additional trademark information and notices.
12
