SAP Fiori Launchpad for Developers Architecture Overview Applies to: 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. Authors: Steffen Hüster, Olivier Keimel Company: SAP SE Created on: 04 August 2014 Author Bio Steffen Hüster, 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 FioriLaunchpad.html. 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 selfcontained SAPUI5 components as described below. Embedding SAPUI5 Applications into the SAP Fiori Launchpad 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.js 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 qualified names for the applications modules (for example, component and views). For a comprehensive example, see Application Best Practices. File Structure The SAPUI5 component is defined in a file namedcomponent.js, which should be located in the root folder of your application. In an Eclipse project, it is typically located under src/main/webapp or WebContent. 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 resourcebundle titleresource favicon "homescreeniconphone", "homescreeniconphone@2", "homescreenicontablet", "homescreenicontablet@2" Description Path to the resource bundle that holds the translated app title. Example: i18n/i18n.properties Key of the app title text in the resource bundle. The title is typically displayed in the browser tab 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. 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 resolution 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.js 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 theincludes property. 6
Example The 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", } }, (...) }); 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 thecomponent.js file. For more information, see SAPUI5 Components in the SAPUI5 Developer Guide. Use an app-specificindex.html file for standalone apps only. Theapplication.js and index.html files are not loaded by the unified shell. Declare configuration information, like the location of icons, and library dependencies in the component.js 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.core.component.geteventbus). 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 not use the global event bus (sap.ui.getcore().geteventbus()). Register models on the root component or on single views of your apps. Example:this.getView().setModel("MyModel",aModel); Do not usesap.ui.getcore() 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 onsap.ui.getcore().byid() for global location of elements. Always use local namesgetview().byid() 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 towindow.location.hash or window.location. 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.core.element. For more information, see Using Dialogs Defined as Fragments in the SAPUI5 documentation. 8
Avoid usingsap.ui.localresources inside yourcomponent.js file. sap.ui.localresources registers a path relative to the main page (FioriLaunchpad.html). Components must not make implicit assumptions on this location. Avoid usingjquery.sap.registermodulepath inside your Component.js, as it creates a dependency to a specific platform. 9
How to Reference Resources from an SAPUI5 Component Referencing Resources Inside your own Component Referencing JavaScript Modules To 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 the path "/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): Your component "mycompany.samples.mysample.component" is retrieved from "/sap/bc/ui5_ui5/mycompany/my_sample_bsp/component.js". 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 using the 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 using jquery.sap.require("mycompany.samples.mysample.morejs.myjsfile"); Including Style Sheets To include custom style sheets, use the includes property of the component metadata as shown in the example in Component Metadata in the SAPUI5 documentation. Referencing other files 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 component. Example: var effectiveurl = jquery.sap.getmodulepath("mycompany.samples.mysample") + "/" + "i18n/i18n.properties" var resourcebundle = jquery.sap.resources({ url : effectiveurl }); 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#trademark for additional trademark information and notices. 12