SAP Fiori Toolkit February 2014
Copyright Copyright 2014 SAP AG. All rights reserved SAP Library document classification: PUBLIC 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. Microsoft, Windows, Excel, Outlook, PowerPoint, Silverlight, and Visual Studio are registered trademarks of Microsoft Corporation. IBM, DB2, DB2 Universal Database, System i, System i5, System p, System p5, System x, System z, System z10, z10, z/vm, z/os, OS/390, zenterprise, PowerVM, Power Architecture, Power Systems, POWER7, POWER6+, POWER6, POWER, PowerHA, purescale, PowerPC, BladeCenter, System Storage, Storwize, XIV, GPFS, HACMP, RETAIN, DB2 Connect, RACF, Redbooks, OS/2, AIX, Intelligent Miner, WebSphere, Tivoli, Informix, and Smarter Planet are trademarks or registered trademarks of IBM Corporation. Linux is the registered trademark of Linus Torvalds in the United States and other countries. Adobe, the Adobe logo, Acrobat, PostScript, and Reader are trademarks or registered trademarks of Adobe Systems Incorporated in the United States and other countries. Oracle and Java are registered trademarks of Oracle and its affiliates. UNIX, X/Open, OSF/1, and Motif are registered trademarks of the Open Group. Citrix, ICA, Program Neighborhood, MetaFrame, WinFrame, VideoFrame, and MultiWin are trademarks or registered trademarks of Citrix Systems Inc. HTML, XML, XHTML, and W3C are trademarks or registered trademarks of W3C, World Wide Web Consortium, Massachusetts Institute of Technology. Apple, App Store, ibooks, ipad, iphone, iphoto, ipod, itunes, Multi-Touch, Objective-C, Retina, Safari, Siri, and Xcode are trademarks or registered trademarks of Apple Inc. IOS is a registered trademark of Cisco Systems Inc. RIM, BlackBerry, BBM, BlackBerry Curve, BlackBerry Bold, BlackBerry Pearl, BlackBerry Torch, BlackBerry Storm, BlackBerry Storm2, BlackBerry PlayBook, and BlackBerry App World are trademarks or registered trademarks of Research in Motion Limited. Google App Engine, Google Apps, Google Checkout, Google Data API, Google Maps, Google Mobile Ads, Google Mobile Updater, Google Mobile, Google Store, Google Sync, Google Updater, Google Voice, Google Mail, Gmail, YouTube, Dalvik and Android are trademarks or registered trademarks of Google Inc. INTERMEC is a registered trademark of Intermec Technologies Corporation. Wi-Fi is a registered trademark of Wi-Fi Alliance. Bluetooth is a registered trademark of Bluetooth SIG Inc. Motorola is a registered trademark of Motorola Trademark Holdings LLC. Computop is a registered trademark of Computop Wirtschaftsinformatik GmbH. SAP, R/3, SAP NetWeaver, Duet, PartnerEdge, ByDesign, SAP BusinessObjects Explorer, StreamWork, SAP HANA, 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. Business Objects and the Business Objects logo, BusinessObjects, Crystal Reports, Crystal Decisions, Web Intelligence, Xcelsius, and other Business Objects products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of Business Objects Software Ltd. Business Objects is an SAP company. Sybase and Adaptive Server, ianywhere, Sybase 365, SQL Anywhere, and other Sybase products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of Sybase Inc. Sybase is an SAP company. Crossgate, m@gic EDDY, B2B 360, and B2B 360 Services are registered trademarks of Crossgate AG in Germany and other countries. Crossgate is an SAP company. All other product and service names mentioned are the trademarks of their respective companies. Data contained in this document serves informational purposes only. National product specifications may vary. These materials are subject to change without notice. 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.
Contents 1 Introduction... 1 2 Installing, Uninstalling and Upgrading... 2 2.1 Prerequisites... 2 2.2 Installing the Toolkit... 2 2.2.1 Language Support... 3 2.2.2 Installing the Toolkit on Eclipse Versions Higher than Juno... 3 2.3 Uninstalling the Toolkit... 3 2.4 Upgrading the Toolkit... 3 3 Creating a Starter Application Project... 4 3.1 Working with the Generated SAP Fiori Starter Application... 11 3.2 Running the SAPUI5 Application... 11 3.2.1 Running an Application using Mock Data... 11 4 Extending the Generated Application... 12 4.1 Creating New Extension Projects... 12 4.1.1 Changing the OData Service in the Extended Project... 13 4.2 Extending the Application... 14 4.2.1 Extending Views... 15 4.2.2 Extending Controllers... 17
SAP Fiori Toolkit 1 Introduction The SAP Fiori toolkit is a consumption tool for developers, part of the SAP NetWeaver Gateway productivity accelerator offering. SAP NetWeaver Gateway productivity accelerator (GWPA) provides Eclipse-based developer tools for creating OData-based applications. This toolkit is an Eclipse plug-in that simplifies the development process and the knowledge required to consume SAP business data via SAP NetWeaver Gateway. It supports the following: Generating SAP Fiori starter applications Extending an existing SAP Fiori application 1
2 Installing, Uninstalling and Upgrading 2.1 Prerequisites Before you can install the SAP Fiori toolkit, make sure you have the following: Eclipse Juno 4.2 HANA tools update site To add the update site: 1. Start Eclipse. 2. From the menu bar, choose Help > Install new software. The Available Software page is displayed. 3. Click Add. The Add Repository page is displayed. 4. In the Name field, enter a name for the repository. 5. In the Location field, enter https://tools.hana.ondemand.com/juno 6. Click OK. 7. Select the Contact all update sites during install to find required software checkbox. You must download the SAP Fiori toolkit installation file available at the SAP Developer Network site: SAP Fiori toolkit installation zip 2.2 Installing the Toolkit To install the tool: 1. Start Eclipse. 2. From the menu bar, choose Help > Install new software. The Available Software page is displayed. 3. Click Add, and then click Archive... 4. Browse for the installation zip file you downloaded and then click OK. 5. Select the SAP Fiori Toolkit checkbox. 6. Choose Next. The Install Details page is displayed. 7. Choose Next. The Review License page is displayed. 8. Choose the I accept the terms of the license agreements radio button to continue with the installation. 9. Choose Finish. The installation procedure begins. A security Warning is displayed. Choose OK. The Selection Needed page is displayed. 10. Select the localsigning certificate and choose OK. 11. On completion, Eclipse prompts you to restart. 12. Choose Yes. 13. When prompted, select the desired workspace location. Your toolkit installation is complete. 2
2.2.1 Language Support To enable the use of characters in languages other than English: 1. Navigate to the location where Eclipse is installed on your computer. 2. Open the eclipse.ini file for editing and add the following in a new line: -Dfile.encoding=UTF-8 3. Restart Eclipse. Your default encoding in eclipse is changed to UTF-8. 4. In Eclipse, select WIndow > Preferences > General > Workspace. 5. In the Text file encoding section, make sure UTF-8 is selected either as the default or as an option in the Other radio button. 2.2.2 Installing the Toolkit on Eclipse Versions Higher than Juno The installation process for the Fiori Toolkit on Eclipse versions higher than Juno (for example Kepler, Luna, etc) is the same as that described in section 2.1, but with additional prerequisites. Perform a new Eclipse installation in your system. Note: If the installation is not completely new, the toolkit installation will fail because of clashing Graphiti versions. Add an additional update site for the Graphiti plugin before starting the installation. 1. Start Eclipse. 2. From the menu bar, choose Help > Install new software. The Available Software page is displayed. 3. Click Add. The Add Repository page is displayed. 4. In the Name field, enter a name for the Graphiti plugin. 5. In the Location field, enter http://archive.eclipse.org/graphiti/updates/0.9.1 and click OK. 6. Select the Contact all update sites during install to find required software checkbox. 2.3 Uninstalling the Toolkit To uninstall the SAP Fiori toolkit: 1. Start Eclipse. 2. From the menu bar, choose Help > About Eclipse. The About Eclipse dialog box is displayed. 3. Choose Installation Details. 4. Select the Installed Software tab. The list of installed software components is displayed. 5. Select SAP Fiori Templates and choose Uninstall. The Uninstall Details page is displayed. 6. Choose Finish. The toolkit is uninstalled. 7. Restart Eclipse for the changes to take effect. 2.4 Upgrading the Toolkit To upgrade the tool: 1. Download an updated installation zipped file from the SCN page. 2. Follow the steps described in the Installing the Toolkit section. 3
3 Creating a Starter Application Project You can create a starter application based on a given OData service for SAP Fiori with entry points for custom development. To create your SAP Fiori starter application: 1. From the Eclipse menu bar, select File > New > Other. The Select a Wizard page is displayed. 2. Expand the OData Development node and select Starter Application Project. 4
3. Choose Next. The New Starter Application Project page is displayed. 4. In the Project name field, enter a name for your project. 5. From the Create new project for drop-down list, select SAP Fiori. 6. Choose Next. The Starter Application Templates for SAP Fiori page is displayed. 5
7. Select the template, Basic SAP Fiori Application. 8. Choose Next. The Location of OData Service page is displayed. 9. Select the OData service in one of the following ways: In the Service URL field, enter the desired service s URL, and then choose Go. Choose Catalog and select the desired service using the Service Catalog dialog. Select the File system radio button and browse for the relevant service metadata and service document. 6
10. Choose Next. The Application Customization page is displayed. 7
11. Under Containers, select Master to define the labels you want in master view at runtime. Label Containers Customization OData Configuration Explanation Specify the views in the template. Master Section Specifies the labels you want to define in the master view. It is the selected default view when the page opens. Details Section Specifies the labels you want to define in the details view. Specify the labels you want to use for the following: Title: The specified label is used as the title of the view. For example, Sales Orders Search: The specified label is used as the placeholder text within the search field. For example, search. Search tooltip: The specified text is used as the tooltip information for the search. For example, Search for SalesOrder. Define the service collection and entity properties you want the application to use. Based on OData Collection This option is selected by default when the Master Section is selected Collection Select the desired service collection from which to retrieve data. For example, SalesOrders. Note: The option, Based on OData Collection must always be selected when the Master Section is chosen. Based on Previous Navigation This option is selected by default, when you choose the Detail Section The Container and Navigation drop-down list-lists are populated according to your selection in the Master section. Note: Make sure that the specified navigation value is the same as the selected collection value in the Master Section. 8
Selected Collection The lower section shows the name of the collection selected in the OData Configuration section. Properties from the selected service collection appear as fields: Title: The specified label is used as the title of the property. For example, Customer Name. Numeric Attribute: The specified number is used as a numeric attribute in the Master Section. For example, TotalAmount. Units Attribute: The specified unit is used as a unit attribute in the Master Section. For example, Currency. Attribute 1: A placholder for specifying an additional property. Attribute 2: A placholder for specifying an additional property Search Field: The specified label is used as the search name. The field name changes according to the properties of the selected collection. Note: If the specified values for the properties are long they can exceed the allocated width in the application view. You can manually resolve this issue, for example, by minimizing the font size. 9
12. Under Containers, select the Detail Section. 13. In the Customization section, enter the labels you want in the Detail view of the application. 14. In the OData Configuration section, select Master Section from the Container drop-down list. 15. From the Navigation drop-down list, select the collection you chose in the Master section (SalesOrder). In each of the fields, from the drop-down list, select the property to be displayed in the application. 16. Choose Finish. An Eclipse project with the application code is created in your workspace. Note: The application is generated with placeholder labels if you do not define an OData service, a collection, or configure the properties to be shown in your application. You can manually add the information by editing the code of the generated application. 10
3.1 Working with the Generated SAP Fiori Starter Application The generated project is an Eclipse Web project, which references the required resources to help in writing HTML and JavaScript code. This also includes a reference to the JavaScript library that enables Eclipse to detect syntax errors and to provide intellisense. The main folder of the generated project is the WebContent folder. This folder contains all the HTML, JavaScript, and CSS files required to run the Web application. You can modify and extend the generated code for the SAP Fiori starter application to suit your needs. Below are examples of generated projects for the SAP Fiori applications, and a description of possible customizations and extensions. 3.2 Running the SAPUI5 Application Before you can run the generated SAPUI5 application, you must edit the index.html file to set the location of the SAPUI5 libraries. To set the location of the SAPUI5 libraries: 1. Open the index.html file located in the WebContent directory. 2. Search for the following line in the Script tag: src="/resources/sap-ui-core.js" 3. Replace the text in quotation marks with the link to the location where the files for SAPUI5 are located. Note: If you download the SAPUI5 library and deploy it with your application, the location should indicate the relative path of the library in your application. Alternatively, you can set this location with the URL of a remote location hosting this libraries. 4. In the component.js file of the extension project, search for the following text: url: jquery.sap.getmodulepath("{some Project Name}") + "/../{parent project url}" // provide parent project url 5. Change the {parent project url} to the actual URL for the relevant parent project. 3.2.1 Running an Application using Mock Data You can use mock data obtained from the SAPUI5 Mock Server. To use mock data: 1. Open the generated started application. 2. Open the Component.js file located within the WebContent folder. 3. Uncomment line 77: var busemockdata = ( true === responderon 4. Comment line 78: var busemockdata = false; 5. Create a new folder within the WebContent folder called model. 6. Copy the desired metadata.xml file into the model folder. 7. To add data to the service, add the desired.json files to the model folder. 11
4 Extending the Generated Application You can extend your SAP Fiori application by creating new extension projects and then adding extensions to these projects. 4.1 Creating New Extension Projects Extension projects are used to change the functionality or appearance of the parent project. To create a new extension project: 1. Open Eclipse. 2. On the Project Explorer (in Web perspective), right-click on the project for which you want to create an extension project and select Create SAP Fiori Extension Project. The New SAP Fiori Extension Project page is displayed. 3. In the Parent Project field, browse for the desired parent project. Note: If the parent project is not an SAP Fiori project, an error message is displayed. Before you continue, make sure your project contains the Component.js files and that it has a UI5 nature. 4. In the Extension Project Name field, enter the desired name for the new extension project. 5. Choose Finish. The new extension project is created and can be visible in the Project Explorer. 12
4.1.1 Changing the OData Service in the Extended Project To change the OData service used by the extended project: 1. Open Eclipse. 2. On the Project Explorer, right-click on the project for which you want to create an extension project and select Create SAP Fiori Extension Project. The New SAP Fiori Extension Project page is displayed. 3. In the Parent Project field, browse for the desired parent project. 4. In the Extension Project Name field, enter the desired name for the new extension project. 5. Select the Replace the parent application project s OData service with a new OData service checkbox. The current OData service details are displayed. 6. Choose Next. The Location of OData Service page is displayed. 13
7. Select the OData service with which you want to replace the current OData service. in one of the following ways: In the Service URL field, enter the desired service s URL, and then choose Go. Select the File system radio button and browse for the relevant service metadata and service document. Note: The new OData service must be compatible (similar metadata, similar operations, as well as any extensions) with the OData service of the parent project. When the service is validated, its details are displayed. 8. Choose Finish. An Eclipse project with the application code is created in your workspace. Notice that in the Component.js file of the extended project, the service name and URL are of the new selected service. 4.2 Extending the Application You can create extensions to perform one of the following: Replace an existing view with a new view in an existing project. Add logic to an existing view using an extension point which was defined in the Parent Project. Change control visibility. Extend an existing controller with new logic. Once the extensions have been created, a reference to them is created in the Component.js file of the extended project. Note: If you delete a file that is being referenced from the component.js file or rename it, the application will not work properly. Make sure you delete the reference or update the file name on the component.js file. 14
4.2.1 Extending Views This option enables you to modify the view of the original application. To extend a view: 1. In the Project Explorer, (in Web perspective) right-click on the desired extended project and choose Add SAP Fiori Extension. The SAP Fiori Extension Wizard is displayed. 2. Select the Modify a View radio button. 3. From the View Name drop-down list, select the view in the original application you wish to extend. 4. Click Next. The SAP Fiori Extension Wizard - Modify View Options page is displayed. 5. From this page you can replace or extend a view, and hide controls. 15
4.2.1.1 Replacing an Existing View This option enables you to replace a specific view in the parent project with a new view. To replace a view: 1. Select the Replace View radio button. 2. Select the Original View radio button to edit the view based on the original view, Or; Select the Empty View radio button to replace the view with an entirely new one. 3. Click Finish. The view is added to the extended project under WebContent > view and it is opened in the workspace. 4.2.1.2 Adding Extension Points This option enables you extend a view using an extension point. To extend a view, extension points must have previously been defined in the parent project. To extend a view using extension points: 1. Select the Extend View radio button. 2. From the Extension Point drop-down list, select the desired extension point. 3. Click Finish. The extension point is added to the extended project under WebContent > view and it is opened in the workspace. 4. Edit the fragment.xml file to add the desired extensibility. 16
4.2.1.3 Hiding Controls This option enables you to hide a specific control in the parent application. Note: Only controls whose Visible property is defined in the parent project as True can be hidden. If the Visible property does not exist, you cannot hide the control. To check if the control contains the Visible property, check the View file of the parent project. To hide a control: 1. Select the Hide Control radio button. 2. From the Control ID drop-down list, select the specific control you want to hide. Note: Only controls whose ID was defined in the parent project are visible in the list. 3. Click Finish. 4.2.2 Extending Controllers This option enables you to add code to a controller of the parent application. To extend a controller: 1. In the Project Explorer, right-click on the desired extended project and choose Add SAP Fiori Extension. The SAP Fiori Extension Wizard is displayed. 2. Select the Extend Controller radio button. 3. From the Controller Name drop-down list, select the controller you wish to extend. 4. Click Finish. The controller is added to the extended project under WebContent > view and it is opened in the workspace. 17